Switch the libc documentation site from the alabaster theme to Furo,
which provides mobile-friendly layout, a collapsible sidebar with
caption-based section grouping, and built-in "Edit this page" links.
Changes by area:
conf.py
- Switch html_theme to "furo"
- Add myst_parser extension (already in llvm/docs/requirements.txt, used
by LLDB/Clang/LLVM docs) to allow Markdown alongside RST
- Accept both .rst and .md source suffixes
- Configure Furo source_repository/source_branch/source_directory for
"Edit this page" links pointing to GitHub
- Wire _static/copybutton.{js,css} for copy-to-clipboard buttons on code
blocks (no new pip dependency; can migrate to sphinx-copybutton later
once it's in requirements-hashed.txt)
- Exclude plan-docs.md and Helpers/ from Sphinx processing
index.rst
- Rewrite landing page: remove apologetic "not fully complete" note, add
"What Works Today" section with concrete supported use cases, honest
caveat that full C stdlib coverage is still in progress
- Restructure hidden toctrees into five captioned sidebar groups: "Using
LLVM-libc", "Platforms" (GPU/UEFI promoted to top-level),
"Implementation Status", "Development", "Links"
New files
- docs/_static/copybutton.{js,css}: lightweight copy button for code
blocks
- docs/_static/custom.css: add status badge styles (.badge-complete
etc.) for use with Helpers/Styles.rst substitutions in later phases
Prepare for future status badges:
- docs/Helpers/Styles.rst: RST substitution definitions for status
badges (|Complete|, |Partial|, |InProgress|, |NotStarted|, |GPUOnly|,
|LinuxOnly|) — excluded from toctree, available for Phase 5+ pages
- docs/dev/building_docs.rst: new page covering prerequisites (with
Debian apt-first instructions), CMake flags, ninja docs-libc-html, the
docgen auto-generation pipeline, and troubleshooting
Removed
- docs/README.txt: stale file claiming Sphinx 1.1.3, not in any toctree;
superseded by docs/dev/building_docs.rst
Cleanups
- Remove redundant ".. contents:: Table of Contents" directives from 16
RST files (Furo renders its own per-page TOC in the sidebar)
- Remove same directive from libc/Maintainers.rst (pulled into docs via
include)
Summary:
I forgot that the OpenMP tests still look for this, reverting for now
until I can make a fix.
This reverts commit c1c6ed83e9ac13c511961e5f5791034a63168e7e.
Summary:
Previously, the GPU built the `libc` in a fat binary version that was
used to pass this to the link job in offloading languages like CUDA or
OpenMP. This was mostly required because NVIDIA couldn't consume the
standard static library version. Recent patches have now created the
`clang-nvlink-wrapper` which lets us do that. Now, the C library is just
included implicitly by the toolchain (or passed with -Xoffload-linker
-lc).
This code can be fully removed, which will heavily simplify the build
(and removed some bugs and garbage files I've encoutnered).
Summary:
After the overhaul of the GPU build the documentation pages were a
little stale. This updates them with more in-depth information on
building the GPU runtimes and using them. Specifically using them goes
through the differences between the offloading and direct compilation
modes.
Summary:
This is a massive patch because it reworks the entire build and
everything that depends on it. This is not split up because various bots
would fail otherwise. I will attempt to describe the necessary changes
here.
This patch completely reworks how the GPU build is built and targeted.
Previously, we used a standard runtimes build and handled both NVPTX and
AMDGPU in a single build via multi-targeting. This added a lot of
divergence in the build system and prevented us from doing various
things like building for the CPU / GPU at the same time, or exporting
the startup libraries or running tests without a full rebuild.
The new appraoch is to handle the GPU builds as strict cross-compiling
runtimes. The first step required
https://github.com/llvm/llvm-project/pull/81557 to allow the `LIBC`
target to build for the GPU without touching the other targets. This
means that the GPU uses all the same handling as the other builds in
`libc`.
The new expected way to build the GPU libc is with
`LLVM_LIBC_RUNTIME_TARGETS=amdgcn-amd-amdhsa;nvptx64-nvidia-cuda`.
The second step was reworking how we generated the embedded GPU library
by moving it into the library install step. Where we previously had one
`libcgpu.a` we now have `libcgpu-amdgpu.a` and `libcgpu-nvptx.a`. This
patch includes the necessary clang / OpenMP changes to make that not
break the bots when this lands.
We unfortunately still require that the NVPTX target has an `internal`
target for tests. This is because the NVPTX target needs to do LTO for
the provided version (The offloading toolchain can handle it) but cannot
use it for the native toolchain which is used for making tests.
This approach is vastly superior in every way, allowing us to treat the
GPU as a standard cross-compiling target. We can now install the GPU
utilities to do things like use the offload tests and other fun things.
Some certain utilities need to be built with
`--target=${LLVM_HOST_TRIPLE}` as well. I think this is a fine
workaround as we
will always assume that the GPU `libc` is a cross-build with a
functioning host.
Depends on https://github.com/llvm/llvm-project/pull/81557
This patch updates some of the documentation for the GPU libc project.
There is a lot of work still to be done, but this sets the general
outline.
Reviewed By: jdoerfert
Differential Revision: https://reviews.llvm.org/D149194
