[docs] Improve documentation around CMAKE_BUILD_TYPE

[thieta]

Summary

See discussion in: https://reviews.llvm.org/D124153

[tschuett]

Thanks for driving this.

[tschuett]

llvm/docs/CMake.rst

208

209

[jhenderson]

llvm/docs/CMake.rst

208

I suspect RAM is the limiting factor for most users rather than disk space. I'd suggest mentioning that here too.

209–210

Let's be a bit more explicit by stating the sort of issues (i.e. OOM issues) when doing this build.

222

223

Here and possibly in a few other places, you've referred to builds in the plural, whereas usually you refer to it in the singular. I don't mind which, but you should be consistent at least.

llvm/docs/GettingStarted.rst

77–78

Do you mean "with it's libraries" i.e. someone who is developing a project using LLVM libraries? If not, it should be "or it's libraries".

1191

[aaronpuchert]

The build types control three different aspects, so maybe you could even present this as a table:

Build type	Optimizations	Debug Info	Assertions
Release	For speed	✗	✗
Debug	None	✓	✓
RelWithDebInfo	For speed/size	✓	✗
MinSizeRel	For size	✗	✗

Then briefly explain the aspects:

• Optimizations make code run faster but can be an impediment to step-by-step debugging.
• Builds with debug info can consume lots of memory and disk space, here is how that might be mitigated: ...
• Assertions are internal constraint checks that can help find bugs.

Then you don't have to repeat wording about those aspects.

llvm/docs/CMake.rst

202–203

Perhaps we can phrase this in a way that doesn't suggest we know what others want, like "It is best suited for users of LLVM and Clang."

206–207

Let's keep it short and say "disables optimizations". That's pretty much true for -O0.

207

207–208

I don't think they are necessarily slower. Optimizations can also take some time, and perhaps under certain circumstances this is no longer true.

208

The build might not run out of disk space, but it can be very IO-heavy (without split debug info).

But memory is the main issue of course.

208

Perhaps we can add that these are most suitable for step-by-step debugging.

208–211

I wouldn't suggest a specific linker here, but simply list some options to mitigate the downsides: LLVM_USE_LINKER (LLVM_ENABLE_LLD is mostly interesting for two-stage builds, and gold is also an option), LLVM_USE_SPLIT_DWARF, LLVM_PARALLEL_LINK_JOBS, and BUILD_SHARED_LIBS. There is no need to explain them, they are explained below.

217

It's more of a combination than a balance, as the name implies: the optimizations are practically the same as in Release (the difference between -O2 and -O3 is marginal in Clang), and we have full debug info as in Debug.

218–221

Here I would suggest something like "Binaries will be fast as in Release, but it allows limited interactive debugging".

219–221

True, but since we want people new to the code to read that, I'd suggest to omit that in the sense of brevity.

227–228

Also here: I'd suggest to omit that in the interest of keeping it short. This build type is rarely used anyway.

llvm/docs/GettingStarted.rst

75–80

Doesn't this duplicate the section below? There is certain danger in having different parts of the documentation talking about the same stuff. I'd prefer if you just pointed there as in "For details see below", or kept the reference to CMAKE_BUILD_TYPE.

101

Why is that # needed now?

1190–1191

The most important aspect is already there, so maybe just a brief addition. Also we don't need to recommend an alternative, since it's right after this. Detailed information can be found in the CMake page.

[thieta]

Thanks for the suggestions all - I am working on this and came up with this table, WDYT. I will upload this as a diff when I have addressed all the rest of the comments, but wanted to get the input on the table first since it's a bit annoying to mark-up correctly.

[tschuett]

Thanks! I have the feeling that Release wins at execution speed and is the fastest to build?

[aaronpuchert]

This looks pretty good!

[jhenderson]

Table looks good to me, although the second bullet has some grammar errors in it. Is it worth referencing the cmake option to enable assertions in the bullet about assertions?

[thieta]

Review updates, make it a more readable table and point more people to
this table

[thieta]

Here is my latest attempt:

Did a table, then pointed all references to CMAKE_BUILD_TYPE to this table so that we keep all documentation about it in the same place.

Please take another pass on it - and feel free to point out my grammar errors (English is not my first language).

[jhenderson]

llvm/docs/CMake.rst

212

llvm/docs/GettingStarted.rst

77–78

Not addressed? Also it's -> its.

[thieta]

llvm/docs/GettingStarted.rst

77–78

I did change it to or it's libraries, will fix the other issue.

[thieta]

Smaller grammar fixes

[jhenderson]

llvm/docs/GettingStarted.rst

77–78

You didn't address the main bit which was the inline edit (use "which" and "who" instead of "that").

[thieta]

llvm/docs/GettingStarted.rst

77–78

Ah shit - thanks for pointing that out. I was focused on the it's bit. I find the inline edits hard to see when you are color blind at times. Will fix in the next update.

[thieta]

Finally fix this line

[jhenderson]

llvm/docs/CMake.rst

209

211–212

"can use a lot of RAM and disk space and are usually"

215–216

Nit: possibly wrapped a bit prematurely?

llvm/docs/GettingStarted.rst

1191–1192

This paragraph seems to be a match for the earlier one under "common cmake options". If you feel it should be duplicated, please update it to fix the same grammar issues.

(i.e. "that" -> "which")

[thieta]

Latest batch up of updates

[thieta]

Thanks for all your detailed feedback @jhenderson

[jhenderson]

LGTM, but worth waiting for others to take a look.

[thieta]

Thanks everyone for the input! If you have any more input on this - please try to get to it today since I plan to merge this and the CMake change to show this documentation tomorrow CEST.

[awarzynski]

llvm/docs/GettingStarted.rst

51

I think that the moment you land https://reviews.llvm.org/D124153, this line will be invalid.

[thieta]

I will land this documentation update now since it's pretty low risk, and I want to land before the other diff making CMAKE_BUILD_TYPE mandatory. I'll be happy to make more changes if people feel it's needed. Hit me up with other changes in that case.

llvm/docs/CMake.rst

 -------------------------------
 
 Here are some of the CMake variables that are used often, along with a
 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:
+
 **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. Be aware that Release and
-  RelWithDebInfo use different optimization levels on most
-  platforms, and that the default value of ``LLVM_ENABLE_ASSERTIONS``
-  is affected.
+  This configures the optimization level for ``make`` or ``ninja`` builds.
+  The default ``CMAKE_BUILD_TYPE`` is set to ``Debug`` but you should
+  carefully read the list below to figure out what configuration matches
+  your use case the best.
+
+  Possible values:
+
+  =========================== ============= ========== ========== ==========================
+  Build Type                  Optimizations Debug Info Assertions Best suited for
+  =========================== ============= ========== ========== ==========================
+  **Release**                 For Speed     No         No         Users of LLVM and Clang
+  **Debug**                   None          Yes        Yes        Developers of LLVM
+  **RelWithDebInfo**          For Speed     Yes        No         Users that also need Debug
+  **MinSizeRel**              For Size      No         No         When disk space matters
+  =========================== ============= ========== ========== ==========================
+
+  * Optimizations makes LLVM/Clang run faster, but can be an
+    impediment for step-by-step debugging.
+  * Builds with debug information can use a lot of RAM and lot of
+    disk space and is usually slower to run. You can improve
+    RAM usage by using ``lld``, see the :ref:`LLVM_USE_LINKER <llvm_use_linker>`
+    option.
+  * Assertions are internal checks to help you find bugs. They
+    typically slow down LLVM and Clang when enabled, but can be useful
+    during development. You can manually set :ref:`LLVM_ENABLE_ASSERTIONS <llvm_enable_assertions>`
+    to override the default from `CMAKE_BUILD_TYPE`.
+
+  If you are using an IDE such as Visual Studio or Xcode, you should use
+  the IDE settings to set the build type.
 
 **CMAKE_INSTALL_PREFIX**:PATH
   Path where LLVM will be installed when the "install" target is built.
 
 **CMAKE_{C,CXX}_FLAGS**:STRING
   Extra flags to use when compiling C and C++ source files respectively.
 
 **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
**LLVM_PARALLEL_{COMPILE,LINK}_JOBS**:STRING
   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:
+
 **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
**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
   for more information. Defaults to "org.llvm". This option is only useful in
   combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
   it has no effect.
 
 **LLVM_DOXYGEN_SVG**:BOOL
   Uses .svg files instead of .png files for graphs in the Doxygen output.
   Defaults to OFF.
 
+.. _llvm_enable_assertions:
+
 **LLVM_ENABLE_ASSERTIONS**:BOOL
   Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
   is *Debug*.
 
 **LLVM_ENABLE_BINDINGS**:BOOL
   If disabled, do not try to build the OCaml and go bindings.
 
 **LLVM_ENABLE_DIA_SDK**:BOOL

llvm/docs/GettingStarted.rst

* To save storage and speed-up the checkout time, you may want to do a
      For example, to get the latest revision of the LLVM project, use
      ``git clone --depth 1 https://github.com/llvm/llvm-project.git``
 
 #. Configure and build LLVM and Clang:
 
    * ``cd llvm-project``
    * ``mkdir build``
    * ``cd build``
    * ``cmake -G <generator> [options] ../llvm``
 
      Some common build system generators are:
 
      * ``Ninja`` --- for generating `Ninja <https://ninja-build.org>`_
        build files. Most llvm developers use Ninja.
      * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
      * ``Visual Studio`` --- for generating Visual Studio projects and
        solutions.
      * ``Xcode`` --- for generating Xcode projects.
 
      Some Common options:
 
      * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
        subprojects you'd like to additionally build. Can include any of: clang,
        clang-tools-extra, lldb, compiler-rt, lld, polly, or cross-project-tests.
 
        For example, to build LLVM, Clang, libcxx, and libcxxabi, use
        ``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
 
      * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
        pathname of where you want the LLVM tools and libraries to be installed
        (default ``/usr/local``).
 
-     * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
-       Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
+     * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug information
+       of the build. The default value is ``Debug`` which fits people who want
+       to work on LLVM or its libraries. ``Release`` is a better fit for most
+       users of LLVM and Clang. For more detailed information see
+       :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
 
      * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
        (default is Yes for Debug builds, No for all other build types).
 
    * ``cmake --build . [--target <target>]`` or the build system specified
      above directly.
 
      * The default target (i.e. ``cmake --build .`` or ``make``) will build all of
        LLVM.
 
      * The ``check-all`` target (i.e. ``ninja check-all``) will run the
        regression tests to ensure everything is in working order.
 
      * CMake will generate build targets for each tool and library, and most
        LLVM sub-projects generate their own ``check-<project>`` target.
 
      * Running a serial build will be **slow**.  To improve speed, try running a
        parallel build. That's done by default in Ninja; for ``make``, use the
        option ``-j NN``, where ``NN`` is the number of parallel jobs, e.g. the
        number of available CPUs.
 
    * For more information see `CMake <CMake.html>`__
 
    * If you get an "internal compiler error (ICE)" or test failures, see
      `below`_.
 
 Consult the `Getting Started with LLVM`_ section for detailed information on
 configuring and compiling LLVM.  Go to `Directory Layout`_ to learn about the
 layout of the source code tree.
 
* -G Ninja
    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
    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
-
-    - Debug --- This is the default build type. This disables optimizations while
-      compiling LLVM and enables debug info. On ELF-based platforms (e.g. Linux)
-      linking with debug info may consume a large amount of memory.
-
-    - Release --- Turns on optimizations and disables debug info. Combining the
-      Release build type with -DLLVM_ENABLE_ASSERTIONS=ON may be a good trade-off
-      between speed and debugability during development, particularly for running
-      the test suite.
+   The default ``CMAKE_BUILD_TYPE`` is ``Debug`` that is well suited to people
+   that develop LLVM, but will use more disk space and more RAM when linking.
+   If you only plan to use LLVM or Clang it's better to set this to ``Release``.
+   For more information see :ref:`CMAKE_BUILD_TYPE <cmake_build_type>`.
 
  * -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
    Set this equal to number of jobs you wish to run simultaneously. This is