Lines Matching +full:docs +full:- +full:libc +full:- +full:html
4 Contributing to libc++
7 This file contains information useful when contributing to libc++. If this is your first time contributing,
8 please also read `this document <https://www.llvm.org/docs/Contributing.html>`__ on general rules for
11 If you plan on contributing to libc++, it can be useful to join the ``#libcxx`` channel
14 Looking for pre-existing pull requests
17 Before you start working on any feature, please take a look at the open libc++ pull
19 filtering pull requests `tagged with libc++ <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+is%3Aopen+label%3Alibc%2B%2B>`__.
23 RFCs for significant user-affecting changes
27 please consider creating a RFC on the `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx>`_.
35 Every change in libc++ must come with appropriate tests. Libc++ has an extensive test suite that
42 libc++'s coding guidelines are documented :ref:`here <CodingGuidelines>`.
48 Libc++ specific
49 ---------------
51 - ``libcxx/include/__config`` -- this file contains the commonly used
52 macros in libc++. Libc++ supports all C++ language versions. Newer versions
58 - ``libcxx/test/support/test_macros.h`` -- similar to the above, but for the
63 ----------------
65 Libc++ implements the library part of the ISO C++ standard. The official
67 needed to work on libc++, there are other free resources available.
69 - The `LaTeX sources <https://github.com/cplusplus/draft>`_ used to
73 - An `HTML rendered version of the draft <https://eel.is/c++draft/>`_ is
77 - An `alternative <https://github.com/timsong-cpp/cppwp>`_ is available.
80 - When implementing features, there are
86 - The `WG21 redirect service <https://wg21.link/>`_ is a tool to quickly locate
89 - The `paper trail <https://github.com/cplusplus/papers/issues>`_ of
94 - `Feature-Test Macros and Policies
95 <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 paper
100 - `cppreference <https://en.cppreference.com/w/>`_ is a good resource
106 Pre-commit check list
109 Before committing or creating a review, please go through this check-list to make
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:
119 - Did you add it to ``include/module.modulemap``?
120 - Did you add it to ``include/CMakeLists.txt``?
121 - If it's a public header, did you update ``utils/libcxx/header_information.py``?
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?
130 After uploading your patch, you should see that the "libc++" review group is automatically
137 Note that the rule for accepting as the "libc++" review group is to wait for two members
139 rule -- for very simple patches, use your judgement. The `"libc++" review group <https://reviews.llvm.org/project/members/64/>`__
140 consists of frequent libc++ contributors with a good understanding of the project's
141 guidelines -- if you would like to be added to it, please reach out on Discord.
145 - Keep the number of formatting changes in patches minimal.
146 - Provide separate patches for style fixes and for bug fixes or features. Keep in
149 - Keep patches self-contained. Large and/or complicated patches are harder to
152 self-contained sub-tasks.
157 When exporting new symbols from libc++, you must update the ABI lists located in ``lib/abi``.
158 To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``.
159 To regenerate the lists, use the target ``generate-cxx-abilist``.
163 `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.
171 Pre-commit CI
175 ------------
177 Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This
178 CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__ and
182 The CI tests libc++ for all :ref:`supported platforms <SupportedPlatforms>`.
189 Typically, the libc++ jobs use a Ubuntu Docker image. This image contains
192 are used to build libc++ and execute its tests.
207 explaining the benefits of libc++'s pre-commit CI.
210 ------
214 * ``Format`` runs ``clang-format`` and uploads its output as an artifact. At the
216 * ``Generated output`` runs the ``libcxx-generate-files`` build target and
217 tests for non-ASCII characters in libcxx. Some files are excluded since they
227 uses that Clang version to build and test libc++. This validates the current
233 * ``Modular build`` tests libc++ using Clang modules [#]_.
234 * ``GCC <version>`` tests libc++ with the latest stable GCC version. Only C++11
236 * ``Santitizers`` tests libc++ using the Clang sanitizers.
237 * ``Parts disabled`` tests libc++ with certain libc++ features disabled.
238 * ``Windows`` tests libc++ using MinGW and clang-cl.
239 * ``Apple`` tests libc++ on MacOS.
240 * ``ARM`` tests libc++ on various Linux ARM platforms.
241 * ``AIX`` tests libc++ on AIX.
247 --------------
251 the platform used by most of libc++'s Buildkite runners and developers.
257 used for the ``main`` and ``release`` branch, it should contain no hard-coded
258 versions. It contains the used versions of Clang, various clang-tools,
264 run-buildbot-container
271 run-buildbot
275 locally or inside ``run-buildbot-container``. The script must be called with
276 the target to test. For example, ``run-buildbot generic-cxx20`` will build
277 libc++ and test it using C++20.
279 .. warning:: This script will overwrite the directory ``<llvm-root>/build/XX``
280 where ``XX`` is the target of ``run-buildbot``.
284 combination not in the libc++ CI. It can be used to add a new (temporary)
285 job to the CI. For example, testing the C++17 build with Clang-14 can be done
288 .. code-block:: bash
290 CC=clang-14 CXX=clang++-14 run-buildbot generic-cxx17
292 buildkite-pipeline.yml