moar docs

Author: nickdesaulniers

libc/docs/full_cross_build.rst

@@ -59,13 +59,15 @@ Below is the CMake command to configure the standalone crossbuild of the libc.
   $> cd build
   $> C_COMPILER=<C compiler> # For example "clang"
   $> CXX_COMPILER=<C++ compiler> # For example "clang++"
+  $> KERNEL_HEADERS=<path/to/built/linux/kernel/headers>
   $> cmake ../runtimes  \
      -G Ninja \
      -DLLVM_ENABLE_RUNTIMES=libc  \
      -DCMAKE_C_COMPILER=$C_COMPILER \
      -DCMAKE_CXX_COMPILER=$CXX_COMPILER \
      -DLLVM_LIBC_FULL_BUILD=ON \
      -DLIBC_TARGET_TRIPLE=<Your target triple> \
+     -DLIBC_KERNEL_HEADERS=$KERNEL_HEADERS \
      -DCMAKE_BUILD_TYPE=<Release|Debug>
 
 We will go over the special options passed to the ``cmake`` command above.
@@ -77,6 +79,10 @@ We will go over the special options passed to the ``cmake`` command above.
 * **The target triple** - This is the target triple of the target for which
   we are building the libc. For example, for a Linux 32-bit Arm target,
   one can specify it as ``arm-linux-eabi``.
+* **The path to the kernel headers** - (Optional) Necessary when targeting
+  Linux. The Linux kernel headers are architecture specific and should be built
+  from source. See :ref:`linux_headers` section for how to build the Linux
+  kernel headers from source.
 
 Build step
 ----------
@@ -116,6 +122,7 @@ CMake configure step
      -DLLVM_ENABLE_PROJECTS=clang \
      -DLLVM_ENABLE_RUNTIMES=libc \
      -DLLVM_LIBC_FULL_BUILD=ON \
+     -DLIBC_KERNEL_HEADERS=$KERNEL_HEADERS \
      -DLLVM_RUNTIME_TARGETS=$TARGET_TRIPLE \
      -DCMAKE_BUILD_TYPE=Debug
 

libc/docs/full_host_build.rst

@@ -28,6 +28,10 @@ development. In this we've set the Ninja generator, set the build type to
 "Debug", and enabled the Scudo allocator. This build also enables generating the
 documentation and verbose cmake logging, which are useful development features.
 
+If targeting Linux, see :ref:`linux_headers` for how to build the Linux kernel
+headers from source, which llvm-libc will depend on. If not targeting Linux,
+the below cmake variable ``LIBC_KERNEL_HEADERS`` should be omitted.
+
 .. note::
    if your build fails with an error saying the compiler can't find
    ``<asm/unistd.h>`` or similar then you're probably missing the symlink from
@@ -50,6 +54,7 @@ documentation and verbose cmake logging, which are useful development features.
       -DLLVM_LIBC_FULL_BUILD=ON \
       -DCMAKE_BUILD_TYPE=Debug \
       -DLLVM_LIBC_INCLUDE_SCUDO=ON \
+      -DLLVM_LIBC_KERNEL_HEADERS=/path/to/kernel/headers/ \
       -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
       -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
@@ -133,6 +138,7 @@ allocator for LLVM-libc.
       -DCMAKE_CXX_COMPILER=clang++ \
       -DLLVM_LIBC_FULL_BUILD=ON \
       -DLLVM_LIBC_INCLUDE_SCUDO=ON \
+      -DLLVM_LIBC_KERNEL_HEADERS=/path/to/kernel/headers/ \
       -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
       -DCOMPILER_RT_BUILD_GWP_ASAN=OFF                       \
       -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF        \
@@ -171,6 +177,8 @@ toolchain with which you can build practical/real-world C applications. See
 `<https://github.com/llvm/llvm-project/tree/main/libc/examples>`_ for examples
 of how to start using this new toolchain.
 
+.. _linux_headers:
+
 Linux Headers
 =============
 
@@ -183,7 +191,9 @@ Linux headers in your sysroot.  Let's build them from source.
    $> make LLVM=1 INSTALL_HDR_PATH=/path/to/sysroot -C /tmp/linux headers_install
 
 The headers can be built to target non-host architectures by adding the
-``ARCH={arm|arm64|i386}`` to the above invocation of ``make``.
+``ARCH={arm|arm64|i386}`` to the above invocation of ``make``. Then you should
+set the cmake variable `-DLIBC_KERNEL_HEADERS=/path/to/sysroot` when
+configuring llvm-libc.
 
 Using your newly built libc
 ===========================

libc/docs/overlay_mode.rst

@@ -40,6 +40,7 @@ building it with the following cmake command:
   $> mkdir build
   $> cd build
   $> cmake ../runtimes -G Ninja -DLLVM_ENABLE_RUNTIMES="libc"  \
+     -LIBC_USE_HOST_KERNEL_HEADERS=ON \
      -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_BUILD_TYPE=<Debug|Release>                    \  # Select build type
      -DCMAKE_INSTALL_PREFIX=<Your prefix of choice>           # Optional
@@ -78,6 +79,7 @@ performance possible.
 
   $> cmake ../llvm -G Ninja -DLLVM_ENABLE_PROJECTS="clang" \
      -DLLVM_ENABLE_RUNTIMES="libc"  \  # libc is listed as runtime and not as a project
+     -DLIBC_USE_HOST_KERNEL_HEADERS=ON \
      -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_BUILD_TYPE=<Debug|Release>                    \  # Select build type
      -DCMAKE_INSTALL_PREFIX=<Your prefix of choice>           # Optional