xref: /llvm-project/libc/docs/build_and_test.rst (revision 692c77f2af133874f18942fe8c32f0f072bfc02b) 
1.. _build_and_test:
2
3=============================
4Building and Testing the libc
5=============================
6
7Build modes
8===========
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's
13   libc along with the system libc. See :ref:`overlay_mode` for more details
14   on building and using the libc in this mode. You can only run the libc
15   unittests in this mode. To run them, one simply does:
16
17   .. code-block:: sh
18
19     $> ninja check-libc
20
21   Note that, unittests for only those functions which are part of the overlay
22   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 libc
25   for the user's application. See :ref:`full_host_build` for more details on
26   building and using the libc in this mode. Once configured for a full libc
27   build, you can run three kinds of tests:
28
29   #. Unit tests - You can run unittests by the command:
30
31      .. code-block:: sh
32
33        $> ninja check-libc
34
35   #. Integration tests - You can run integration tests by the command:
36
37      .. code-block:: sh
38
39        $> ninja libc-integration-tests
40
41Building with VSCode
42====================
43
44As a quickstart to using VSCode for development, install the cmake extension
45and put the following in your settings.json file:
46
47.. code-block:: javascript
48
49   {
50     "cmake.sourceDirectory": "${workspaceFolder}/llvm",
51     "cmake.configureSettings": {
52         "LLVM_ENABLE_PROJECTS" : "libc",
53         "LLVM_LIBC_FULL_BUILD" : true,
54         "LLVM_ENABLE_SPHINX" : true,
55         "LIBC_INCLUDE_DOCS" : true
56     }
57   }
58
59Building with Bazel
60===================
61
62#. To build with Bazel, use the following command:
63
64  .. code-block:: sh
65
66    $> bazel build --config=generic_clang @llvm-project//libc/...
67
68#. To run the unit tests with bazel, use the following command:
69
70  .. code-block:: sh
71
72    $> bazel test --config=generic_clang @llvm-project//libc/...
73
74#. 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>`_.
75
76Building in a container for a different architecture
77====================================================
78
79`Podman <https://podman.io/>`_ can be used together with
80`QEMU <https://www.qemu.org/>`_ to run container images built for architectures
81other than the host's. This can be used to build and test the libc on other
82supported architectures for which you do not have access to hardware. It can
83also be used if the hardware is slower than emulation of its architecture on a
84more powerful machine under a different architecture.
85
86As an example, to build and test in a container for 32-bit Arm:
87
88#. To install the necessary packages on Arch Linux:
89
90   .. code-block:: sh
91
92     $> pacman -S podman qemu-user-static qemu-user-static-binfmt \
93        qemu-system-arm
94
95#. To run Bash interactively in an Ubuntu 22.04 container for 32-bit Arm and
96   bind-mount an existing checkout of llvm-project on the host:
97
98   .. code-block:: sh
99
100     $> podman run -it \
101        -v </host/path/to/llvm-project>:</container/path/to/llvm-project> \
102        --arch arm docker.io/ubuntu:jammy bash
103
104#. Install necessary packages, invoke CMake, build, and run tests.
105