[llvm] 30e8796 - [docs] Improve documentation around CMAKE_BUILD_TYPE
Tobias Hieta via llvm-commits
llvm-commits at lists.llvm.org
Wed May 4 02:23:53 PDT 2022
Author: Tobias Hieta
Date: 2022-05-04T11:23:45+02:00
New Revision: 30e8796496032b9d41b3f4810aef076d1526fa0e
URL: https://github.com/llvm/llvm-project/commit/30e8796496032b9d41b3f4810aef076d1526fa0e
DIFF: https://github.com/llvm/llvm-project/commit/30e8796496032b9d41b3f4810aef076d1526fa0e.diff
LOG: [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
Added:
Modified:
llvm/docs/CMake.rst
llvm/docs/GettingStarted.rst
Removed:
################################################################################
diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index 8fc40e7ba3bd2..10945618e2f94 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -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
diff erent optimization levels on
- most platforms. Be aware that Release and
- RelWithDebInfo use
diff erent 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*.
diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index a2e7f87745000..2559432ed22a1 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -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
More information about the llvm-commits
mailing list