From 936176f381e7de36b524ee8c9a0b4abae9792047 Mon Sep 17 00:00:00 2001 From: David Spickett Date: Fri, 13 Sep 2024 10:01:52 +0100 Subject: [PATCH 1/3] [llvm][Docs] Improve the formatting of the Common Problems section I realised this existed after answering https://discourse.llvm.org/t/clang-development-environment/81140. * Mark options, option values and program names as plain text. * Add a blank line between the option and the explanatory text so that it doesn't get printed on the same line. (this seems to be the original intent of the rst source anyway) * Update the phrasing of a couple of the options. --- llvm/docs/GettingStarted.rst | 67 +++++++++++++++++++++--------------- 1 file changed, 40 insertions(+), 27 deletions(-) diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst index e03ae5effcdc4..0984acea47840 100644 --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -1085,67 +1085,80 @@ 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 + * ``-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 + * ``-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 AMD64 machine. + You will find a full list of targets within the + `llvm-project/llvm/lib/Target `_ + directory. - * -DLLVM_OPTIMIZED_TABLEGEN - Set this to ON to generate a fully optimized tablegen during your build. This + * ``-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. + using the ``Debug`` build type. + + * ``-DLLVM_ENABLE_PROJECTS`` - * -DLLVM_ENABLE_PROJECTS - Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If + 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. .. _links: From a0a793c021d8a9112031e9adb2957854ed03a205 Mon Sep 17 00:00:00 2001 From: David Spickett Date: Fri, 13 Sep 2024 10:27:48 +0100 Subject: [PATCH 2/3] Add shared libs suggestion --- llvm/docs/CMake.rst | 2 ++ llvm/docs/GettingStarted.rst | 8 ++++++++ 2 files changed, 10 insertions(+) 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 0984acea47840..f4ecf949cbd2a 100644 --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -1160,6 +1160,14 @@ following options with cmake: 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: Links From cd52a6945bfdc6234a3c69895654c6baaffa478b Mon Sep 17 00:00:00 2001 From: David Spickett Date: Mon, 7 Oct 2024 11:37:34 +0100 Subject: [PATCH 3/3] update wording --- llvm/docs/GettingStarted.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst index f4ecf949cbd2a..8ef1f85d6b6fd 100644 --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -1097,7 +1097,7 @@ following options with cmake: * ``-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 + 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. @@ -1124,16 +1124,17 @@ following options with cmake: * ``-DLLVM_TARGETS_TO_BUILD`` Set this equal to the target you wish to build. You may wish to set this to - only your host architecture. For example `X86` if you are using an AMD64 machine. - You will find a full list of targets within the + 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`` - 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``