[libc][docs] reorder docs to be more beginner friendly

libc/docs/build_and_test.rst

@@ -22,7 +22,7 @@ The libc can be built and tested in two different 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:
 

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 [email protected]: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.

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>

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