364 lines · plain
1.. _ContributingToLibcxx:2 3======================4Contributing to libc++5======================6 7This file contains information useful when contributing to libc++. If this is your first time contributing,8please also read `this document <https://www.llvm.org/docs/Contributing.html>`__ on general rules for9contributing to LLVM.10 11If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel12on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.13 14Looking for pre-existing pull requests15======================================16 17Before you start working on any feature, please take a look at the open libc++ pull18requests to avoid duplicating someone else's work. You can do that on GitHub by19filtering pull requests `tagged with libc++ <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+is%3Aopen+label%3Alibc%2B%2B>`__.20If you see that your feature is already being worked on, please consider chiming in21and helping review the code instead of duplicating work!22 23RFCs for significant user-affecting changes24===========================================25 26Before you start working on a change that can have significant impact on users of the library,27please consider creating a RFC on the `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx>`_.28This will ensure that you work in a direction that the project endorses and will ease reviewing your29contribution as directional questions can be raised early. Including a WIP patch is not mandatory,30but it can be useful to ground the discussion in something concrete.31 32Writing tests and running the test suite33========================================34 35Every change in libc++ must come with appropriate tests. Libc++ has an extensive test suite that36should be run locally by developers before submitting patches and is also run as part of our CI37infrastructure. The documentation about writing tests and running them is :ref:`here <testing>`.38 39Coding Guidelines40=================41 42libc++'s coding guidelines are documented :ref:`here <CodingGuidelines>`.43 44 45Resources46=========47 48Libc++ specific49---------------50 51- ``libcxx/include/__config`` -- this file contains the commonly used52 macros in libc++. Libc++ supports all C++ language versions. Newer versions53 of the Standard add new features. For example, making functions ``constexpr``54 in C++20 is done by using ``_LIBCPP_CONSTEXPR_SINCE_CXX20``. This means the55 function is ``constexpr`` in C++20 and later. The Standard does not allow56 making this available in C++17 or earlier, so we use a macro to implement57 this requirement.58- ``libcxx/test/support/test_macros.h`` -- similar to the above, but for the59 test suite.60 61 62ISO C++ Standard63----------------64 65Libc++ implements the library part of the ISO C++ standard. The official66publication must be bought from ISO or your national body. This is not67needed to work on libc++, there are other free resources available.68 69- The `LaTeX sources <https://github.com/cplusplus/draft>`_ used to70 create the official C++ standard. This can be used to create your own71 unofficial build of the standard.72 73- An `HTML rendered version of the draft <https://eel.is/c++draft/>`_ is74 available. This is the most commonly used place to look for the75 wording of the standard.76 77- An `alternative <https://github.com/timsong-cpp/cppwp>`_ is available.78 This link has both recent and historic versions of the standard.79 80- When implementing features, there are81 `general requirements <https://eel.is/c++draft/#library>`_.82 Most papers use this83 `jargon <http://eel.is/c++draft/structure#specifications>`_84 to describe how library functions work.85 86- The `WG21 redirect service <https://wg21.link/>`_ is a tool to quickly locate87 papers, issues, and wording in the standard.88 89- The `paper trail <https://github.com/cplusplus/papers/issues>`_ of90 papers is publicly available, including the polls taken. It91 contains links to the minutes of paper's discussion. Per ISO rules,92 these minutes are only accessible by members of the C++ committee.93 94- `Feature-Test Macros and Policies95 <https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_96 contains information about feature-test macros in C++.97 It contains a list with all feature-test macros, their versions, and the paper98 that introduced them.99 100- `cppreference <https://en.cppreference.com/w/>`_ is a good resource101 for the usage of C++ library and language features. It's easier to102 read than the C++ Standard, but it lacks details needed to properly implement103 library features.104 105 106Pre-commit check list107=====================108 109Before committing or creating a review, please go through this check-list to make110sure you don't forget anything:111 112- Do you have :ref:`tests <testing>` for every public class and/or function you're adding or modifying?113- Did you update the synopsis of the relevant headers?114- Did you update the relevant files to track implementation status (in ``docs/Status/``)?115- Did you mark all functions and type declarations with the :ref:`proper visibility macro <visibility-macros>`?116- Did you add all new named declarations to the ``std`` module?117- If you added a header:118 119 - Did you add it to ``include/module.modulemap.in``?120 - Did you add it to ``include/CMakeLists.txt``?121 - If it's a public header, did you update ``utils/libcxx/header_information.py``?122 123- 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?124- Did you run the ``libcxx-generate-files`` target and verify its output?125- If needed, did you add ``_LIBCPP_PUSH_MACROS`` and ``_LIBCPP_POP_MACROS`` to the relevant headers?126 127The review process128==================129 130After uploading your patch, you should see that the "libc++" review group is automatically131added as a reviewer for your patch. Once the group is marked as having approved your patch,132you can commit it. However, if you get an approval very quickly for a significant patch,133please try to wait a couple of business days before committing to give the opportunity for134other reviewers to chime in. If you need someone else to commit the patch for you, please135mention it and provide your ``Name <email@domain>`` for us to attribute the commit properly.136 137Note that the rule for accepting as the "libc++" review group is to wait for two members138of the group to have approved the patch, excluding the patch author. This is not a hard139rule -- for very simple patches, use your judgement. The `"libc++" review group <https://reviews.llvm.org/project/members/64/>`__140consists of frequent libc++ contributors with a good understanding of the project's141guidelines -- if you would like to be added to it, please reach out on Discord.142 143Some tips:144 145- Keep the number of formatting changes in patches minimal.146- Provide separate patches for style fixes and for bug fixes or features. Keep in147 mind that large formatting patches may cause merge conflicts with other patches148 under review. In general, we prefer to avoid large reformatting patches.149- Keep patches self-contained. Large and/or complicated patches are harder to150 review and take a significant amount of time. It's fine to have multiple151 patches to implement one feature if the feature can be split into152 self-contained sub-tasks.153 154Exporting new symbols from the library155======================================156 157When exporting new symbols from libc++, you must update the ABI lists located in ``lib/abi``.158To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``.159To regenerate the lists, use the target ``generate-cxx-abilist``.160The ABI lists must be updated for all supported platforms; currently Linux and161Apple. If you don't have access to one of these platforms, you can download an162updated list from the failed build at163`Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.164Look for the failed build and select the ``artifacts`` tab. There, download the165abilist for the platform, e.g.:166 167* C++<version>.168* MacOS X86_64 and MacOS arm64 for the Apple platform.169 170 171Pre-commit CI172=============173 174Introduction175------------176 177Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. Some of178this CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__,179but some has migrated to the LLVM CI infrastructure. The build results are180visible in the review on GitHub. Please make sure the CI is green before181committing a patch.182 183The CI tests libc++ for all :ref:`supported platforms <SupportedPlatforms>`.184The build is started for every commit added to a Pull Request. A complete CI185run takes approximately one hour. To reduce the load:186 187* The build is cancelled when a new commit is pushed to a PR that is already running CI.188* The build is done in several stages and cancelled when a stage fails.189 190Typically, the libc++ jobs use a Ubuntu Docker image. This image contains191recent `nightly builds <https://apt.llvm.org>`__ of all supported versions of192Clang and the current version of the ``main`` branch. These versions of Clang193are used to build libc++ and execute its tests.194 195Unless specified otherwise, the configurations:196 197* use a nightly build of the ``main`` branch of Clang,198* execute the tests using the language C++<latest>. This is the version199 "developed" by the C++ committee.200 201.. note:: Updating the Clang nightly builds in the Docker image is a manual202 process and is done at an irregular interval on purpose. When you need to203 have the latest nightly build to test recent Clang changes, ask in the204 ``#libcxx`` channel on `LLVM's Discord server205 <https://discord.gg/jzUbyP26tQ>`__.206 207.. [#] There's `LLVM Dev Meeting talk <https://www.youtube.com/watch?v=B7gB6van7Bw>`__208 explaining the benefits of libc++'s pre-commit CI.209 210Builds211------212 213Below is a short description of the most interesting CI builds [#]_:214 215* ``Format`` runs ``clang-format`` and uploads its output as an artifact. At the216 moment this build is a soft error and doesn't fail the build.217* ``Generated output`` runs the ``libcxx-generate-files`` build target and218 tests for non-ASCII characters in libcxx. Some files are excluded since they219 use Unicode, mainly tests. The output of these commands are uploaded as220 artifact.221* ``Documentation`` builds the documentation. (This is done early in the build222 process since it is cheap to run.)223* ``C++<version>`` these build steps test the various C++ versions, making sure all224 C++ language versions work with the changes made.225* ``Clang <version>`` these build steps test whether the changes work with all226 supported Clang versions.227* ``Booststrapping build`` builds Clang using the revision of the patch and228 uses that Clang version to build and test libc++. This validates the current229 Clang and lib++ are compatible.230 231 When a crash occurs in this build, the crash reproducer is available as an232 artifact.233 234* ``Modular build`` tests libc++ using Clang modules [#]_.235* ``GCC <version>`` tests libc++ with the latest stable GCC version. Only C++11236 and the latest C++ version are tested.237* ``Santitizers`` tests libc++ using the Clang sanitizers.238* ``Parts disabled`` tests libc++ with certain libc++ features disabled.239* ``Windows`` tests libc++ using MinGW and clang-cl.240* ``Apple`` tests libc++ on MacOS.241* ``ARM`` tests libc++ on various Linux ARM platforms.242* ``AIX`` tests libc++ on AIX.243 244.. [#] Not all steps are listed: steps are added and removed when the need arises.245.. [#] Clang modules are not the same as C++20's modules.246 247Infrastructure248--------------249 250The files for the CI infrastructure are split between the llvm-project251and the llvm-zorg repositories. All files of the CI infrastructure in252the llvm-project are in the directory ``libcxx/utils/ci``. Note that253quite a bit of this infrastructure is heavily Linux focused. This is254the platform used by most of libc++'s Buildkite runners and255developers.256 257Dockerfile/Container Images258~~~~~~~~~~~~~~~~~~~~~~~~~~~259 260Contains the Docker image for the Ubuntu CI. Because the same Docker image is261used for the ``main`` and ``release`` branch, it should contain no hard-coded262versions. It contains the used versions of Clang, various clang-tools,263GCC, and CMake.264 265.. note:: This image is pulled from Docker hub and not rebuild when changing266 the Dockerfile.267 268Updating the CI testing container images269----------------------------------------270 271The libcxx linux premerge testing can run on one of three sets of runner272groups. The three runner group names are ``llvm-premerge-libcxx-runners``,273``llvm-premerge-libcxx-release-runners`` and ``llvm-premerge-libcxx-next-runners``.274The runner set to use is controlled by the contents of275https://github.com/llvm/llvm-project/blob/main/.github/workflows/libcxx-build-and-test.yaml.276By default, it uses ``llvm-premerge-libcxx-runners``. To switch to one of the277other runner sets, just replace all uses of ``llvm-premerge-libcxx-runners`` in278the yaml file with the desired runner set.279 280Which container image is used by these three runner sets is controlled281and set by the variable values in282https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.283The table below shows the variable names and284the runner sets to which they correspond. To see their values, follow the285link above (to ``variables.tf`` in llvm-zorg).286 287+------------------------------------+---------------------------+288|Runner Set |Variable |289+====================================+===========================+290|llvm-premerge-libcxx-runners |libcxx_runner_image |291+------------------------------------+---------------------------+292|llvm-premerge-libcxx-release-runners|libcxx_release_runner_image|293+------------------------------------+---------------------------+294|llvm-premerge-libcxx-next-runners |libcxx_next_runner_image |295+------------------------------------+---------------------------+296 297 298When updating the container image you can either update just the runner binary (the part299that connects to Github), or you can update everything (tools, etc.). To update the runner300binary, bump the value of ``GITHUB_RUNNER_VERSION`` in ``libcxx/utils/ci/docker/docker-compose.yml``.301To update all of the tools, bump ``BASE_IMAGE_VERSION`` to a newer version of the ``libcxx-linux-builder-base``302image. You can see all versions of that image at https://github.com/llvm/llvm-project/pkgs/container/libcxx-linux-builder-base.303 304On push to ``main``, a new version of both the ``libcxx-linux-builder`` and the ``libcxx-android-builder``305images will be built and pushed to https://github.com/llvm/llvm-project/packages.306 307You can then update the image used by the actual runners by changing the sha associated308to ``libcxx_runner_image``, ``libcxx_release_runner_image`` or ``libcxx_next_runner_image``309in `the Terraform configuration file <https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf>`_.310To do so, you will need to create a PR in the llvm-zorg repository and wait for it to be311merged. Once that change has been merged, an LLVM premerge maintainer (a Google employee)312must use terraform to apply the change to the running GKE cluster.313 314.. note:: When you update the ``libcxx_runner_image``, also make sure to update the315 ``libcxx/utils/ci/run-buildbot-container`` script to contain the new image.316 317 318Monitoring premerge testing performance319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~320 321The llvm-premerge-libcxx runners mentioned above collect metrics regarding the322time the tests spend queued up before they start running and also the time it323takes the tests to actually complete running. These metrics are collected and324aggregated (based on stage and PR), and the results can be seen at the325`Libc++ Premerge Testing dashboard326<https://llvm.grafana.net/public-dashboards/0bd453e8b3034733a1b0ff8c7728086d>`__327.328 329run-buildbot-container330~~~~~~~~~~~~~~~~~~~~~~331 332Helper script that pulls and runs the Docker image. This image mounts the LLVM333monorepo at ``/llvm``. This can be used to test with compilers not available on334your system.335 336run-buildbot337~~~~~~~~~~~~338 339Contains the build script executed on Buildkite. This script can be executed340locally or inside ``run-buildbot-container``. The script must be called with341the target to test. For example, ``run-buildbot generic-cxx20`` will build342libc++ and test it using C++20.343 344.. warning:: This script will overwrite the directory ``<llvm-root>/build/XX``345 where ``XX`` is the target of ``run-buildbot``.346 347This script contains as little version information as possible. This makes it348easy to use the script with a different compiler. This allows testing a349combination not in the libc++ CI. It can be used to add a new (temporary)350job to the CI. For example, testing the C++17 build with Clang-14 can be done351like:352 353.. code-block:: bash354 355 CC=clang-14 CXX=clang++-14 run-buildbot generic-cxx17356 357buildkite-pipeline.yml358~~~~~~~~~~~~~~~~~~~~~~359 360Contains the jobs executed in the CI. This file contains the version361information of the jobs being executed. Since this script differs between the362``main`` and ``release`` branch, both branches can use different compiler363versions.364