Home | History | Annotate | Line # | Download | only in docs 
      1 .. _ContributingToLibcxx:
      2 
      3 ======================
      4 Contributing to libc++
      5 ======================
      6 
      7 .. contents::
      8   :local:
      9 
     10 Please read `this document <https://www.llvm.org/docs/Contributing.html>`__ on general rules to contribute to LLVM projects.
     11 
     12 Tasks and processes
     13 ===================
     14 
     15 This file contains notes about various tasks and processes specific to libc++.
     16 
     17 Looking for pre-existing reviews
     18 ================================
     19 
     20 Before you start working on any feature, please take a look at the open reviews
     21 to avoid duplicating someone else's work. You can do that by going to the website
     22 where code reviews are held, `Differential <https://reviews.llvm.org/differential>`__,
     23 and clicking on ``Libc++ Open Reviews`` in the sidebar to the left. If you see
     24 that your feature is already being worked on, please consider chiming in instead
     25 of duplicating work!
     26 
     27 Post-Release TODO
     28 =================
     29 
     30 After branching for an LLVM release:
     31 
     32 1. Update ``_LIBCPP_VERSION`` in ``include/__config``
     33 2. Update the ``include/__libcpp_version`` file
     34 3. Update the version number in ``docs/conf.py``
     35 
     36 Modifying feature-test macros
     37 =============================
     38 
     39 When adding or updating feature-test macros, you should update the corresponding tests.
     40 To do that, modify ``feature_test_macros`` table in the script
     41 ``utils/generate_feature_test_macro_components.py``, run it, and commit updated
     42 files. Running ``utils/generate_feature_test_macro_components.py`` should never
     43 generate diffs in a clean checkout; feel free to run it in your local checkout
     44 any time you want.
     45 
     46 
     47 Adding a new header TODO
     48 ========================
     49 
     50 When adding a new header to libc++:
     51 
     52 1. Add a test under ``test/libcxx`` that the new header defines ``_LIBCPP_VERSION``. See ``test/libcxx/algorithms/version.pass.cpp`` for an example.
     53 2. Run ``python utils/generate_header_tests.py``; verify and commit the changes.
     54 3. Modify ``python utils/generate_header_inclusion_tests.py``; run it; verify and commit the changes.
     55 4. Create a submodule in ``include/module.modulemap`` for the new header.
     56 5. Update the ``include/CMakeLists.txt`` file to include the new header.
     57 
     58 Exporting new symbols from the library
     59 ======================================
     60 
     61 When exporting new symbols from libc++, you must update the ABI lists located in ``lib/abi``.
     62 To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``.
     63 To regenerate the lists, use the target ``generate-cxx-abilist``.
     64 The ABI lists must be updated for all supported platforms; currently Linux and
     65 Apple.  If you don't have access to one of these platforms, you can download an
     66 updated list from the failed build at
     67 `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.
     68 Look for the failed build and select the ``artifacts`` tab. There, download the
     69 abilist for the platform, e.g.:
     70 
     71 * C++20 for the Linux platform.
     72 * MacOS C++20 for the Apple platform.
     73