diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst index 838447f483e51..7dffa57ab724e 100644 --- a/llvm/docs/CMake.rst +++ b/llvm/docs/CMake.rst @@ -309,6 +309,8 @@ These variables provide fine control over the build of LLVM and enabled sub-projects. Nearly all of these variable names begin with ``LLVM_``. +.. _LLVM-related variables BUILD_SHARED_LIBS: + **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 diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst index e03ae5effcdc4..8ef1f85d6b6fd 100644 --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -1085,67 +1085,89 @@ general questions about LLVM, please consult the `Frequently Asked Questions `_ page. If you are having problems with limited memory and build time, please try -building with ninja instead of make. Please consider configuring the +building with ``ninja`` instead of ``make``. Please consider configuring the following options with cmake: - * -G Ninja + * ``-G Ninja`` + Setting this option will allow you to build with ninja instead of make. Building with ninja significantly improves your build time, especially with 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 + * ``-DLLVM_USE_LINKER`` + + Setting this option to ``lld`` will significantly reduce linking time for LLVM + executables, particularly on Linux and Windows. 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 + * ``-DCMAKE_BUILD_TYPE`` + Controls optimization level and debug information of the build. This setting can affect RAM and disk usage, see :ref:`CMAKE_BUILD_TYPE ` for more information. - * -DLLVM_ENABLE_ASSERTIONS - This option defaults to ON for Debug builds and defaults to OFF for Release + * ``-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 + * ``-DLLVM_PARALLEL_LINK_JOBS`` + Set this equal to number of jobs you wish to run simultaneously. This is - similar to the -j option used with make, but only for link jobs. This option + similar to the ``-j`` option used with ``make``, but only for link jobs. This option can only be used with ninja. You may wish to use a very low number of jobs, as this will greatly reduce the amount of memory used during the build - process. If you have limited memory, you may wish to set this to 1. + process. If you have limited memory, you may wish to set this to ``1``. + + * ``-DLLVM_TARGETS_TO_BUILD`` - * -DLLVM_TARGETS_TO_BUILD Set this equal to the target you wish to build. You may wish to set this to - X86; however, you will find a full list of targets within the - llvm-project/llvm/lib/Target directory. + only your host architecture. For example ``X86`` if you are using an Intel or + AMD machine. You will find a full list of targets within the + `llvm-project/llvm/lib/Target `_ + directory. + + * ``-DLLVM_OPTIMIZED_TABLEGEN`` - * -DLLVM_OPTIMIZED_TABLEGEN - Set this to ON to generate a fully optimized tablegen during your build. This - will significantly improve your build time. This is only useful if you are - using the Debug build type. + Set this to ``ON`` to generate a fully optimized TableGen compiler during your + build, even if that build is a ``Debug`` build. This will significantly improve + your build time. You should not enable this if your intention is to debug the + TableGen compiler. - * -DLLVM_ENABLE_PROJECTS - Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If + * ``-DLLVM_ENABLE_PROJECTS`` + + Set this equal to the projects you wish to compile (e.g. ``clang``, ``lld``, etc.) If compiling more than one project, separate the items with a semicolon. Should you run into issues with the semicolon, try surrounding it with single quotes. - * -DLLVM_ENABLE_RUNTIMES - Set this equal to the runtimes you wish to compile (e.g. libcxx, libcxxabi, etc.) + * ``-DLLVM_ENABLE_RUNTIMES`` + + Set this equal to the runtimes you wish to compile (e.g. ``libcxx``, ``libcxxabi``, etc.) If compiling more than one runtime, separate the items with a semicolon. Should you run into issues with the semicolon, try surrounding it with single quotes. - * -DCLANG_ENABLE_STATIC_ANALYZER - Set this option to OFF if you do not require the clang static analyzer. This + * ``-DCLANG_ENABLE_STATIC_ANALYZER`` + + Set this option to ``OFF`` if you do not require the clang static analyzer. This should improve your build time slightly. - * -DLLVM_USE_SPLIT_DWARF - Consider setting this to ON if you require a debug build, as this will ease + * ``-DLLVM_USE_SPLIT_DWARF`` + + Consider setting this to ``ON`` if you require a debug build, as this will ease memory pressure on the linker. This will make linking much faster, as the - binaries will not contain any of the debug information; however, this will - generate the debug information in the form of a DWARF object file (with the - extension .dwo). This only applies to host platforms using ELF, such as Linux. + binaries will not contain any of the debug information. Instead the debug + information is in a separate DWARF object file (with the extension ``.dwo``). + This only applies to host platforms using ELF, such as Linux. + + * ``-DBUILD_SHARED_LIBS`` + + Setting this to ``ON`` will build shared libraries instead of static + libraries. This will ease memory pressure on the linker. However, this should + only be used when developing llvm. See + :ref:`BUILD_SHARED_LIBS ` + for more information. .. _links: