[libc-commits] [libc] 692c77f - [libc][docs] reorder docs to be more beginner friendly (#122376)
via libc-commits
libc-commits at lists.llvm.org
Tue Jan 14 09:38:19 PST 2025
Author: Nick Desaulniers
Date: 2025-01-14T09:38:15-08:00
New Revision: 692c77f2af133874f18942fe8c32f0f072bfc02b
URL: https://github.com/llvm/llvm-project/commit/692c77f2af133874f18942fe8c32f0f072bfc02b
DIFF: https://github.com/llvm/llvm-project/commit/692c77f2af133874f18942fe8c32f0f072bfc02b.diff
LOG: [libc][docs] reorder docs to be more beginner friendly (#122376)
This commit does a few things, with the intent to make it more straightforward
to potential future users how to get started with llvm-libc. Answers to "What's
the status and how do I use it?" are front and center, "above the fold."
This commit does a few things:
* reorganize the landing page's toctree: start with implementation status, arch
* support, platform support, and
compiler support.
* Then a (new) simple getting started page using full host builds. Then more
* Advanced topics such as host vs cross builds, overlay mode,
gpu builds and additional configuration options.
* Remove c23 status, the old fullbuild_mode landing page, and
usage_modes landing pages. c23 status isn't as interesting as I originally
thought it might.
We should point people at full host builds to start, then link to more info on
cross compilation, or overlay mode as more advanced topics. I assert most users
starting out won't care about those.
Added:
libc/docs/getting_started.rst
Modified:
libc/docs/build_and_test.rst
libc/docs/index.rst
libc/docs/porting.rst
Removed:
libc/docs/c23.rst
libc/docs/fullbuild_mode.rst
libc/docs/usage_modes.rst
################################################################################
diff --git a/libc/docs/build_and_test.rst b/libc/docs/build_and_test.rst
index ccd8b5bbee4759..dfdd96531b1f90 100644
--- a/libc/docs/build_and_test.rst
+++ b/libc/docs/build_and_test.rst
@@ -22,7 +22,7 @@ The libc can be built and tested in two
diff erent modes:
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:`fullbuild_mode` for more details on
+ 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:
diff --git a/libc/docs/c23.rst b/libc/docs/c23.rst
deleted file mode 100644
index b9a2424307f84b..00000000000000
--- a/libc/docs/c23.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-.. _c23_support:
-
-===========
-C23 Support
-===========
-
-.. include:: check.rst
-.. contents:: Table of Contents
- :depth: 4
- :local:
-
----------------------
-Implementation Status
----------------------
-
-(It's helpful to review 'Annex B (Informative) Library Summary' for these.)
-
-
-Additions:
-
-* fenv.h
-
- * fesetexcept |check|
- * fetestexceptflag |check|
- * fegetmode
- * fesetmode
-* math.h
-
- * acospi*
- * asinpi*
- * atanpi*
- * atan2pi*
- * cospi*
- * sinpi*
- * tanpi*
- * exp10*
- * exp10m1*
- * exp2m1*
- * log10p1*
- * logp1
- * log2p1*
- * rsqrt*
- * __STDC_IEC_60559_DFP__ functions (_Decimal32, _Decimal64, _Decimal128)
- * compoundn*
- * totalorder* |check|
- * totalordermag* |check|
- * getpayload* |check|
- * setpayload* |check|
- * setpayloadsig* |check|
- * iscannonical
- * issignaling
- * issubnormal
- * iszero
- * llogb* |check|
- * pown*
- * powr*
- * rootn*
- * roundeven* |check|
- * fromfp* |check|
- * ufromfp* |check|
- * fromfpx* |check|
- * ufromfpx* |check|
- * nextup* |check|
- * nextdown* |check|
- * canonicalize* |check|
- * fmaximum* |check|
- * fminimum* |check|
- * fmaximum_mag* |check|
- * fminimum_mag* |check|
- * fmaximum_num* |check|
- * fminimum_num* |check|
- * fmaximum_mag_num* |check|
- * fminimum_mag_num* |check|
- * fadd*
- * fsub*
- * fmul*
- * fdiv*
- * ffma*
- * dfmal
- * fsqrt*
- * dsqrtl
-* stdbit.h (New header) |check|
-* stdckdint.h (New header) |check|
-* stddef.h
-
- * unreachable
-* stdlib.h
-
- * strfromd
- * strfromf
- * strfroml
- * free_sized
- * free_aligned_sized
- * memalignment
-* string.h
-
- * memset_explicit |check|
- * memccpy
- * strdup
- * strndup
-* tgmath.h
-
- * acospi
- * asinpi
- * atan2pi
- * atanpi
- * compoundn
- * cospi
- * erf
- * exp10m1
- * exp10
- * exp2m1
- * fmaximum
- * fmaximum_mag
- * fmaximum_num
- * fmaximum_mag_num
- * fminimum
- * fminimum_mag
- * fminimum_num
- * fminimum_mag_num
- * fromfpx
- * fromfp
- * llogb
- * log10p1
- * log2p1
- * logp1
- * nextdown
- * nextup
- * pown
- * powr
- * rootn
- * roundeven
- * rsqrt
- * scalbn
- * sinpi
- * tanpi
- * ufromfpx
- * ufromfp
- * fadd
- * dadd
- * fsub
- * dsub
- * fmul
- * dmul
- * fdiv
- * ddiv
- * ffma
- * dfma
- * fsqrt
- * dsqrt
-* time.h
-
- * gmtime_r
- * localtime_r
- * timegm
- * timespec_getres
- * strftime conversion specifiers
-
- * 0b
- * 0B
-* uchar.h
-
- * mbrtoc8
- * c8rtomb
- * char*_t |check|
diff --git a/libc/docs/fullbuild_mode.rst b/libc/docs/fullbuild_mode.rst
deleted file mode 100644
index d5c62172dac8e7..00000000000000
--- a/libc/docs/fullbuild_mode.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-.. _fullbuild_mode:
-
-==============
-Fullbuild Mode
-==============
-
-.. note::
- Fullbuild requires running headergen, which is a python program that depends on
- pyyaml. The minimum versions are listed on the :ref:`header_generation`
- page, as well as additional information.
-
-The *fullbuild* mode of LLVM's libc is the mode in which it is to be used as
-the only libc (as opposed to the :ref:`overlay_mode` in which it is used along
-with the system libc.) In order to use it as the only libc, one will have to
-build and install not only the static archives like ``libc.a`` from LLVM's libc,
-but also the start-up objects like ``crt1.o`` and the public headers.
-
-The full libc build can be of two types:
-
-.. toctree::
- :maxdepth: 1
-
- full_host_build
- full_cross_build
diff --git a/libc/docs/getting_started.rst b/libc/docs/getting_started.rst
new file mode 100644
index 00000000000000..51c295f384a06f
--- /dev/null
+++ b/libc/docs/getting_started.rst
@@ -0,0 +1,58 @@
+Getting Started
+===============
+
+Let's fetch the llvm-libc sources and build them.
+
+Install dependencies first:
+
+.. code-block:: sh
+
+ $ sudo apt update
+ $ sudo apt install git cmake ninja-build clang gcc-multilib
+
+.. code-block:: sh
+
+ $ git clone --depth=1 git at github.com:llvm/llvm-project.git /tmp/llvm-project
+ $ mkdir /tmp/llvm-project/build
+ $ cd /tmp/llvm-project/build
+ $ cmake ../runtimes -GNinja \
+ -DLLVM_ENABLE_RUNTIMES="libc;compiler-rt" \
+ -DCMAKE_BUILD_TYPE=Debug \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -DCMAKE_C_COMPILER=clang \
+ -DLLVM_LIBC_FULL_BUILD=ON \
+ -DLLVM_LIBC_INCLUDE_SCUDO=ON \
+ -DCOMPILER_RT_BUILD_SCUDO_STANDALONE_WITH_LLVM_LIBC=ON \
+ -DCOMPILER_RT_BUILD_GWP_ASAN=OFF \
+ -DCOMPILER_RT_SCUDO_STANDALONE_BUILD_SHARED=OFF
+ $ ninja libc libm
+
+This will produce the following artifacts:
+
+.. code-block::
+
+ llvm-project/build/libc/lib/libc.a
+ llvm-project/build/libc/lib/libm.a
+ llvm-project/build/libc/startup/linux/crt1.o
+ llvm-project/build/libc/include/**.h
+
+We can then compile and run hello world via:
+
+.. code-block:: c++
+
+ // hello.c
+ #include <stdio.h>
+ int main () { puts("hello world"); }
+
+.. code-block:: sh
+
+ $ clang -nostdinc -nostdlib hello.c -I libc/include \
+ -I $(clang -print-resource-dir)/include libc/startup/linux/crt1.o \
+ libc/lib/libc.a
+ $ ./a.out
+ hello world
+
+This was what we call a "full build" of llvm-libc. From here, you can visit
+:ref:`full_host_build` for more info, :ref:`full_cross_build` for cross
+compiling, :ref:`overlay_mode` for mixing llvm-libc with another libc, or
+:ref:`libc_gpu` for targeting GPUs.
diff --git a/libc/docs/index.rst b/libc/docs/index.rst
index 0cbf75f5e0ef2d..12dcba27a906bb 100644
--- a/libc/docs/index.rst
+++ b/libc/docs/index.rst
@@ -38,31 +38,31 @@ LLVM-libc aspires to a unique place in the software ecosystem. The goals are:
.. toctree::
:hidden:
- :maxdepth: 2
- :caption: Using
+ :maxdepth: 1
+ :caption: Status & Support
- usage_modes
- overlay_mode
- fullbuild_mode
- configure
- gpu/index.rst
+ headers/index.rst
+ arch_support
+ platform_support
+ compiler_support
.. toctree::
:hidden:
:maxdepth: 1
- :caption: Status
+ :caption: Simple Usage
- headers/index.rst
- c23
+ getting_started
.. toctree::
:hidden:
:maxdepth: 1
- :caption: Support
+ :caption: Advanced Usage
- arch_support
- platform_support
- compiler_support
+ full_host_build
+ full_cross_build
+ overlay_mode
+ gpu/index.rst
+ configure
.. toctree::
:hidden:
@@ -73,13 +73,13 @@ LLVM-libc aspires to a unique place in the software ecosystem. The goals are:
dev/index.rst
porting
contributing
- talks
.. toctree::
:hidden:
:maxdepth: 1
- :caption: External Links
+ :caption: Useful Links
+ talks
Source Code <https://github.com/llvm/llvm-project/tree/main/libc>
Bug Reports <https://github.com/llvm/llvm-project/labels/libc>
Discourse <https://discourse.llvm.org/c/runtimes/libc>
diff --git a/libc/docs/porting.rst b/libc/docs/porting.rst
index a4df4e8cf0719d..5747a8b9b0c73c 100644
--- a/libc/docs/porting.rst
+++ b/libc/docs/porting.rst
@@ -68,7 +68,7 @@ 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
:ref:`entrypoints`) you want to include in the static archive of the libc (for
-the :ref:`overlay_mode` and/or the :ref:`fullbuild_mode`.) If you are doing an
+the :ref:`overlay_mode` and/or the :ref:`full_host_build`.) If you are doing an
architecture specific bring up, then an ``entrypoints.txt`` file should be
created in the architecture subdirectory for each architecture. Else, having a
single ``entrypoints.txt`` in the operating system directory is sufficient.
@@ -95,7 +95,7 @@ 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
provided by the libc. This is relevant only if the libc is to be used in the
-:ref:`fullbuild_mode` on the target operating system and architecture. As with
+:ref:`full_host_build` on the target operating system and architecture. As with
the ``entrypoints.txt`` file, one ``headers.txt`` file should be listed for
each individual target architecture if you are doing an architecture specific
bring up. The Linux config has ``headers.txt`` file listed separately for the
diff --git a/libc/docs/usage_modes.rst b/libc/docs/usage_modes.rst
deleted file mode 100644
index 8e5dcca6e0a75c..00000000000000
--- a/libc/docs/usage_modes.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-===========
-Usage Modes
-===========
-
-The libc can used in two
diff erent modes:
-
-#. The **overlay** mode: In this mode, the link order semantics are exploited
- to overlay implementations from LLVM's libc over the system libc. See
- :ref:`overlay_mode` for more information about this mode. In this mode, libc
- uses the ABI of the system it's being overlayed onto. Headers are NOT
- generated. libllvmlibc.a is the only build artifact.
-#. The **fullbuild** mode: In this mode, LLVM's libc is used as the only libc
- for the binary. See :ref:`fullbuild_mode` for information about this mode.
- In this mode, libc uses its own ABI. Headers are generated along with a
- libc.a.
More information about the libc-commits
mailing list