[llvm] 6b4c4d7 - [llvm][docs] Improve the formatting of the Common Problems section (#108522)

[via llvm-commits]

Author: David Spickett
Date: 2024-10-08T10:00:31+01:00
New Revision: 6b4c4d78f03b83a371e239844d2f86dafeed6b53

URL: https://github.com/llvm/llvm-project/commit/6b4c4d78f03b83a371e239844d2f86dafeed6b53
DIFF: https://github.com/llvm/llvm-project/commit/6b4c4d78f03b83a371e239844d2f86dafeed6b53.diff

LOG: [llvm][docs] Improve the formatting of the Common Problems section (#108522)

...and add shared libs as a suggestion.

* Mark options, option values and program names as plain text.
* Add a blank line between the option and the explanatory text
  so that it doesn't get printed on the same line.
  (this seems to be the original intent of the rst source anyway)
* Update the phrasing of a couple of the options.
* Add BUILD_SHARED_LIBS to suggestions.

Added: 
    

Modified: 
    llvm/docs/CMake.rst
    llvm/docs/GettingStarted.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index 321bae48594cf9..4364029f71c6dc 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -309,6 +309,8 @@ These variables provide fine control over the build of LLVM and
 enabled sub-projects. Nearly all of these variable names begin with
 ``LLVM_``.
 
+.. _LLVM-related variables BUILD_SHARED_LIBS:
+
 **BUILD_SHARED_LIBS**:BOOL
   Flag indicating if each LLVM component (e.g. Support) is built as a shared
   library (ON) or as a static library (OFF). Its default value is OFF. On

diff  --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index e03ae5effcdc44..8ef1f85d6b6fd7 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -1085,67 +1085,89 @@ general questions about LLVM, please consult the `Frequently Asked
 Questions <FAQ.html>`_ page.
 
 If you are having problems with limited memory and build time, please try
-building with ninja instead of make. Please consider configuring the
+building with ``ninja`` instead of ``make``. Please consider configuring the
 following options with cmake:
 
- * -G Ninja
+ * ``-G Ninja``
+
    Setting this option will allow you to build with ninja instead of make.
    Building with ninja significantly improves your build time, especially with
    incremental builds, and improves your memory usage.
 
- * -DLLVM_USE_LINKER
-   Setting this option to lld will significantly reduce linking time for LLVM
-   executables on ELF-based platforms, such as Linux. If you are building LLVM
+ * ``-DLLVM_USE_LINKER``
+
+   Setting this option to ``lld`` will significantly reduce linking time for LLVM
+   executables, particularly on Linux and Windows. If you are building LLVM
    for the first time and lld is not available to you as a binary package, then
    you may want to use the gold linker as a faster alternative to GNU ld.
 
- * -DCMAKE_BUILD_TYPE
+ * ``-DCMAKE_BUILD_TYPE``
+
    Controls optimization level and debug information of the build.  This setting
    can affect RAM and disk usage, see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`
    for more information.
 
- * -DLLVM_ENABLE_ASSERTIONS
-   This option defaults to ON for Debug builds and defaults to OFF for Release
+ * ``-DLLVM_ENABLE_ASSERTIONS``
+
+   This option defaults to ``ON`` for Debug builds and defaults to ``OFF`` for Release
    builds. As mentioned in the previous option, using the Release build type and
    enabling assertions may be a good alternative to using the Debug build type.
 
- * -DLLVM_PARALLEL_LINK_JOBS
+ * ``-DLLVM_PARALLEL_LINK_JOBS``
+
    Set this equal to number of jobs you wish to run simultaneously. This is
-   similar to the -j option used with make, but only for link jobs. This option
+   similar to the ``-j`` option used with ``make``, but only for link jobs. This option
    can only be used with ninja. You may wish to use a very low number of jobs,
    as this will greatly reduce the amount of memory used during the build
-   process. If you have limited memory, you may wish to set this to 1.
+   process. If you have limited memory, you may wish to set this to ``1``.
+
+ * ``-DLLVM_TARGETS_TO_BUILD``
 
- * -DLLVM_TARGETS_TO_BUILD
    Set this equal to the target you wish to build. You may wish to set this to
-   X86; however, you will find a full list of targets within the
-   llvm-project/llvm/lib/Target directory.
+   only your host architecture. For example ``X86`` if you are using an Intel or
+   AMD machine. You will find a full list of targets within the
+   `llvm-project/llvm/lib/Target <https://github.com/llvm/llvm-project/tree/main/llvm/lib/Target>`_
+   directory.
+
+ * ``-DLLVM_OPTIMIZED_TABLEGEN``
 
- * -DLLVM_OPTIMIZED_TABLEGEN
-   Set this to ON to generate a fully optimized tablegen during your build. This
-   will significantly improve your build time. This is only useful if you are
-   using the Debug build type.
+   Set this to ``ON`` to generate a fully optimized TableGen compiler during your
+   build, even if that build is a ``Debug`` build. This will significantly improve
+   your build time. You should not enable this if your intention is to debug the
+   TableGen compiler.
 
- * -DLLVM_ENABLE_PROJECTS
-   Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If
+ * ``-DLLVM_ENABLE_PROJECTS``
+
+   Set this equal to the projects you wish to compile (e.g. ``clang``, ``lld``, etc.) If
    compiling more than one project, separate the items with a semicolon. Should
    you run into issues with the semicolon, try surrounding it with single quotes.
 
- * -DLLVM_ENABLE_RUNTIMES
-   Set this equal to the runtimes you wish to compile (e.g. libcxx, libcxxabi, etc.)
+ * ``-DLLVM_ENABLE_RUNTIMES``
+
+   Set this equal to the runtimes you wish to compile (e.g. ``libcxx``, ``libcxxabi``, etc.)
    If compiling more than one runtime, separate the items with a semicolon. Should
    you run into issues with the semicolon, try surrounding it with single quotes.
 
- * -DCLANG_ENABLE_STATIC_ANALYZER
-   Set this option to OFF if you do not require the clang static analyzer. This
+ * ``-DCLANG_ENABLE_STATIC_ANALYZER``
+
+   Set this option to ``OFF`` if you do not require the clang static analyzer. This
    should improve your build time slightly.
 
- * -DLLVM_USE_SPLIT_DWARF
-   Consider setting this to ON if you require a debug build, as this will ease
+ * ``-DLLVM_USE_SPLIT_DWARF``
+
+   Consider setting this to ``ON`` if you require a debug build, as this will ease
    memory pressure on the linker. This will make linking much faster, as the
-   binaries will not contain any of the debug information; however, this will
-   generate the debug information in the form of a DWARF object file (with the
-   extension .dwo). This only applies to host platforms using ELF, such as Linux.
+   binaries will not contain any of the debug information. Instead the debug
+   information is in a separate DWARF object file (with the extension ``.dwo``).
+   This only applies to host platforms using ELF, such as Linux.
+
+ * ``-DBUILD_SHARED_LIBS``
+
+   Setting this to ``ON`` will build shared libraries instead of static
+   libraries. This will ease memory pressure on the linker. However, this should
+   only be used when developing llvm. See
+   :ref:`BUILD_SHARED_LIBS <LLVM-related variables BUILD_SHARED_LIBS>`
+   for more information.
 
 .. _links: