80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
Examples
|
|
========
|
|
This directory contains a few example programs which illustrate how one can set
|
|
up their own projects to use LLVM's libc, either as an overlay or as the only
|
|
libc in their projects. See the
|
|
[the usage mode document](https://libc.llvm.org/usage_modes.html) for more
|
|
information about the different modes in which one can build and use the libc.
|
|
|
|
Building the Examples
|
|
=====================
|
|
Each example has its own directory which contain the source code and the CMake
|
|
build set up. To build an example, create a directory named `build` in the
|
|
example's directory:
|
|
|
|
```bash
|
|
cd <example directory>
|
|
mkdir build
|
|
cd build
|
|
```
|
|
|
|
Each example can be built to use the libc in either
|
|
[the overlay mode](https://libc.llvm.org/overlay_mode.html) or the
|
|
[full build mode](https://libc.llvm.org/fullbuild_mode.html). The CMake
|
|
configure step differs slightly depending on the mode you want to use the libc
|
|
in.
|
|
|
|
Building against an overlay libc
|
|
--------------------------------
|
|
|
|
Before you can link an example against the overlay libc, you will have to
|
|
install it. See [the documentation of the overlay mode](https://libc.llvm.org/overlay_mode.html)
|
|
to learn how to install the libc's overlay static archive named `libllvmlibc.a`.
|
|
Once installed, to build an example against it, you have specify the directory
|
|
in which the static archive is installed with the option
|
|
`LIBC_OVERLAY_ARCHIVE_DIR`:
|
|
|
|
```bash
|
|
cmake ../ -G <GEN> \
|
|
-DLIBC_OVERLAY_ARCHIVE_DIR=<dir in which libc is installed>
|
|
```
|
|
|
|
Next, if `Ninja` is used for `<GEN>`, you can build the example as follows:
|
|
|
|
```bash
|
|
ninja <example name>
|
|
```
|
|
|
|
Building against a full libc
|
|
----------------------------
|
|
|
|
Before you can link an example against the full libc, you will have to first
|
|
install it. See [the documentation of the full build mode](https://libc.llvm.org/fullbuild_mode.html)
|
|
to learn how to install a full libc along with the other LLVM toolchain pieces
|
|
like `clang`, `lld` and `compiler-rt`. The CMake build for the examples will
|
|
assume that you have all of these components installed in a special sysroot
|
|
(see decription of the `--sysroot` option
|
|
[here](https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html).) Once you
|
|
have installed them, you have to inform CMake that we are linking against the
|
|
full libc as follows:
|
|
|
|
```bash
|
|
cmake ../ -G <GEN> -DLIBC_FULLBUILD=ON \
|
|
-DCMAKE_SYSROOT=<SYSROOT> \
|
|
-DCMAKE_C_COMPILER=<SYSROOT>/bin/clang \
|
|
-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY
|
|
```
|
|
|
|
`<SYSROOT>` is the path to the sysroot directory you have set up while
|
|
installing the full libc. The option
|
|
`-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY` tells CMake to not attempt
|
|
linking full executables against shared libraries. We have to use this as LLVM's
|
|
libc does not yet have support for shared libraries and dynamic linking. After
|
|
the above `cmake` command, assuming `Ninja` was used for `<GEN>`, you can build
|
|
the example as follows:
|
|
|
|
|
|
```bash
|
|
ninja <example name>
|
|
```
|