libc/docs/build_and_test.rst

   1 .. _build_and_test:
   2
   3 =============================
   4 Building and Testing the libc
   5 =============================
   6
   7 Build modes
   8 ===========
   9
  10 The 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:`fullbuild_mode` 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
  41    #. API verification test - See :ref:`api_test` for more information about
  42       the API test. It can be run by the command:
  43
  44       .. code-block:: sh
  45
  46         $> ninja libc-api-test
  47
  48 Building with VSCode
  49 ====================
  50
  51 As a quickstart to using VSCode for development, install the cmake extension
  52 and put the following in your settings.json file:
  53
  54 .. code-block:: javascript
  55
  56    {
  57      "cmake.sourceDirectory": "${workspaceFolder}/llvm",
  58      "cmake.configureSettings": {
  59          "LLVM_ENABLE_PROJECTS" : "libc",
  60          "LLVM_LIBC_FULL_BUILD" : true,
  61          "LLVM_ENABLE_SPHINX" : true,
  62          "LIBC_INCLUDE_DOCS" : true
  63      }
  64    }
  65
  66 Building with Bazel
  67 ===================
  68
  69 #. To build with Bazel, use the following command:
  70
  71   .. code-block:: sh
  72
  73     $> bazel build --config=generic_clang @llvm-project//libc/...
  74
  75 #. To run the unit tests with bazel, use the following command:
  76
  77   .. code-block:: sh
  78
  79     $> bazel test --config=generic_clang @llvm-project//libc/...
  80
  81 #. 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>`_.