[docs] More CMAKE variable documentation

[urnathan]

Summary

This follows from my D102481 collation of cmake variables by breaking out some (more) common llvm-specific variables. Controlling the subprojects and target architectures, along with clues about restricting build parallelism when linking. 'more common' is somewhat subjective, I take what I use defines that? :)

ok?

[aaron.ballman]

llvm/docs/CMake.rst

187

224

I'd move this up above the rarely-used section so that the list goes in order of most-used to least-used. WDYT?

225

Underlines are off here, so sphinx will complain about this.

228

One thing that's interesting about this is that I don't know that they're LLVM variables or not. LLVM_ENABLE_PROJECTS isn't really LLVM-specific, it decides what to build as part of the whole project. Similar logic applies to a lot of these items. The only one that's really LLVM-specific in this list is LLVM_TARGETS_TO_BUILD, but even that one impacts Clang.

261

[urnathan]

llvm/docs/CMake.rst

224

I wasn;t sure myself, your comment is enough to do the ordering you suggest.

225

I don't know what that means -- I tried to figure out how to sphinx it, but failed. I (attempted to) match the formatting of other section headers.

228

Agreed, there's an unfortunate use of LLVM to mean both 'LLVM library' and 'LLVM project'. I don't know the best way to disambiguate that -- or how to categorize these variables.

261

muscle memory for the lose!

[urnathan]

thanks for the comments. I've addressed what I can, but I don't understand the sphinx thing.

[aaron.ballman]

llvm/docs/CMake.rst

212–213

225

The count of underlines needs to match the count of characters on the line. I made a suggested edit to show what I mean.

228

How about using LLVM-related instead of LLVM-specific in the section title and prose? Alternatively, we could just stick them under frequently used and not call out LLVM at all?

[xgupta]

I think newcomers first visit getting started to know the common practice or frequently used variable. It will be duplication to write a similar heading in CMake.rst

llvm/docs/CMake.rst

210

I think similar documentation is available on getting started page - https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm, https://llvm.org/docs/GettingStarted.html#local-llvm-configuration and https://llvm.org/docs/GettingStarted.html#common-problems.

And again the same variables are listed on the same cmake.rst page below so again a duplication.

[urnathan]

llvm/docs/CMake.rst

225

ah, I see, thanks.

[aaron.ballman]

I think you may have uploaded the wrong patch, @urnathan. ;-)

[urnathan]

Let's try that again

[aaron.ballman]

LGTM, thank you for the improvements!

llvm/docs/CMake.rst

195–199

You can re-flow these lines to 80 col.

210

Good catch on the repeated documentation in places. As a follow-up, it might be nice to have all of those places point to this documentation so we have everything funneled into one place. But I don't think that needs to happen as part of this patch.

[xgupta]

llvm/docs/CMake.rst

210

Sounds good to me

llvm/docs/CMake.rst

#. Execute this command in the shell replacing `path/to/llvm/source/root` with
    a list of build parameters that you can modify.
 
    This can fail if CMake can't detect your toolset, or if it thinks that the
    environment is not sane enough. In this case, make sure that the toolset that
    you intend to use is the only one reachable from the shell, and that the shell
    itself is the correct one for your development environment. CMake will refuse
    to build MinGW makefiles if you have a POSIX shell reachable through the PATH
    environment variable, for instance. You can force CMake to use a given build
-   tool; for instructions, see the `Usage`_ section, below.
+   tool; for instructions, see the `Usage`_ section, below.  You may
+   also wish to control which targets LLVM enables, or which LLVM
+   components are built; see the `Frequently Used LLVM-specific
+   variables`_ below.
 
 #. After CMake has finished running, proceed to use IDE project files, or start
    the build from the build directory:
 
    .. code-block:: console
 
      $ cmake --build .
 

 .. code-block:: console
 
   $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
 
 Frequently-used CMake variables
 -------------------------------
 
 Here are some of the CMake variables that are used often, along with a
-brief explanation and LLVM-specific notes. For full documentation, consult the
-CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
+brief explanation. For full documentation, consult the CMake manual,
+or execute ``cmake --help-variable VARIABLE_NAME``.  See `Frequently
+Used LLVM-specific variables`_ below for information about commonly
+used LLVM-specific variables.
 
 **CMAKE_BUILD_TYPE**:STRING
   Sets the build type for ``make``-based generators. Possible values are
   Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
   Visual Studio, you should use the IDE settings to set the build type.
   Be aware that Release and RelWithDebInfo use different optimization levels on
-  most platforms.
+  most platforms. Be aware that Release and
+  RelWithDebInfo use different optimization levels on most
+  platforms, and that the default value of ``LLVM_ENABLE_ASSERTIONS``
+  is affected.
 
 **CMAKE_INSTALL_PREFIX**:PATH
-  Path where LLVM will be installed if "make install" is invoked or the
-  "install" target is built.
+  Path where LLVM will be installed when the "install" target is built.
 
-**CMAKE_C_FLAGS**:STRING
-  Extra flags to use when compiling C source files.
+**CMAKE_{C,CXX}_FLAGS**:STRING
+  Extra flags to use when compiling C and C++ source files respectively.
 
-**CMAKE_CXX_FLAGS**:STRING
-  Extra flags to use when compiling C++ source files.
-
-**LLVM_LIBDIR_SUFFIX**:STRING
-  Extra suffix to append to the directory where libraries are to be
-  installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
-  to install libraries to ``/usr/lib64``.
+**CMAKE_{C,CXX}_COMPILER**:STRING
+  Specify the C and C++ compilers to use. If you have multiple
+  compilers installed, CMake might not default to the one you wish to
+  use.
 
 Rarely-used CMake variables
 ---------------------------
 
 Here are some of the CMake variables that are rarely used, along with a brief
 explanation and LLVM-specific notes.  For full documentation, consult the CMake
 manual, or execute ``cmake --help-variable VARIABLE_NAME``.
 
 **CMAKE_CXX_STANDARD**:STRING
   Sets the C++ standard to conform to when building LLVM.  Possible values are
   14, 17, 20.  LLVM Requires C++ 14 or higher.  This defaults to 14.
 
+.. _Frequently Used LLVM-specific variables:
+
+Frequently Used LLVM-specific variables
+-----------------------
+
+The default configuration may not match your requirements. Here are
+LLVM variables that are frequently used to control that. The full
+description is in `LLVM-specific variables`_ below.
+
+**LLVM_ENABLE_PROJECTS**:STRING
+  Control which projects are enabled. For example you may want to work on clang
+  or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.
+
+**LLVM_LIBDIR_SUFFIX**:STRING
+  Extra suffix to append to the directory where libraries are to be
+  installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
+  to install libraries to ``/usr/lib64``.
+
+**LLVM_PARALLEL_{COMPILE,LINK}_JOBS**:STRING
+  Building the llvm toolchain can use a lot of resources, particularly
+  linking. These options, when you use the Ninja generator, allow you
+  to restrict the parallelism. For example, to avoid OOMs or going
+  into swap, permit only one link job per 15GB of RAM available on a
+  32GB machine, specify ``-G Ninja -DLLVM_PARALLEL_LINK_JOBS=2``.
+
+**LLVM_TARGETS_TO_BUILD**:STRING
+  Control which targets are enabled. For example you may only need to enable
+  your native target with, for example, ``-DLLVM_TARGETS_TO_BUILD=X86``.
+
+**LLVM_USE_LINKER**:STRING
+  Override the system's default linker. For instance use ``lld`` with
+  ``-DLLVM_USE_LINKER=lld``.
+
 .. _LLVM-specific variables:
 
 LLVM-specific variables
 -----------------------
 
+These variables provide fine control over the build of LLVM and
+enabled sub-projects.  Nearly all of these variable namess begin with
+``LLVM_``.
+
 **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
   Windows, shared libraries may be used when building with MinGW, including
   mingw-w64, but not when building with the Microsoft toolchain.
 
   .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
             If you want to build LLVM as a shared library, you should use the