[llvm][docs] Improve the formatting of the Common Problems section

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

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: