19145bf13SSiva Chandra ReddyExamples 29145bf13SSiva Chandra Reddy======== 39145bf13SSiva Chandra ReddyThis directory contains a few example programs which illustrate how one can set 49145bf13SSiva Chandra Reddyup their own projects to use LLVM's libc, either as an overlay or as the only 59145bf13SSiva Chandra Reddylibc in their projects. See the 69145bf13SSiva Chandra Reddy[the usage mode document](https://libc.llvm.org/usage_modes.html) for more 79145bf13SSiva Chandra Reddyinformation about the different modes in which one can build and use the libc. 89145bf13SSiva Chandra Reddy 99145bf13SSiva Chandra ReddyBuilding the Examples 109145bf13SSiva Chandra Reddy===================== 119145bf13SSiva Chandra ReddyEach example has its own directory which contain the source code and the CMake 129145bf13SSiva Chandra Reddybuild set up. To build an example, create a directory named `build` in the 139145bf13SSiva Chandra Reddyexample's directory: 149145bf13SSiva Chandra Reddy 159145bf13SSiva Chandra Reddy```bash 16086757a4SSiva Chandra Reddycd <example directory> 17086757a4SSiva Chandra Reddymkdir build 18086757a4SSiva Chandra Reddycd build 199145bf13SSiva Chandra Reddy``` 209145bf13SSiva Chandra Reddy 219145bf13SSiva Chandra ReddyEach example can be built to use the libc in either 229145bf13SSiva Chandra Reddy[the overlay mode](https://libc.llvm.org/overlay_mode.html) or the 239145bf13SSiva Chandra Reddy[full build mode](https://libc.llvm.org/fullbuild_mode.html). The CMake 249145bf13SSiva Chandra Reddyconfigure step differs slightly depending on the mode you want to use the libc 259145bf13SSiva Chandra Reddyin. 269145bf13SSiva Chandra Reddy 279145bf13SSiva Chandra ReddyBuilding against an overlay libc 289145bf13SSiva Chandra Reddy-------------------------------- 299145bf13SSiva Chandra Reddy 309145bf13SSiva Chandra ReddyBefore you can link an example against the overlay libc, you will have to 319145bf13SSiva Chandra Reddyinstall it. See [the documentation of the overlay mode](https://libc.llvm.org/overlay_mode.html) 329145bf13SSiva Chandra Reddyto learn how to install the libc's overlay static archive named `libllvmlibc.a`. 339145bf13SSiva Chandra ReddyOnce installed, to build an example against it, you have specify the directory 349145bf13SSiva Chandra Reddyin which the static archive is installed with the option 359145bf13SSiva Chandra Reddy`LIBC_OVERLAY_ARCHIVE_DIR`: 369145bf13SSiva Chandra Reddy 379145bf13SSiva Chandra Reddy```bash 383d2165f7SSiva Chandra Reddycmake ../ -G <GEN> \ 399145bf13SSiva Chandra Reddy -DLIBC_OVERLAY_ARCHIVE_DIR=<dir in which libc is installed> 409145bf13SSiva Chandra Reddy``` 419145bf13SSiva Chandra Reddy 429145bf13SSiva Chandra ReddyNext, if `Ninja` is used for `<GEN>`, you can build the example as follows: 439145bf13SSiva Chandra Reddy 449145bf13SSiva Chandra Reddy```bash 453d2165f7SSiva Chandra Reddyninja <example name> 469145bf13SSiva Chandra Reddy``` 479145bf13SSiva Chandra Reddy 489145bf13SSiva Chandra ReddyBuilding against a full libc 499145bf13SSiva Chandra Reddy---------------------------- 509145bf13SSiva Chandra Reddy 519145bf13SSiva Chandra ReddyBefore you can link an example against the full libc, you will have to first 529145bf13SSiva Chandra Reddyinstall it. See [the documentation of the full build mode](https://libc.llvm.org/fullbuild_mode.html) 539145bf13SSiva Chandra Reddyto learn how to install a full libc along with the other LLVM toolchain pieces 549145bf13SSiva Chandra Reddylike `clang`, `lld` and `compiler-rt`. The CMake build for the examples will 559145bf13SSiva Chandra Reddyassume that you have all of these components installed in a special sysroot 569145bf13SSiva Chandra Reddy(see decription of the `--sysroot` option 579145bf13SSiva Chandra Reddy[here](https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html).) Once you 589145bf13SSiva Chandra Reddyhave installed them, you have to inform CMake that we are linking against the 599145bf13SSiva Chandra Reddyfull libc as follows: 609145bf13SSiva Chandra Reddy 619145bf13SSiva Chandra Reddy```bash 62*fda04b1cSRajveer Singh Bharadwajcmake ../ -G <GEN> -DLLVM_LIBC_FULL_BUILD=ON \ 639145bf13SSiva Chandra Reddy -DCMAKE_SYSROOT=<SYSROOT> \ 649145bf13SSiva Chandra Reddy -DCMAKE_C_COMPILER=<SYSROOT>/bin/clang \ 659145bf13SSiva Chandra Reddy -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY 669145bf13SSiva Chandra Reddy``` 679145bf13SSiva Chandra Reddy 689145bf13SSiva Chandra Reddy`<SYSROOT>` is the path to the sysroot directory you have set up while 699145bf13SSiva Chandra Reddyinstalling the full libc. The option 709145bf13SSiva Chandra Reddy`-DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY` tells CMake to not attempt 719145bf13SSiva Chandra Reddylinking full executables against shared libraries. We have to use this as LLVM's 729145bf13SSiva Chandra Reddylibc does not yet have support for shared libraries and dynamic linking. After 739145bf13SSiva Chandra Reddythe above `cmake` command, assuming `Ninja` was used for `<GEN>`, you can build 749145bf13SSiva Chandra Reddythe example as follows: 759145bf13SSiva Chandra Reddy 769145bf13SSiva Chandra Reddy 779145bf13SSiva Chandra Reddy```bash 783d2165f7SSiva Chandra Reddyninja <example name> 799145bf13SSiva Chandra Reddy``` 80