[docs] Improve documentation around CMAKE_BUILD_TYPE

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

Reviewed By: jhenderson

Differential Revision: https://reviews.llvm.org/D124367
This commit is contained in:
Tobias Hieta 2022-04-25 10:28:59 +02:00
parent 71672375fe
commit 30e8796496
2 changed files with 42 additions and 19 deletions

View File

@ -187,15 +187,37 @@ 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 make 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 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.
@ -241,6 +263,8 @@ description is in `LLVM-related variables`_ below.
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``.
@ -435,6 +459,8 @@ enabled sub-projects. Nearly all of these variable names begin with
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*.

View File

@ -72,8 +72,11 @@ This is an example workflow and configuration to get and build the LLVM source:
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).
@ -1185,15 +1188,9 @@ following options with cmake:
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.
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