[DFAJumpThreading] Remove incoming StartBlock from all phis when unfolding select...
[llvm-project.git] / libcxx / docs / Contributing.rst
blobae883841851698a00e40149c821fc63ad8bf1d5d
1 .. _ContributingToLibcxx:
3 ======================
4 Contributing to libc++
5 ======================
7 This file contains notes about various tasks and processes specific to contributing
8 to 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.
11 If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel
12 on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.
14 Looking for pre-existing pull requests
15 ======================================
17 Before you start working on any feature, please take a look at the open libc++ pull
18 requests to avoid duplicating someone else's work. You can do that on GitHub by
19 filtering pull requests `tagged with libc++ <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+is%3Aopen+label%3Alibc%2B%2B>`__.
20 If you see that your feature is already being worked on, please consider chiming in
21 and helping review the code instead of duplicating work!
23 RFCs for significant user-affecting changes
24 ===========================================
26 Before you start working on a change that can have significant impact on users of the library,
27 please consider creating a RFC on `libc++'s Discourse forum <https://discourse.llvm.org/c/runtimes/libcxx>`__.
28 This will ensure that you work in a direction that the project endorses and will ease reviewing your
29 contribution as directional questions can be raised early. Including a WIP patch is not mandatory, but
30 it can be useful to ground the discussion in something concrete.
32 Coding standards
33 ================
35 In general, libc++ follows the
36 `LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
37 There are some deviations from these standards.
39 Libc++ uses ``__ugly_names``. These names are reserved for implementations, so
40 users may not use them in their own applications. When using a name like ``T``,
41 a user may have defined a macro that changes the meaning of ``T``. By using
42 ``__ugly_names`` we avoid that problem. Other standard libraries and compilers
43 use these names too. To avoid common clashes with other uglified names used in
44 other implementations (e.g. system headers), the test in
45 ``libcxx/test/libcxx/system_reserved_names.gen.py`` contains the list of
46 reserved names that can't be used.
48 Unqualified function calls are susceptible to
49 `argument-dependent lookup (ADL) <https://en.cppreference.com/w/cpp/language/adl>`_.
50 This means calling ``move(UserType)`` might not call ``std::move``. Therefore,
51 function calls must use qualified names to avoid ADL. Some functions in the
52 standard library `require ADL usage <http://eel.is/c++draft/contents#3>`_.
53 Names of classes, variables, concepts, and type aliases are not subject to ADL.
54 They don't need to be qualified.
56 Function overloading also applies to operators. Using ``&user_object`` may call
57 a user-defined ``operator&``. Use ``std::addressof`` instead. Similarly, to
58 avoid invoking a user-defined ``operator,``, make sure to cast the result to
59 ``void`` when using the ``,``. For example:
61 .. code-block:: cpp
63     for (; __first1 != __last1; ++__first1, (void)++__first2) {
64       ...
65     }
67 In general, try to follow the style of existing code. There are a few
68 exceptions:
70 - ``_VSTD::foo`` is no longer used in new code. Use ``std::foo`` instead.
71 - ``_LIBCPP_INLINE_VISIBILITY`` is no longer used in new code. Use
72   ``_LIBCPP_HIDE_FROM_ABI`` instead.
73 - Prefer ``using foo = int`` over ``typedef int foo``. The compilers supported
74   by libc++ accept alias declarations in all standard modes.
76 Other tips are:
78 - Keep the number of formatting changes in patches minimal.
79 - Provide separate patches for style fixes and for bug fixes or features. Keep in
80   mind that large formatting patches may cause merge conflicts with other patches
81   under review. In general, we prefer to avoid large reformatting patches.
82 - Keep patches self-contained. Large and/or complicated patches are harder to
83   review and take a significant amount of time. It's fine to have multiple
84   patches to implement one feature if the feature can be split into
85   self-contained sub-tasks.
88 Resources
89 =========
91 Libc++ specific
92 ---------------
94 - ``libcxx/include/__config`` -- this file contains the commonly used
95   macros in libc++. Libc++ supports all C++ language versions. Newer versions
96   of the Standard add new features. For example, making functions ``constexpr``
97   in C++20 is done by using ``_LIBCPP_CONSTEXPR_SINCE_CXX20``. This means the
98   function is ``constexpr`` in C++20 and later. The Standard does not allow
99   making this available in C++17 or earlier, so we use a macro to implement
100   this requirement.
101 - ``libcxx/test/support/test_macros.h`` -- similar to the above, but for the
102   test suite.
105 ISO C++ Standard
106 ----------------
108 Libc++ implements the library part of the ISO C++ standard. The official
109 publication must be bought from ISO or your national body. This is not
110 needed to work on libc++, there are other free resources available.
112 - The `LaTeX sources <https://github.com/cplusplus/draft>`_  used to
113   create the official C++ standard. This can be used to create your own
114   unofficial build of the standard.
116 - An `HTML rendered version of the draft <https://eel.is/c++draft/>`_  is
117   available. This is the most commonly used place to look for the
118   wording of the standard.
120 - An `alternative <https://github.com/timsong-cpp/cppwp>`_ is available.
121   This link has both recent and historic versions of the standard.
123 - When implementing features, there are
124   `general requirements <https://eel.is/c++draft/#library>`_.
125   Most papers use this
126   `jargon <http://eel.is/c++draft/structure#specifications>`_
127   to describe how library functions work.
129 - The `WG21 redirect service <https://wg21.link/>`_ is a tool to quickly locate
130   papers, issues, and wording in the standard.
132 - The `paper trail <https://github.com/cplusplus/papers/issues>`_ of
133   papers is publicly available, including the polls taken. It
134   contains links to the minutes of paper's discussion. Per ISO rules,
135   these minutes are only accessible by members of the C++ committee.
137 - `Feature-Test Macros and Policies
138   <https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_
139   contains information about feature-test macros in C++.
140   It contains a list with all feature-test macros, their versions, and the paper
141   that introduced them.
143 - `cppreference <https://en.cppreference.com/w/>`_ is a good resource
144   for the usage of C++ library and language features. It's easier to
145   read than the C++ Standard, but it lacks details needed to properly implement
146   library features.
149 Pre-commit check list
150 =====================
152 Before committing or creating a review, please go through this check-list to make
153 sure you don't forget anything:
155 - Do you have :ref:`tests <testing>` for every public class and/or function you're adding or modifying?
156 - Did you update the synopsis of the relevant headers?
157 - Did you update the relevant files to track implementation status (in ``docs/Status/``)?
158 - Did you mark all functions and type declarations with the :ref:`proper visibility macro <visibility-macros>`?
159 - Did you add all new named declarations to the ``std`` module?
160 - If you added a header:
162   - Did you add it to ``include/module.modulemap.in``?
163   - Did you add it to ``include/CMakeLists.txt``?
164   - If it's a public header, did you update ``utils/libcxx/header_information.py``?
166 - 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?
167 - Did you run the ``libcxx-generate-files`` target and verify its output?
169 The review process
170 ==================
172 After uploading your patch, you should see that the "libc++" review group is automatically
173 added as a reviewer for your patch. Once the group is marked as having approved your patch,
174 you can commit it. However, if you get an approval very quickly for a significant patch,
175 please try to wait a couple of business days before committing to give the opportunity for
176 other reviewers to chime in. If you need someone else to commit the patch for you, please
177 mention it and provide your ``Name <email@domain>`` for us to attribute the commit properly.
179 Note that the rule for accepting as the "libc++" review group is to wait for two members
180 of the group to have approved the patch, excluding the patch author. This is not a hard
181 rule -- for very simple patches, use your judgement. The `"libc++" review group <https://reviews.llvm.org/project/members/64/>`__
182 consists of frequent libc++ contributors with a good understanding of the project's
183 guidelines -- if you would like to be added to it, please reach out on Discord.
185 Exporting new symbols from the library
186 ======================================
188 When exporting new symbols from libc++, you must update the ABI lists located in ``lib/abi``.
189 To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``.
190 To regenerate the lists, use the target ``generate-cxx-abilist``.
191 The ABI lists must be updated for all supported platforms; currently Linux and
192 Apple.  If you don't have access to one of these platforms, you can download an
193 updated list from the failed build at
194 `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.
195 Look for the failed build and select the ``artifacts`` tab. There, download the
196 abilist for the platform, e.g.:
198 * C++<version>.
199 * MacOS X86_64 and MacOS arm64 for the Apple platform.
202 Pre-commit CI
203 =============
205 Introduction
206 ------------
208 Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This
209 CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__ and
210 the build results are visible in the review on GitHub. Please make sure
211 the CI is green before committing a patch.
213 The CI tests libc++ for all :ref:`supported platforms <SupportedPlatforms>`.
214 The build is started for every commit added to a Pull Request. A complete CI
215 run takes approximately one hour. To reduce the load:
217 * The build is cancelled when a new commit is pushed to a PR that is already running CI.
218 * The build is done in several stages and cancelled when a stage fails.
220 Typically, the libc++ jobs use a Ubuntu Docker image. This image contains
221 recent `nightly builds <https://apt.llvm.org>`__ of all supported versions of
222 Clang and the current version of the ``main`` branch. These versions of Clang
223 are used to build libc++ and execute its tests.
225 Unless specified otherwise, the configurations:
227 * use a nightly build of the ``main`` branch of Clang,
228 * execute the tests using the language C++<latest>. This is the version
229   "developed" by the C++ committee.
231 .. note:: Updating the Clang nightly builds in the Docker image is a manual
232    process and is done at an irregular interval on purpose. When you need to
233    have the latest nightly build to test recent Clang changes, ask in the
234    ``#libcxx`` channel on `LLVM's Discord server
235    <https://discord.gg/jzUbyP26tQ>`__.
237 .. [#] There's `LLVM Dev Meeting talk <https://www.youtube.com/watch?v=B7gB6van7Bw>`__
238    explaining the benefits of libc++'s pre-commit CI.
240 Builds
241 ------
243 Below is a short description of the most interesting CI builds [#]_:
245 * ``Format`` runs ``clang-format`` and uploads its output as an artifact. At the
246   moment this build is a soft error and doesn't fail the build.
247 * ``Generated output`` runs the ``libcxx-generate-files`` build target and
248   tests for non-ASCII characters in libcxx. Some files are excluded since they
249   use Unicode, mainly tests. The output of these commands are uploaded as
250   artifact.
251 * ``Documentation`` builds the documentation. (This is done early in the build
252   process since it is cheap to run.)
253 * ``C++<version>`` these build steps test the various C++ versions, making sure all
254   C++ language versions work with the changes made.
255 * ``Clang <version>`` these build steps test whether the changes work with all
256   supported Clang versions.
257 * ``Booststrapping build`` builds Clang using the revision of the patch and
258   uses that Clang version to build and test libc++. This validates the current
259   Clang and lib++ are compatible.
261   When a crash occurs in this build, the crash reproducer is available as an
262   artifact.
264 * ``Modular build`` tests libc++ using Clang modules [#]_.
265 * ``GCC <version>`` tests libc++ with the latest stable GCC version. Only C++11
266   and the latest C++ version are tested.
267 * ``Santitizers`` tests libc++ using the Clang sanitizers.
268 * ``Parts disabled`` tests libc++ with certain libc++ features disabled.
269 * ``Windows`` tests libc++ using MinGW and clang-cl.
270 * ``Apple`` tests libc++ on MacOS.
271 * ``ARM`` tests libc++ on various Linux ARM platforms.
272 * ``AIX`` tests libc++ on AIX.
274 .. [#] Not all steps are listed: steps are added and removed when the need arises.
275 .. [#] Clang modules are not the same as C++20's modules.
277 Infrastructure
278 --------------
280 All files of the CI infrastructure are in the directory ``libcxx/utils/ci``.
281 Note that quite a bit of this infrastructure is heavily Linux focused. This is
282 the platform used by most of libc++'s Buildkite runners and developers.
284 Dockerfile
285 ~~~~~~~~~~
287 Contains the Docker image for the Ubuntu CI. Because the same Docker image is
288 used for the ``main`` and ``release`` branch, it should contain no hard-coded
289 versions.  It contains the used versions of Clang, various clang-tools,
290 GCC, and CMake.
292 .. note:: This image is pulled from Docker hub and not rebuild when changing
293    the Dockerfile.
295 run-buildbot-container
296 ~~~~~~~~~~~~~~~~~~~~~~
298 Helper script that pulls and runs the Docker image. This image mounts the LLVM
299 monorepo at ``/llvm``. This can be used to test with compilers not available on
300 your system.
302 run-buildbot
303 ~~~~~~~~~~~~
305 Contains the build script executed on Buildkite. This script can be executed
306 locally or inside ``run-buildbot-container``. The script must be called with
307 the target to test. For example, ``run-buildbot generic-cxx20`` will build
308 libc++ and test it using C++20.
310 .. warning:: This script will overwrite the directory ``<llvm-root>/build/XX``
311   where ``XX`` is the target of ``run-buildbot``.
313 This script contains as little version information as possible. This makes it
314 easy to use the script with a different compiler. This allows testing a
315 combination not in the libc++ CI. It can be used to add a new (temporary)
316 job to the CI. For example, testing the C++17 build with Clang-14 can be done
317 like:
319 .. code-block:: bash
321   CC=clang-14 CXX=clang++-14 run-buildbot generic-cxx17
323 buildkite-pipeline.yml
324 ~~~~~~~~~~~~~~~~~~~~~~
326 Contains the jobs executed in the CI. This file contains the version
327 information of the jobs being executed. Since this script differs between the
328 ``main`` and ``release`` branch, both branches can use different compiler
329 versions.