libc/examples/README.md

   1 Examples
   2 ========
   3 This directory contains a few example programs which illustrate how one can set
   4 up their own projects to use LLVM's libc, either as an overlay or as the only
   5 libc in their projects. See the
   6 [the usage mode document](https://libc.llvm.org/usage_modes.html) for more
   7 information about the different modes in which one can build and use the libc.
   8
   9 Building the Examples
  10 =====================
  11 Each example has its own directory which contain the source code and the CMake
  12 build set up. To build an example, create a directory named `build` in the
  13 example's directory:
  14
  15 ```bash
  16 cd <example directory>
  17 mkdir build
  18 cd build
  19 ```
  20
  21 Each example can be built to use the libc in either
  22 [the overlay mode](https://libc.llvm.org/overlay_mode.html) or the
  23 [full build mode](https://libc.llvm.org/fullbuild_mode.html). The CMake
  24 configure step differs slightly depending on the mode you want to use the libc
  25 in.
  26
  27 Building against an overlay libc
  28 --------------------------------
  29
  30 Before you can link an example against the overlay libc, you will have to
  31 install it. See [the documentation of the overlay mode](https://libc.llvm.org/overlay_mode.html)
  32 to learn how to install the libc's overlay static archive named `libllvmlibc.a`.
  33 Once installed, to build an example against it, you have specify the directory
  34 in which the static archive is installed with the option
  35 `LIBC_OVERLAY_ARCHIVE_DIR`:
  36
  37 ```bash
  38 cmake ../ -G <GEN>  \
  39   -DLIBC_OVERLAY_ARCHIVE_DIR=<dir in which libc is installed>
  40 ```
  41
  42 Next, if `Ninja` is used for `<GEN>`, you can build the example as follows:
  43
  44 ```bash
  45 ninja <example name>
  46 ```
  47
  48 Building against a full libc
  49 ----------------------------
  50
  51 Before you can link an example against the full libc, you will have to first
  52 install it. See [the documentation of the full build mode](https://libc.llvm.org/fullbuild_mode.html)
  53 to learn how to install a full libc along with the other LLVM toolchain pieces
  54 like `clang`, `lld` and `compiler-rt`. The CMake build for the examples will
  55 assume that you have all of these components installed in a special sysroot
  56 (see decription of the `--sysroot` option
  57 [here](https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html).) Once you
  58 have installed them, you have to inform CMake that we are linking against the
  59 full libc as follows:
  60
  61 ```bash
  62 cmake ../ -G <GEN> -DLIBC_FULLBUILD=ON    \
  63   -DCMAKE_SYSROOT=<SYSROOT>               \
  64   -DCMAKE_C_COMPILER=<SYSROOT>/bin/clang  \
  65   -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY
  66 ```
  67
  68 `<SYSROOT>` is the path to the sysroot directory you have set up while
  69 installing the full libc. The option
  70 `-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY` tells CMake to not attempt
  71 linking full executables against shared libraries. We have to use this as LLVM's
  72 libc does not yet have support for shared libraries and dynamic linking. After
  73 the above `cmake` command, assuming `Ninja` was used for `<GEN>`, you can build
  74 the example as follows:
  75
  76
  77 ```bash
  78 ninja <example name>
  79 ```