[llvm] [llvm][Docs] Improve the formatting of the Common Problems section (PR #108522)
David Spickett via llvm-commits
llvm-commits at lists.llvm.org
Fri Sep 13 02:30:13 PDT 2024
https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/108522
...and add shared libs as a suggestion.
* 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.
* Add BUILD_SHARED_LIBS to suggestions.
>From 4bdc8bce13acfe895fe80a5d20b53d4974a96dff Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 13 Sep 2024 10:01:52 +0100
Subject: [PATCH 1/2] [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 e03ae5effcdc44..0984acea478403 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 <FAQ.html>`_ 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 <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 <https://github.com/llvm/llvm-project/tree/main/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 18e4604fc867c07284ad3774af3a085858951af1 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 13 Sep 2024 10:27:48 +0100
Subject: [PATCH 2/2] 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 838447f483e510..7dffa57ab724e1 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 0984acea478403..f4ecf949cbd2a9 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 <LLVM-related variables BUILD_SHARED_LIBS>`
+ for more information.
+
.. _links:
Links
More information about the llvm-commits
mailing list