[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

257

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

258

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

261

261

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.

[urnathan]

llvm/docs/CMake.rst

257

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

258

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.

261

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

213–214

258

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

261

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

211

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

258

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.

211

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

211

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-related
+   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-related Variables`_ below for information about commonly
+used variables that control features of LLVM and enabled subprojects.
 
 **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.
+**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.
+
+.. _Frequently Used LLVM-related variables:
+
+Frequently Used LLVM-related 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-related 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``.
+
 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
+explanation and LLVM-related 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.
 
-.. _LLVM-specific variables:
+.. _LLVM-related variables:
 
-LLVM-specific variables
+LLVM-related variables
 -----------------------
 
+These variables provide fine control over the build of LLVM and
+enabled sub-projects. Nearly all of these variable names 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

 
 See `this wiki page <https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling>`_ for
 generic instructions on how to cross-compile with CMake. It goes into detailed
 explanations and may seem daunting, but it is not. On the wiki page there are
 several examples including toolchain files. Go directly to the
 ``Information how to set up various cross compiling toolchains`` section
 for a quick solution.
 
-Also see the `LLVM-specific variables`_ section for variables used when
+Also see the `LLVM-related variables`_ section for variables used when
 cross-compiling.
 
 Embedding LLVM in your project
 ==============================
 
 From LLVM 3.5 onwards the CMake build system exports LLVM libraries as
 importable CMake targets. This means that clients of LLVM can now reliably use
 CMake to develop their own LLVM-based projects against an installed version of