[libc-commits] [libc] [libc][docs] Add a sunset policy to porting docs (PR #168936)
via libc-commits
libc-commits at lists.llvm.org
Thu Nov 20 11:30:38 PST 2025
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-libc
Author: Michael Jones (michaelrj-google)
<details>
<summary>Changes</summary>
As discussed in the monthly meeting, update the porting docs to clarify
what's needed for a target and add a policy for sunsetting targets.
---
Full diff: https://github.com/llvm/llvm-project/pull/168936.diff
3 Files Affected:
- (modified) libc/docs/CMakeLists.txt (+1-1)
- (modified) libc/docs/porting.rst (+55-18)
- (modified) libc/utils/docgen/docgen.py (+1-1)
``````````diff
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..a7dcca1b3a33f 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 <https://llvm.org/docs/HowToAddABuilder.html>`_ for information
-on how to add new builders to the
-`LLVM buildbot <https://lab.llvm.org/buildbot>`_.
-You will either have to extend the existing
-`Linux script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_
-and/or
-`Windows script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_
-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,52 @@ bring up. The Linux config has ``headers.txt`` file listed separately for the
config and the
`x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/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 <https://llvm.org/docs/DeveloperPolicy.html#maintainers>`_.
+
+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 <https://lab.llvm.org/buildbot>`_. For
+instructions on contributing a postsubmit buildbot read
+`the LLVM documentation <https://llvm.org/docs/HowToAddABuilder.html>`_ and for
+presubmit tests read
+`the github documentation <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-fullbuild-tests.yml>`
+TODO: proper link.
+
+The test configurations are at these links:
+ * `Linux Postsubmit <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_
+ * `Windows Postsubmit <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_
+ * `Fullbuild Presubmit <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-fullbuild-tests.yml>`_
+ * `Overlay Presubmit <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-overlay-tests.yml>`_
+
+Sunsetting
+----------
+
+If a target is incomplete and no progress has been made for 1 month, or if a
+target has no active maintainers, then it may be considered stale and sunset.
+Sunsetting means removing the target specific code and turning off any related
+testing. If a target has been sunset and there new maintainers are interested
+in picking it up they are encouraged to look at the git history to learn from
+the previous implementation.
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 -*--==#
#
``````````
</details>
https://github.com/llvm/llvm-project/pull/168936
More information about the libc-commits
mailing list