111 lines · plain
1.. _build_and_test:2 3=============================4Building and Testing the libc5=============================6 7Build modes8===========9 10The libc can be built and tested in two different modes:11 12#. **The overlay mode** - In this mode, one uses the static archive from LLVM's13 libc along with the system libc. See :ref:`overlay_mode` for more details14 on building and using the libc in this mode. You can only run the libc15 unittests in this mode. To run them, one simply does:16 17 .. code-block:: sh18 19 $> ninja check-libc20 21 Note that, unittests for only those functions which are part of the overlay22 static archive will be run with the above command.23 24#. **The full build mode** - In this mode, the libc is used as the only libc25 for the user's application. See :ref:`full_host_build` for more details on26 building and using the libc in this mode. Once configured for a full libc27 build, you can run three kinds of tests:28 29 #. Unit tests - You can run unittests by the command:30 31 .. code-block:: sh32 33 $> ninja check-libc34 35 #. Integration tests - You can run integration tests by the command:36 37 .. code-block:: sh38 39 $> ninja libc-integration-tests40 41Building with VSCode42====================43 44As a quickstart to using VSCode for development, install the cmake extension45and put the following in your settings.json file:46 47.. code-block:: javascript48 49 {50 "cmake.sourceDirectory": "${workspaceFolder}/runtimes",51 "cmake.configureSettings": {52 "LLVM_ENABLE_RUNTIMES" : ["libc", "compiler-rt"],53 "LLVM_LIBC_FULL_BUILD" : true,54 "LLVM_ENABLE_SPHINX" : true,55 "LIBC_INCLUDE_DOCS" : true,56 "LLVM_LIBC_INCLUDE_SCUDO" : true,57 "COMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC": true,58 "COMPILER_RT_BUILD_GWP_ASAN" : false,59 "COMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED" : false,60 "CMAKE_EXPORT_COMPILE_COMMANDS" : true,61 "LIBC_CMAKE_VERBOSE_LOGGING" : true62 }63 }64 65Building with Bazel66===================67 68#. To build with Bazel, use the following command:69 70 .. code-block:: sh71 72 $> bazel build --config=generic_clang @llvm-project//libc/...73 74#. To run the unit tests with bazel, use the following command:75 76 .. code-block:: sh77 78 $> bazel test --config=generic_clang @llvm-project//libc/...79 80#. The bazel target layout of `libc` is located at: `utils/bazel/llvm-project-overlay/libc/BUILD.bazel <https://github.com/llvm/llvm-project/tree/main/utils/bazel/llvm-project-overlay/libc/BUILD.bazel>`_.81 82Building in a container for a different architecture83====================================================84 85`Podman <https://podman.io/>`_ can be used together with86`QEMU <https://www.qemu.org/>`_ to run container images built for architectures87other than the host's. This can be used to build and test the libc on other88supported architectures for which you do not have access to hardware. It can89also be used if the hardware is slower than emulation of its architecture on a90more powerful machine under a different architecture.91 92As an example, to build and test in a container for 32-bit Arm:93 94#. To install the necessary packages on Arch Linux:95 96 .. code-block:: sh97 98 $> pacman -S podman qemu-user-static qemu-user-static-binfmt \99 qemu-system-arm100 101#. To run Bash interactively in an Ubuntu 22.04 container for 32-bit Arm and102 bind-mount an existing checkout of llvm-project on the host:103 104 .. code-block:: sh105 106 $> podman run -it \107 -v </host/path/to/llvm-project>:</container/path/to/llvm-project> \108 --arch arm docker.io/ubuntu:jammy bash109 110#. Install necessary packages, invoke CMake, build, and run tests.111