diff --git a/libc/docs/CMakeLists.txt b/libc/docs/CMakeLists.txt index 5b89511c33bdc..68fe9fc545781 100644 --- a/libc/docs/CMakeLists.txt +++ b/libc/docs/CMakeLists.txt @@ -86,7 +86,7 @@ if (SPHINX_FOUND) # docgen invocation. add_custom_target(${stem_rst} - COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h > + COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h > ${CMAKE_CURRENT_BINARY_DIR}/headers/${stem}.rst) # depend on the docgen invocation. add_dependencies(docs-libc-html ${stem_rst}) diff --git a/libc/docs/porting.rst b/libc/docs/porting.rst index e890e439f619f..908cf2aaffdbd 100644 --- a/libc/docs/porting.rst +++ b/libc/docs/porting.rst @@ -8,23 +8,11 @@ Bringup on a New OS or Architecture :depth: 4 :local: -CI builders -=========== - -If you are contributing a port for an operating system or architecture which -is not covered by existing CI builders, you will also have to present a plan -for testing and contribute a CI builder. See -`this guide `_ for information -on how to add new builders to the -`LLVM buildbot `_. -You will either have to extend the existing -`Linux script `_ -and/or -`Windows script `_ -or add a new script for your operating system. +Building the libc +================= An OS specific config directory -=============================== +------------------------------- If you are starting to bring up LLVM's libc on a new operating system, the first step is to add a directory for that OS in the ``libc/config`` directory. Both @@ -44,7 +32,7 @@ have their own config directory. source tree. Architecture Subdirectory -========================= +------------------------- There are parts of the libc which are implemented differently for different architectures. The simplest example of this is the ``syscall`` function and @@ -63,7 +51,7 @@ The libc CMake machinery looks for subdirectories named after the target architecture. The entrypoints.txt file -======================== +------------------------ One of the important pieces of config information is listed in a file named ``entrypoints.txt``. This file lists the targets for the entrypoints (see @@ -90,7 +78,7 @@ target architectures, then multiple ``entrypoints.txt`` files will have to be updated. The headers.txt file -==================== +-------------------- Another important piece of config information is listed in a file named ``headers.txt``. It lists the targets for the set of public headers that are @@ -103,3 +91,69 @@ bring up. The Linux config has ``headers.txt`` file listed separately for the config and the `x86_64 `_ config. + + +Upstreaming +=========== + +Adding a target to the main LLVM-libc has some requirements to ensure that the +targets stay in usable condition. LLVM-libc is under active development and +without active maintenance targets will become stale and may be sunset. + +Maintenance +----------- + +To add a target there must be one or more people whose responsibility it is to +keep the target up to date or push it forwards if it's not complete. Those +people are the maintainers, and they are responsible for keeping their target in +good shape. This means fixing their target when it breaks, reviewing patches +related to their target, and keeping the target's CI running. + +Maintainers are listed in libc/maintainers.rst and must follow +`LLVM's maintainer policy `_. + +CI builders +----------- + +Every target needs at least one CI builder. These are used to check when the +target breaks, and to help people who don't have access to the specific +architecture fix their bugs. LLVM-libc has both presubmit CI on github +and postsubmit CI on the `LLVM buildbot `_. For +instructions on contributing a postsubmit buildbot read +`the LLVM documentation `_ and for +presubmit tests read +`the github documentation ` +TODO: proper link. + +The test configurations are at these links: + * `Linux Postsubmit `_ + * `Windows Postsubmit `_ + * `Fullbuild Presubmit `_ + * `Overlay Presubmit `_ + +Sunsetting +---------- + +Sunsetting is the process through which targets can be removed from LLVM-libc. +If a target is broken or stale it may be sunset. It is the responsibility of the +target's maintainers to keep it from being sunset. The target's maintainers may +be marked inactive if their target is sunset. + +Broken targets are ones where the target's CI has been failing for at least +30 days. After 30 days have passed the CI should be changed so it does not +block commits and does not notify people when it fails. If the target remains +broken for another 90 days it may be sunset. + +Stale targets are ones with no active maintainers or no contributions. If a +target has 0 specific contributions between two major LLVM releases, or if it +has no active maintainers, then it may be marked "deprecated" in the next major +release. If there are still no contributions or no maintainers after the next +major release it may be sunset. + +To sunset a target, all specific references to that target in the code and build +system should be removed. All buildbots for that target should be shut down, or +otherwise removed. + +To restart a target that was previously sunset, the new maintainers are +encouraged to look at the commit(s) removing the target to provide a starting +point. diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py index 5a57987b3c51e..59cfbd54561c7 100755 --- a/libc/utils/docgen/docgen.py +++ b/libc/utils/docgen/docgen.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # # ====- Generate documentation for libc functions ------------*- python -*--==# #