llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-libc Author: Reid Kleckner (rnk) <details> <summary>Changes</summary> Tracking issue: https://github.com/llvm/llvm-project/issues/201242 Migration guide docs: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines RFC: https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840 This was prepared with rst2myst plus LLM-assisted cleanup. I paged through all the generated HTML looking for migration artifacts, and all of the differences I could find appear to be formatting error corrections. Please spot check my work and approve if it looks good. You can use the HTML links below to confirm it renders properly. ----- Before/after validation links: | Source file | Before HTML | After HTML | | --- | --- | --- | | `libc/docs/arch_support.md` | [before](https://libc.llvm.org/arch_support.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/arch_support.html) | | `libc/docs/build_and_test.md` | [before](https://libc.llvm.org/build_and_test.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/build_and_test.html) | | `libc/docs/build_concepts.md` | [before](https://libc.llvm.org/build_concepts.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/build_concepts.html) | | `libc/docs/compiler_support.md` | [before](https://libc.llvm.org/compiler_support.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/compiler_support.html) | | `libc/docs/contributing.md` | [before](https://libc.llvm.org/contributing.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/contributing.html) | | `libc/docs/dev/building_docs.md` | [before](https://libc.llvm.org/dev/building_docs.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/building_docs.html) | | `libc/docs/dev/builtin_compatibility.md` | [before](https://libc.llvm.org/dev/builtin_compatibility.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/builtin_compatibility.html) | | `libc/docs/dev/code_style.md` | [before](https://libc.llvm.org/dev/code_style.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/code_style.html) | | `libc/docs/dev/config_options.md` | [before](https://libc.llvm.org/dev/config_options.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/config_options.html) | | `libc/docs/dev/entrypoints.md` | [before](https://libc.llvm.org/dev/entrypoints.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/entrypoints.html) | | `libc/docs/dev/fuzzing.md` | [before](https://libc.llvm.org/dev/fuzzing.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/fuzzing.html) | | `libc/docs/dev/header_generation.md` | [before](https://libc.llvm.org/dev/header_generation.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/header_generation.html) | | `libc/docs/dev/implementation_standard.md` | [before](https://libc.llvm.org/dev/implementation_standard.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/implementation_standard.html) | | `libc/docs/dev/implementing_a_function.md` | [before](https://libc.llvm.org/dev/implementing_a_function.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/implementing_a_function.html) | | `libc/docs/dev/index.md` | [before](https://libc.llvm.org/dev/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/index.html) | | `libc/docs/dev/modular_format.md` | [before](https://libc.llvm.org/dev/modular_format.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/modular_format.html) | | `libc/docs/dev/printf_behavior.md` | [before](https://libc.llvm.org/dev/printf_behavior.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/printf_behavior.html) | | `libc/docs/dev/source_tree_layout.md` | [before](https://libc.llvm.org/dev/source_tree_layout.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/source_tree_layout.html) | | `libc/docs/dev/syscall_wrapper_refactor.md` | [before](https://libc.llvm.org/dev/syscall_wrapper_refactor.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/syscall_wrapper_refactor.html) | | `libc/docs/dev/undefined_behavior.md` | [before](https://libc.llvm.org/dev/undefined_behavior.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/dev/undefined_behavior.html) | | `libc/docs/full_cross_build.md` | [before](https://libc.llvm.org/full_cross_build.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/full_cross_build.html) | | `libc/docs/full_host_build.md` | [before](https://libc.llvm.org/full_host_build.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/full_host_build.html) | | `libc/docs/getting_started.md` | [before](https://libc.llvm.org/getting_started.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/getting_started.html) | | `libc/docs/hand_in_hand.md` | [before](https://libc.llvm.org/hand_in_hand.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/hand_in_hand.html) | | `libc/docs/index.md` | [before](https://libc.llvm.org/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/index.html) | | `libc/docs/overlay_mode.md` | [before](https://libc.llvm.org/overlay_mode.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/overlay_mode.html) | | `libc/docs/platform_support.md` | [before](https://libc.llvm.org/platform_support.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/platform_support.html) | | `libc/docs/porting.md` | [before](https://libc.llvm.org/porting.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/porting.html) | | `libc/docs/talks.md` | [before](https://libc.llvm.org/talks.html) | [after](https://llvmdocs.staging.reidkleckner.dev/libc/talks.html) | --- Patch is 301.81 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/208374.diff 30 Files Affected: - (modified) libc/docs/arch_support.md (+10-11) - (modified) libc/docs/build_and_test.md (+67-74) - (modified) libc/docs/build_concepts.md (+33-43) - (modified) libc/docs/compiler_support.md (+12-17) - (modified) libc/docs/conf.py (+6) - (modified) libc/docs/contributing.md (+21-26) - (modified) libc/docs/dev/building_docs.md (+49-56) - (modified) libc/docs/dev/builtin_compatibility.md (+175-345) - (modified) libc/docs/dev/code_style.md (+206-217) - (modified) libc/docs/dev/config_options.md (+81-91) - (modified) libc/docs/dev/entrypoints.md (+56-62) - (modified) libc/docs/dev/fuzzing.md (+7-8) - (modified) libc/docs/dev/header_generation.md (+74-77) - (modified) libc/docs/dev/implementation_standard.md (+52-48) - (modified) libc/docs/dev/implementing_a_function.md (+28-38) - (modified) libc/docs/dev/index.md (+19-20) - (modified) libc/docs/dev/modular_format.md (+16-21) - (modified) libc/docs/dev/printf_behavior.md (+60-67) - (modified) libc/docs/dev/source_tree_layout.md (+55-67) - (modified) libc/docs/dev/syscall_wrapper_refactor.md (+41-44) - (modified) libc/docs/dev/undefined_behavior.md (+89-93) - (modified) libc/docs/full_cross_build.md (+137-147) - (modified) libc/docs/full_host_build.md (+164-166) - (modified) libc/docs/getting_started.md (+67-73) - (modified) libc/docs/hand_in_hand.md (+17-16) - (modified) libc/docs/index.md (+86-86) - (modified) libc/docs/overlay_mode.md (+62-72) - (modified) libc/docs/platform_support.md (+8-9) - (modified) libc/docs/porting.md (+48-56) - (modified) libc/docs/talks.md (+84-88) ``````````diff diff --git a/libc/docs/arch_support.md b/libc/docs/arch_support.md index 6ab0486c7ea22..a9b389e2ca91e 100644 --- a/libc/docs/arch_support.md +++ b/libc/docs/arch_support.md @@ -1,19 +1,18 @@ -Architecture Support -==================== +# Architecture Support The currently continuously tested architectures are: -* aarch64 -* amdgpu -* arm -* nvptx -* riscv32 -* riscv64 -* x86_64 +- aarch64 +- amdgpu +- arm +- nvptx +- riscv32 +- riscv64 +- x86_64 i386 support is [in the works](https://github.com/llvm/llvm-project/issues/93709). -See "`Bringup on a New OS or Architecture <porting.html>`__" for more +See {doc}`Bringup on a New OS or Architecture <porting>` for more information. Please do first file a bug in -`our issue tracker <https://github.com/llvm/llvm-project/labels/libc>`__ before +[our issue tracker](https://github.com/llvm/llvm-project/labels/libc) before starting a port that you plan to upstream. diff --git a/libc/docs/build_and_test.md b/libc/docs/build_and_test.md index da87afa50a3f0..77824e59cb1f9 100644 --- a/libc/docs/build_and_test.md +++ b/libc/docs/build_and_test.md @@ -1,95 +1,89 @@ -.. _build_and_test: +(build_and_test)= -============================= -Building and Testing the libc -============================= +# Building and Testing the libc -Build modes -=========== +## Build modes The libc can be built and tested in two different modes: -#. **The overlay mode** - In this mode, one uses the static archive from LLVM's - libc along with the system libc. See :ref:`overlay_mode` for more details +1. **The overlay mode** - In this mode, one uses the static archive from LLVM's + libc along with the system libc. See {ref}`overlay_mode` for more details on building and using the libc in this mode. You can only run the libc unittests in this mode. To run them, one simply does: - .. code-block:: sh - - $> ninja check-libc + ```sh + $> ninja check-libc + ``` Note that, unittests for only those functions which are part of the overlay static archive will be run with the above command. -#. **The full build mode** - In this mode, the libc is used as the only libc - for the user's application. See :ref:`full_host_build` for more details on +2. **The full build mode** - In this mode, the libc is used as the only libc + for the user's application. See {ref}`full_host_build` for more details on building and using the libc in this mode. Once configured for a full libc build, you can run three kinds of tests: - #. Unit tests - You can run unittests by the command: - - .. code-block:: sh - - $> ninja check-libc + 1. Unit tests - You can run unittests by the command: - #. Integration tests - You can run integration tests by the command: + ```sh + $> ninja check-libc + ``` - .. code-block:: sh + 2. Integration tests - You can run integration tests by the command: - $> ninja libc-integration-tests + ```sh + $> ninja libc-integration-tests + ``` - #. Shared tests - You can run tests for shared, standalone components (like math primitives) without needing the full libc runtime by the command: + 3. Shared tests - You can run tests for shared, standalone components (like math primitives) without needing the full libc runtime by the command: - .. code-block:: sh + ```sh + $> ninja libc-shared-tests + ``` - $> ninja libc-shared-tests - -Building with VSCode -==================== +## Building with VSCode As a quickstart to using VSCode for development, install the cmake extension and put the following in your settings.json file: -.. code-block:: javascript - - { - "cmake.sourceDirectory": "${workspaceFolder}/runtimes", - "cmake.configureSettings": { - "LLVM_ENABLE_RUNTIMES" : ["libc", "compiler-rt"], - "LLVM_LIBC_FULL_BUILD" : true, - "LLVM_ENABLE_SPHINX" : true, - "LIBC_INCLUDE_DOCS" : true, - "LLVM_LIBC_INCLUDE_SCUDO" : true, - "COMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC": true, - "COMPILER_RT_BUILD_GWP_ASAN" : false, - "COMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED" : false, - "CMAKE_EXPORT_COMPILE_COMMANDS" : true, - "LIBC_CMAKE_VERBOSE_LOGGING" : true - } - } +```javascript +{ + "cmake.sourceDirectory": "${workspaceFolder}/runtimes", + "cmake.configureSettings": { + "LLVM_ENABLE_RUNTIMES" : ["libc", "compiler-rt"], + "LLVM_LIBC_FULL_BUILD" : true, + "LLVM_ENABLE_SPHINX" : true, + "LIBC_INCLUDE_DOCS" : true, + "LLVM_LIBC_INCLUDE_SCUDO" : true, + "COMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC": true, + "COMPILER_RT_BUILD_GWP_ASAN" : false, + "COMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED" : false, + "CMAKE_EXPORT_COMPILE_COMMANDS" : true, + "LIBC_CMAKE_VERBOSE_LOGGING" : true + } +} +``` -Building with Bazel -=================== +## Building with Bazel -#. To build with Bazel, use the following command: +1. To build with Bazel, use the following command: - .. code-block:: sh + ```sh + $> bazel build --config=generic_clang @llvm-project//libc/... + ``` - $> bazel build --config=generic_clang @llvm-project//libc/... +1. To run the unit tests with bazel, use the following command: -#. To run the unit tests with bazel, use the following command: + ```sh + $> bazel test --config=generic_clang @llvm-project//libc/... + ``` - .. code-block:: sh +1. The bazel target layout of `libc` is located at: [utils/bazel/llvm-project-overlay/libc/BUILD.bazel](https://github.com/llvm/llvm-project/tree/main/utils/bazel/llvm-project-overlay/libc/BUILD.bazel). - $> bazel test --config=generic_clang @llvm-project//libc/... +## Building in a container for a different architecture -#. The bazel target layout of `libc` is located at: `utils/bazel/llvm-project-overlay/libc/BUILD.bazel <https://github.com/llvm/llvm-project/tree/main/utils/bazel/llvm-project-overlay/libc/BUILD.bazel>`_. - -Building in a container for a different architecture -==================================================== - -`Podman <https://podman.io/>`_ can be used together with -`QEMU <https://www.qemu.org/>`_ to run container images built for architectures +[Podman](https://podman.io/) can be used together with +[QEMU](https://www.qemu.org/) to run container images built for architectures other than the host's. This can be used to build and test the libc on other supported architectures for which you do not have access to hardware. It can also be used if the hardware is slower than emulation of its architecture on a @@ -97,27 +91,26 @@ more powerful machine under a different architecture. As an example, to build and test in a container for 32-bit Arm: -#. To install the necessary packages on Arch Linux: +1. To install the necessary packages on Arch Linux: - .. code-block:: sh + ```sh + $> pacman -S podman qemu-user-static qemu-user-static-binfmt \ + qemu-system-arm + ``` - $> pacman -S podman qemu-user-static qemu-user-static-binfmt \ - qemu-system-arm - -#. To run Bash interactively in an Ubuntu 22.04 container for 32-bit Arm and +2. To run Bash interactively in an Ubuntu 22.04 container for 32-bit Arm and bind-mount an existing checkout of llvm-project on the host: - .. code-block:: sh - - $> podman run -it \ - -v </host/path/to/llvm-project>:</container/path/to/llvm-project> \ - --arch arm docker.io/ubuntu:jammy bash + ```sh + $> podman run -it \ + -v </host/path/to/llvm-project>:</container/path/to/llvm-project> \ + --arch arm docker.io/ubuntu:jammy bash + ``` -#. Install necessary packages, invoke CMake, build, and run tests. +3. Install necessary packages, invoke CMake, build, and run tests. -Building and Testing with an Emulator -===================================== +## Building and Testing with an Emulator If you are cross-compiling the libc for a different architecture, you can use an emulator such as QEMU to run the tests directly on your host without a container. See -:ref:`full_cross_build` for detailed instructions on configuring CMake to use an emulator. +{ref}`full_cross_build` for detailed instructions on configuring CMake to use an emulator. diff --git a/libc/docs/build_concepts.md b/libc/docs/build_concepts.md index 04571c4bb9198..a6a9374497809 100644 --- a/libc/docs/build_concepts.md +++ b/libc/docs/build_concepts.md @@ -1,8 +1,6 @@ -.. _build_concepts: +(build_concepts)= -============== -Build Concepts -============== +# Build Concepts Most people don't need to build their own C library — the one provided by their system works well. However, LLVM-libc's **Overlay Mode** can provide key updates @@ -11,66 +9,58 @@ like faster or more consistent math functions for projects that need them. For those who do need a full C library, LLVM-libc supports several build configurations depending on your target environment and intended usage. -The Five Build Scenarios -======================== +## The Five Build Scenarios -1. Overlay Mode (Augmenting the System Libc) --------------------------------------------- +### 1. Overlay Mode (Augmenting the System Libc) -In Overlay Mode, LLVM-libc functions are compiled alongside the host's existing -system library (like ``glibc``). Only the functions explicitly implemented in -LLVM-libc are used; the rest "fall back" to the system library. This is the +In Overlay Mode, LLVM-libc functions are compiled alongside the host's existing +system library (like `glibc`). Only the functions explicitly implemented in +LLVM-libc are used; the rest "fall back" to the system library. This is the preferred method for most contributors as it is the fastest to build and test. -To configure for an overlay build, point CMake to the ``runtimes`` directory -and set ``LLVM_LIBC_FULL_BUILD=OFF`` (which is the default). This will build a -static archive named ``libllvmlibc.a``: +To configure for an overlay build, point CMake to the `runtimes` directory +and set `LLVM_LIBC_FULL_BUILD=OFF` (which is the default). This will build a +static archive named `libllvmlibc.a`: -.. code-block:: sh +```sh +cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc" \ + -DLLVM_LIBC_FULL_BUILD=OFF ... +``` - cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc" \ - -DLLVM_LIBC_FULL_BUILD=OFF ... +### 2. Full Build Mode (Standalone Library) -2. Full Build Mode (Standalone Library) ---------------------------------------- - -In Full Build Mode, LLVM-libc is a complete replacement for the system library. -This is used to build standalone ``libc.a`` and ``libm.a`` (with separate CMake +In Full Build Mode, LLVM-libc is a complete replacement for the system library. +This is used to build standalone `libc.a` and `libm.a` (with separate CMake targets) for a new operating system or to generate a sysroot for a specific target. -To configure for a full build, set ``LLVM_LIBC_FULL_BUILD=ON``: - -.. code-block:: sh +To configure for a full build, set `LLVM_LIBC_FULL_BUILD=ON`: - cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \ - -DLLVM_LIBC_FULL_BUILD=ON ... +```sh +cmake -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \ + -DLLVM_LIBC_FULL_BUILD=ON ... +``` -3. Bootstrap Build ------------------- +### 3. Bootstrap Build A bootstrap build first builds the compiler (Clang) and other LLVM tools using the host compiler, and then uses that newly-built Clang to build the libc. This ensures you are using a matched toolchain where the compiler and the library are built for each other. -To configure a bootstrap build, you point CMake to the ``llvm`` directory: - -.. code-block:: sh +To configure a bootstrap build, you point CMake to the `llvm` directory: - cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" ... +```sh +cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" ... +``` -4. Cross-compiler Build (Targeting Other Architectures) -------------------------------------------------------- +### 4. Cross-compiler Build (Targeting Other Architectures) -Used when you want to build LLVM-libc for a different architecture than you are -currently running on (e.g., building on x86_64 for an aarch64 target). +Used when you want to build LLVM-libc for a different architecture than you are +currently running on (e.g., building on x86_64 for an aarch64 target). This requires a cross-compiler or a toolchain file. -5. Bootstrap Cross-compiler (New Environment) ---------------------------------------------- +### 5. Bootstrap Cross-compiler (New Environment) -For users who are starting from scratch (e.g., with only Linux kernel headers) -and want to generate a full C compiler and sysroot for their target. This is +For users who are starting from scratch (e.g., with only Linux kernel headers) +and want to generate a full C compiler and sysroot for their target. This is the most common path for those building entire environments to tinker in. - - diff --git a/libc/docs/compiler_support.md b/libc/docs/compiler_support.md index 00234c22dc2e6..790541f9d4290 100644 --- a/libc/docs/compiler_support.md +++ b/libc/docs/compiler_support.md @@ -1,24 +1,19 @@ -.. _compiler_support: +(compiler_support)= -================ -Compiler Support -================ +# Compiler Support -``LLVM libc`` compiles from both ``Clang`` and ``GCC`` but for maximum -performance we recommend using ``Clang``. +`LLVM libc` compiles from both `Clang` and `GCC` but for maximum +performance we recommend using `Clang`. -Indeed, some memory function implementations rely on `compiler intrinsics`__ -that are not currently available in ``GCC``. +Indeed, some memory function implementations rely on [compiler intrinsics](https://clang.llvm.org/docs/LanguageExtensions.html#guaranteed-inlined-copy) +that are not currently available in `GCC`. As such we cannot guarantee optimal performance for these functions. -.. __: https://clang.llvm.org/docs/LanguageExtensions.html#guaranteed-inlined-copy +For platforms where only `GCC` is natively available but maximum performance +is required it is possible to bootstrap `Clang` with `GCC` and then use +`Clang` to build the `libc` project. -For platforms where only ``GCC`` is natively available but maximum performance -is required it is possible to bootstrap ``Clang`` with ``GCC`` and then use -``Clang`` to build the '`libc``" project. +## Minimum supported versions -Minimum supported versions -========================== - - - ``Clang 11`` - - ``GCC 12.2`` +- `Clang 11` +- `GCC 12.2` diff --git a/libc/docs/conf.py b/libc/docs/conf.py index 1490e7bde7411..0aec05980b6f0 100644 --- a/libc/docs/conf.py +++ b/libc/docs/conf.py @@ -27,6 +27,8 @@ "sphinx_reredirects", ] +myst_enable_extensions += ["deflist"] + # General information about the project. project = "libc" copyright = "2011-%d, LLVM Project" % date.today().year @@ -61,6 +63,10 @@ .. |check| replace:: :raw-html:`✅` """ +myst_substitutions = { + "check": "\N{WHITE HEAVY CHECK MARK}", +} + # The reST default role (used for this markup: `text`) to use for all documents. # default_role = None diff --git a/libc/docs/contributing.md b/libc/docs/contributing.md index a8d7fad67b813..8e53f8f5501b9 100644 --- a/libc/docs/contributing.md +++ b/libc/docs/contributing.md @@ -1,46 +1,41 @@ -.. _contributing: +(contributing)= -================================ -Contributing to the libc Project -================================ +# Contributing to the libc Project LLVM-libc is being developed as part of the LLVM project so contributions to the libc project should also follow the general LLVM -`contribution guidelines <https://llvm.org/docs/Contributing.html>`_. Below is +[contribution guidelines](https://llvm.org/docs/Contributing.html). Below is a list of open projects that one can start with: -#. **Beginner Bugs** - Help us tackle - `good first issues <https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Alibc+label%3A%22good+first+issue%22>`__. +1. **Beginner Bugs** - Help us tackle + [good first issues](https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Alibc+label%3A%22good+first+issue%22). These bugs have been tagged with the github labels "libc" and "good first - issue" by the team as potentially easier places to get started. Please do + issue" by the team as potentially easier places to get started. Please do first check if the bug has an assignee; if so please find another unless there's been no movement on the issue from the assignee, in which place do ask if you can help take over. - -#. **Cleanup code-style** - The libc project follows the general - `LLVM style <https://llvm.org/docs/CodingStandards.html>`_ with specific - conventions for naming (``snake_case`` for functions, ``CamelCase`` for - types). See the :ref:`code_style` page for the authoritative reference. +2. **Cleanup code-style** - The libc project follows the general + [LLVM style](https://llvm.org/docs/CodingStandards.html) with specific + conventions for naming (`snake_case` for functions, `CamelCase` for + types). See the {doc}`code style <dev/code_style>` page for the + authoritative reference. Mechanical projects to move parts following old styles to the current conventions are welcome. - -#. **Implement Linux syscall wrappers** - A large portion of the POSIX API can +3. **Implement Linux syscall wrappers** - A large portion of the POSIX API can be implemented as syscall wrappers on Linux. A good number have already been implemented but many more are yet to be implemented. So, a project of medium complexity would be to implement syscall wrappers which have not yet been implemented. - -#. **Update the clang-tidy lint rules and use them in the build and/or CI** - - The libc project has a set of clang-tidy checks (see :ref:`clang_tidy_checks`) +4. **Update the clang-tidy lint rules and use them in the build and/or CI** - + The libc project has a set of clang-tidy checks (see + {ref}`clang-tidy checks <clang_tidy_checks>`) but they are not enabled by default. They can be enabled by configuring with - ``-DLLVM_LIBC_ENABLE_LINTING=ON`` (or by setting ``LLVM_LIBC_CLANG_TIDY``) and - running the ``libc-lint`` build target. This project is about keeping the + `-DLLVM_LIBC_ENABLE_LINTING=ON` (or by setting `LLVM_LIBC_CLANG_TIDY`) and + running the `libc-lint` build target. This project is about keeping the checks up to date and reintegrating them into the build and CI. - -#. **double and higher precision math functions** - These are under active +5. **double and higher precision math functions** - These are under active development but you can take a shot at those not yet implemented. See - :ref:`math` for more information. - -#. **Contribute a new OS/Architecture port** - You can contribute a new - operating system or target architecture port. See :ref:`porting` for more + {ref}`math` for more information. +6. **Contribute a new OS/Architecture port** - You can contribute a new + operating system or target architecture port. See {ref}`porting` for more information. diff --git a/libc/docs/dev/building_docs.md b/libc/docs/dev/building_docs.md index 567f717bbd34a..cf262827c9ab4 100644 --- a/libc/docs/dev/building_docs.md +++ b/libc/docs/dev/building_docs.md @@ -1,93 +1,86 @@ -.. _building_docs: +(building_docs)= -========================== -Building the Documentation -========================== +# Building the Documentation This page explains how to build the LLVM-libc HTML documentation locally so you can preview changes before submitting a patch. -Prerequisites -============= +## Prerequisites -The LLVM documentation build uses `Sphinx <https://www.sphinx-doc.org/>`__. +The LLVM documentation build uses [Sphinx](https://www.sphinx-doc.org/). The key packages required are: -* ``sphinx`` — the documentation generator -* ``furo`` — the theme used by LLVM-libc -* ``myst-parser`` — Markdown support alongside RST -* ``sphinx-reredirects`` — handles page redirect entries in ``conf.py`` +- `sphinx` — the documentation generator +- `furo` — the theme used by LLVM-libc +- `myst-parser` — Markdown support alongside RST +- `sphinx-reredirects` — handles pag... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/208374 _______________________________________________ llvm-branch-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-branch-commits
