[PATCH] D124367: [docs] Improve documentation around CMAKE_BUILD_TYPE

[Aaron Puchert via Phabricator via llvm-commits]

aaronpuchert added a comment.

The build types control three different aspects, so maybe you could even present this as a table <https://docutils.sourceforge.io/docs/ref/rst/directives.html#tables>:

| **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.



================
Comment at: llvm/docs/CMake.rst:202-203
+    This enables the highest level of optimizations and disables
+    all debug information and assertions. This is the build type that most
+    users of LLVM and Clang want to use.
+
----------------
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."


================
Comment at: llvm/docs/CMake.rst:206-207
+  **Debug**
+    This build type enables debug information and disables most
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
----------------
Let's keep it short and say "disables optimizations". That's pretty much true for `-O0`.


================
Comment at: llvm/docs/CMake.rst:207
+    This build type enables debug information and disables most
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
----------------
aaronpuchert wrote:
> I don't think they are necessarily slower. Optimizations can also take some time, and perhaps under certain circumstances this is no longer true.



================
Comment at: llvm/docs/CMake.rst:207-208
+    This build type enables debug information and disables most
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
+    Linux/ELF It's not uncommon that your linker might run into issues
----------------
I don't think they are necessarily slower. Optimizations can also take some time, and perhaps under certain circumstances this is no longer true.


================
Comment at: llvm/docs/CMake.rst:208
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
+    Linux/ELF It's not uncommon that your linker might run into issues
----------------
aaronpuchert wrote:
> jhenderson wrote:
> > tschuett wrote:
> > > 
> > I suspect RAM is the limiting factor for most users rather than disk space. I'd suggest mentioning that here too.
> 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.
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.


================
Comment at: llvm/docs/CMake.rst:208
+    optimizations. Builds using ``Debug`` will be siginficantly slower and
+    use a lot more diskspace then a ``Release`` build. When targetting
+    Linux/ELF It's not uncommon that your linker might run into issues
----------------
aaronpuchert wrote:
> aaronpuchert wrote:
> > jhenderson wrote:
> > > tschuett wrote:
> > > > 
> > > I suspect RAM is the limiting factor for most users rather than disk space. I'd suggest mentioning that here too.
> > 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.
> 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.
Perhaps we can add that these are most suitable for step-by-step debugging.


================
Comment at: llvm/docs/CMake.rst:208-211
+    use a lot more diskspace then a ``Release`` build. When targetting
+    Linux/ELF It's not uncommon that your linker might run into issues
+    when linking ``Debug`` builds. It's recommended that ``Debug`` build
+    are linked with ``lld``, see the ``LLVM_ENABLE_LLD`` option.
----------------
jhenderson wrote:
> tschuett wrote:
> > 
> I suspect RAM is the limiting factor for most users rather than disk space. I'd suggest mentioning that here too.
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.


================
Comment at: llvm/docs/CMake.rst:217
+  **RelWithDebInfo**
+    This build type tries to give a balance between ``Release`` and
+    ``Debug`` builds. It enables most optimizations and also debug
----------------
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.


================
Comment at: llvm/docs/CMake.rst:218-221
+    ``Debug`` builds. It enables most optimizations and also debug
+    information for debugging. This build is usually used when you want
+    to deploy something to production but you still need to debug it
+    in order to find a bug or problem. Size of binaries will be big and
----------------
Here I would suggest something like "Binaries will be fast as in Release, but it allows limited interactive debugging".


================
Comment at: llvm/docs/CMake.rst:219-221
+    information for debugging. This build is usually used when you want
+    to deploy something to production but you still need to debug it
+    in order to find a bug or problem. Size of binaries will be big and
----------------
True, but since we want people new to the code to read that, I'd suggest to omit that in the sense of brevity.


================
Comment at: llvm/docs/CMake.rst:227-228
+    This build type will configure the build to be optimized for size
+    instead of speed. This should be used if you are tight on space and
+    speed of execution is not your primary concern. No debug information
+    is included by default in this configuration and assertions are turned
----------------
Also here: I'd suggest to omit that in the interest of keeping it short. This build type is rarely used anyway.


================
Comment at: llvm/docs/GettingStarted.rst:75-79
+     * ``-DCMAKE_BUILD_TYPE=type`` --- Controls optimization level and debug information
+       of the build. Possible values are ``Release``, ``Debug``, ``MinSizeRel`` and
+       ``RelWithDebInfo``. The default value is ``Debug`` that fits people that want
+       to work on LLVM or with it's 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>`.
----------------
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`.


================
Comment at: llvm/docs/GettingStarted.rst:101
 
-   * For more information see `CMake <CMake.html>`__
+   * For more information see `CMake <CMake.html#>`__
 
----------------
Why is that `#` needed now?


================
Comment at: llvm/docs/GettingStarted.rst:1194-1196
+      linking with debug info may consume a large amount of memory. This configuration
+      also consumes a lot more disk space, so if you have problems with how big
+      a build is, you should consider the ``Release`` type instead.
----------------
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.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D124367/new/

https://reviews.llvm.org/D124367