1.. _ContributingToLibcxx: 2 3====================== 4Contributing to libc++ 5====================== 6 7This file contains notes about various tasks and processes specific to contributing 8to libc++. If this is your first time contributing, please also read `this document 9<https://www.llvm.org/docs/Contributing.html>`__ on general rules for contributing to LLVM. 10 11For libc++, please make sure you follow `these instructions <https://www.llvm.org/docs/Phabricator.html#requesting-a-review-via-the-command-line>`_ 12for submitting a code review from the command-line using ``arc``, since we have some 13automation (e.g. CI) that depends on the review being submitted that way. 14 15If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel 16on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__. 17 18Looking for pre-existing reviews 19================================ 20 21Before you start working on any feature, please take a look at the open reviews 22to avoid duplicating someone else's work. You can do that by going to the website 23where code reviews are held, `Differential <https://reviews.llvm.org/differential>`__, 24and clicking on ``Libc++ Open Reviews`` in the sidebar to the left. If you see 25that your feature is already being worked on, please consider chiming in instead 26of duplicating work! 27 28Pre-commit check list 29===================== 30 31Before committing or creating a review, please go through this check-list to make 32sure you don't forget anything: 33 34- Do you have tests for every public class and/or function you're adding or modifying? 35- Did you update the synopsis of the relevant headers? 36- Did you update the relevant files to track implementation status (in ``docs/Status/``)? 37- Did you mark all functions and type declarations with the :ref:`proper visibility macro <visibility-macros>`? 38- If you added a header: 39 40 - Did you add it to ``include/module.modulemap.in``? 41 - Did you add it to ``include/CMakeLists.txt``? 42 - If it's a public header, did you add a test under ``test/libcxx`` that the new header defines ``_LIBCPP_VERSION``? See ``test/libcxx/algorithms/version.pass.cpp`` for an example. NOTE: This should be automated. 43 - If it's a public header, did you update ``utils/generate_header_inclusion_tests.py``? 44 45- Did you add the relevant feature test macro(s) for your feature? Did you update the ``generate_feature_test_macro_components.py`` script with it? 46- Did you run the ``libcxx-generate-files`` target and verify its output? 47 48The review process 49================== 50 51After uploading your patch, you should see that the "libc++" review group is automatically 52added as a reviewer for your patch. Once the group is marked as having approved your patch, 53you can commit it. However, if you get an approval very quickly for a significant patch, 54please try to wait a couple of business days before committing to give the opportunity for 55other reviewers to chime in. If you need someone else to commit the patch for you, please 56mention it and provide your ``Name <email@domain>`` for us to attribute the commit properly. 57 58Note that the rule for accepting as the "libc++" review group is to wait for two members 59of the group to have approved the patch, excluding the patch author. This is not a hard 60rule -- for very simple patches, use your judgement. The `"libc++" review group <https://reviews.llvm.org/project/members/64/>`__ 61consists of frequent libc++ contributors with a good understanding of the project's 62guidelines -- if you would like to be added to it, please reach out on Discord. 63 64Post-release check list 65======================= 66 67After branching for an LLVM release: 68 691. Update ``_LIBCPP_VERSION`` in ``libcxx/include/__config`` 702. Update the version number in ``libcxx/docs/conf.py`` 713. Update ``_LIBCPPABI_VERSION`` in ``libcxxabi/include/cxxabi.h`` 724. Update ``_LIBUNWIND_VERSION`` in ``libunwind/include/__libunwind_config.h`` 735. Update the list of supported clang versions in ``libcxx/docs/index.rst`` 746. Remove the in-progress warning from ``libcxx/docs/ReleaseNotes.rst`` 75 76Exporting new symbols from the library 77====================================== 78 79When exporting new symbols from libc++, you must update the ABI lists located in ``lib/abi``. 80To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``. 81To regenerate the lists, use the target ``generate-cxx-abilist``. 82The ABI lists must be updated for all supported platforms; currently Linux and 83Apple. If you don't have access to one of these platforms, you can download an 84updated list from the failed build at 85`Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__. 86Look for the failed build and select the ``artifacts`` tab. There, download the 87abilist for the platform, e.g.: 88 89* C++<version>. 90* MacOS X86_64 and MacOS arm64 for the Apple platform. 91 92 93Pre-commit CI 94============= 95 96Introduction 97------------ 98 99Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This 100CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__ and 101the build results are visible in the review on Phabricator. Please make sure 102the CI is green before committing a patch. 103 104The CI tests libc++ for all :ref:`supported platforms <SupportedPlatforms>`. 105The build is started for every diff uploaded to Phabricator. A complete CI run 106takes approximately one hour. To reduce the load: 107 108* The build is cancelled when a new diff for the same revision is uploaded. 109* The build is done in several stages and cancelled when a stage fails. 110 111Typically, the libc++ jobs use a Ubuntu Docker image. This image contains 112recent `nightly builds <https://apt.llvm.org>`__ of all supported versions of 113Clang and the current version of the ``main`` branch. These versions of Clang 114are used to build libc++ and execute its tests. 115 116Unless specified otherwise, the configurations: 117 118* use a nightly build of the ``main`` branch of Clang, 119* execute the tests using the language C++<latest>. This is the version 120 "developed" by the C++ committee. 121 122.. note:: Updating the Clang nightly builds in the Docker image is a manual 123 process and is done at an irregular interval on purpose. When you need to 124 have the latest nightly build to test recent Clang changes, ask in the 125 ``#libcxx`` channel on `LLVM's Discord server 126 <https://discord.gg/jzUbyP26tQ>`__. 127 128.. [#] There's `LLVM Dev Meeting talk <https://www.youtube.com/watch?v=B7gB6van7Bw>`__ 129 explaining the benefits of libc++'s pre-commit CI. 130 131Builds 132------ 133 134Below is a short description of the most interesting CI builds [#]_: 135 136* ``Format`` runs ``clang-format`` and uploads its output as an artifact. At the 137 moment this build is a soft error and doesn't fail the build. 138* ``Generated output`` runs the ``libcxx-generate-files`` build target and 139 tests for non-ASCII characters in libcxx. Some files are excluded since they 140 use Unicode, mainly tests. The output of these commands are uploaded as 141 artifact. 142* ``Documentation`` builds the documentation. (This is done early in the build 143 process since it is cheap to run.) 144* ``C++<version>`` these build steps test the various C++ versions, making sure all 145 C++ language versions work with the changes made. 146* ``Clang <version>`` these build steps test whether the changes work with all 147 supported Clang versions. 148* ``Booststrapping build`` builds Clang using the revision of the patch and 149 uses that Clang version to build and test libc++. This validates the current 150 Clang and lib++ are compatible. 151 152 When a crash occurs in this build, the crash reproducer is available as an 153 artifact. 154 155* ``Modular build`` tests libc++ using Clang modules [#]_. 156* ``GCC <version>`` tests libc++ with the latest stable GCC version. Only C++11 157 and the latest C++ version are tested. 158* ``Santitizers`` tests libc++ using the Clang sanitizers. 159* ``Parts disabled`` tests libc++ with certain libc++ features disabled. 160* ``Windows`` tests libc++ using MinGW and clang-cl. 161* ``Apple`` tests libc++ on MacOS. 162* ``ARM`` tests libc++ on various Linux ARM platforms. 163* ``AIX`` tests libc++ on AIX. 164 165.. [#] Not all all steps are listed: steps are added and removed when the need 166 arises. 167.. [#] Clang modules are not the same as C++20's modules. 168 169Infrastructure 170-------------- 171 172All files of the CI infrastructure are in the directory ``libcxx/utils/ci``. 173Note that quite a bit of this infrastructure is heavily Linux focused. This is 174the platform used by most of libc++'s Buildkite runners and developers. 175 176Dockerfile 177~~~~~~~~~~ 178 179Contains the Docker image for the Ubuntu CI. Because the same Docker image is 180used for the ``main`` and ``release`` branch, it should contain no hard-coded 181versions. It contains the used versions of Clang, various clang-tools, 182GCC, and CMake. 183 184.. note:: This image is pulled from Docker hub and not rebuild when changing 185 the Dockerfile. 186 187run-buildbot-container 188~~~~~~~~~~~~~~~~~~~~~~ 189 190Helper script that pulls and runs the Docker image. This image mounts the LLVM 191monorepo at ``/llvm``. This can be used to test with compilers not available on 192your system. 193 194run-buildbot 195~~~~~~~~~~~~ 196 197Contains the buld script executed on Buildkite. This script can be executed 198locally or inside ``run-buildbot-container``. The script must be called with 199the target to test. For example, ``run-buildbot generic-cxx20`` will build 200libc++ and test it using C++20. 201 202.. warning:: This script will overwrite the directory ``<llvm-root>/build/XX`` 203 where ``XX`` is the target of ``run-buildbot``. 204 205This script contains as little version information as possible. This makes it 206easy to use the script with a different compiler. This allows testing a 207combination not in the libc++ CI. It can be used to add a new (temporary) 208job to the CI. For example, testing the C++17 build with Clang-14 can be done 209like: 210 211.. code-block:: bash 212 213 CC=clang-14 CXX=clang++-14 run-buildbot generic-cxx17 214 215buildkite-pipeline.yml 216~~~~~~~~~~~~~~~~~~~~~~ 217 218Contains the jobs executed in the CI. This file contains the version 219information of the jobs being executed. Since this script differs between the 220``main`` and ``release`` branch, both branches can use different compiler 221versions. 222