[libunwind] 4ae83bb - Update all LLVM documentation mentioning runtimes in LLVM_ENABLE_PROJECTS
Louis Dionne via cfe-commits
cfe-commits at lists.llvm.org
Thu Feb 10 12:05:39 PST 2022
Author: Louis Dionne
Date: 2022-02-10T15:05:23-05:00
New Revision: 4ae83bb2b1e27628f6bd14d746aef964ed776d52
URL: https://github.com/llvm/llvm-project/commit/4ae83bb2b1e27628f6bd14d746aef964ed776d52
DIFF: https://github.com/llvm/llvm-project/commit/4ae83bb2b1e27628f6bd14d746aef964ed776d52.diff
LOG: Update all LLVM documentation mentioning runtimes in LLVM_ENABLE_PROJECTS
We are moving away from building the runtimes with LLVM_ENABLE_PROJECTS,
however the documentation was largely outdated. This commit updates all
the documentation I could find to use LLVM_ENABLE_RUNTIMES instead of
LLVM_ENABLE_PROJECTS for building runtimes.
Note that in the near future, libcxx, libcxxabi and libunwind will stop
supporting being built with LLVM_ENABLE_PROJECTS altogether. I don't know
what the plans are for other runtimes like libc, openmp and compiler-rt,
so I didn't make any changes to the documentation that would imply
something for those projects.
Once this lands, I will also cherry-pick this on the release/14.x branch
to make sure that LLVM's documentation is up-to-date and reflects what
we intend to support in the future.
Differential Revision: https://reviews.llvm.org/D119351
Added:
Modified:
README.md
bolt/docs/OptimizingClang.md
clang/docs/DataFlowSanitizer.rst
clang/docs/Toolchain.rst
compiler-rt/www/index.html
flang/README.md
libcxx/docs/BuildingLibcxx.rst
libunwind/docs/BuildingLibunwind.rst
llvm/docs/BuildingADistribution.rst
llvm/docs/CMake.rst
llvm/docs/GettingStarted.rst
Removed:
################################################################################
diff --git a/README.md b/README.md
index 27cc755c93d00..15da302765081 100644
--- a/README.md
+++ b/README.md
@@ -63,17 +63,25 @@ This is an example work-flow and configuration to get and build the LLVM source:
Some common options:
- * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
- sub-projects you'd like to additionally build. Can include any of: clang,
- clang-tools-extra, compiler-rt,cross-project-tests, flang, libc, libclc,
- libcxx, libcxxabi, libunwind, lld, lldb, mlir, openmp, polly, or pstl.
+ * ``-DLLVM_ENABLE_PROJECTS='...'`` and ``-DLLVM_ENABLE_RUNTIMES='...'`` ---
+ semicolon-separated list of the LLVM sub-projects and runtimes you'd like to
+ additionally build. ``LLVM_ENABLE_PROJECTS`` can include any of: clang,
+ clang-tools-extra, cross-project-tests, flang, libc, libclc, lld, lldb,
+ mlir, openmp, polly, or pstl. ``LLVM_ENABLE_RUNTIMES`` can include any of
+ libcxx, libcxxabi, libunwind, compiler-rt, libc or openmp. Some runtime
+ projects can be specified either in ``LLVM_ENABLE_PROJECTS`` or in
+ ``LLVM_ENABLE_RUNTIMES``.
For example, to build LLVM, Clang, libcxx, and libcxxabi, use
- ``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
+ ``-DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
* ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
path name of where you want the LLVM tools and libraries to be installed
- (default ``/usr/local``).
+ (default ``/usr/local``). Be careful if you install runtime libraries: if
+ your system uses those provided by LLVM (like libc++ or libc++abi), you
+ must not overwrite your system's copy of those libraries, since that
+ could render your system unusable. In general, using something like
+ ``/usr`` is not advised, but ``/usr/local`` is fine.
* ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
diff --git a/bolt/docs/OptimizingClang.md b/bolt/docs/OptimizingClang.md
index 5d727d9417819..e66201b31d6d4 100644
--- a/bolt/docs/OptimizingClang.md
+++ b/bolt/docs/OptimizingClang.md
@@ -41,7 +41,7 @@ Collecting accurate profile requires running `perf` on a hardware that
implements taken branch sampling (`-b/-j` flag). For that reason, it may not be possible to
collect the accurate profile in a virtualized environment, e.g. in the cloud.
We do support regular sampling profiles, but the performance
-improvements are expected to be more modest.
+improvements are expected to be more modest.
```bash
$ mkdir ${TOPLEV}/stage3
@@ -211,7 +211,8 @@ $ cd ${TOPLEV}/stage1
$ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_ASM_COMPILER=gcc \
- -DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt" \
+ -DLLVM_ENABLE_PROJECTS="clang;lld" \
+ -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
-DCOMPILER_RT_BUILD_SANITIZERS=OFF -DCOMPILER_RT_BUILD_XRAY=OFF \
-DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
-DCMAKE_INSTALL_PREFIX=${TOPLEV}/stage1/install
diff --git a/clang/docs/DataFlowSanitizer.rst b/clang/docs/DataFlowSanitizer.rst
index b4136a935dd28..6faca3f2ed913 100644
--- a/clang/docs/DataFlowSanitizer.rst
+++ b/clang/docs/DataFlowSanitizer.rst
@@ -32,15 +32,15 @@ libc++ and the libc++ ABI with data flow sanitizer instrumentation.
.. code-block:: console
+ mkdir libcxx-build
cd libcxx-build
# An example using ninja
- cmake -GNinja path/to/llvm-project/llvm \
+ cmake -GNinja -S <monorepo-root>/runtimes \
-DCMAKE_C_COMPILER=clang \
-DCMAKE_CXX_COMPILER=clang++ \
-DLLVM_USE_SANITIZER="DataFlow" \
- -DLLVM_ENABLE_LIBCXX=ON \
- -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi"
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"
ninja cxx cxxabi
diff --git a/clang/docs/Toolchain.rst b/clang/docs/Toolchain.rst
index 2ed835c0317e4..958199eb7a2e2 100644
--- a/clang/docs/Toolchain.rst
+++ b/clang/docs/Toolchain.rst
@@ -230,7 +230,7 @@ libunwind (LLVM)
^^^^^^^^^^^^^^^^
LLVM's unwinder library is part of the llvm-project git repository. To
-build it, pass ``-DLLVM_ENABLE_PROJECTS=libunwind`` to the cmake invocation.
+build it, pass ``-DLLVM_ENABLE_RUNTIMES=libunwind`` to the cmake invocation.
If using libc++abi, you may need to configure it to use libunwind
rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``
diff --git a/compiler-rt/www/index.html b/compiler-rt/www/index.html
index 3954a3c4e516a..d190565244004 100644
--- a/compiler-rt/www/index.html
+++ b/compiler-rt/www/index.html
@@ -112,7 +112,7 @@ <h2>Get it and get involved!</h2>
<p>Generally, you need to build LLVM/Clang in order to build compiler-rt. You
can build it either together with llvm and clang, or separately.
- <p>To build it together, simply add compiler-rt to the -DLLVM_ENABLE_PROJECTS= option to
+ <p>To build it together, simply add compiler-rt to the -DLLVM_ENABLE_RUNTIMES= option to
cmake.
<p>To build it separately, first
diff --git a/flang/README.md b/flang/README.md
index a8cd9c83846df..604049a5ebee9 100644
--- a/flang/README.md
+++ b/flang/README.md
@@ -33,8 +33,8 @@ read the [style guide](docs/C++style.md)
and
also review [how flang uses modern C++ features](docs/C++17.md).
-If you are interested in writing new documentation, follow
-[markdown style guide from LLVM](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
+If you are interested in writing new documentation, follow
+[LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
## Building flang
There are two ways to build flang. The first method is to build it at the same
@@ -55,7 +55,7 @@ Note that compiler-rt is only needed to access libraries that support 16 bit
floating point numbers. It's not needed to run the automated tests.
Here's a complete set of commands to clone all of the necessary source and do
-the build.
+the build.
First clone the source:
```bash
@@ -79,7 +79,8 @@ cmake \
-DLLVM_TARGETS_TO_BUILD=host \
-DCMAKE_INSTALL_PREFIX=$INSTALLDIR
-DLLVM_LIT_ARGS=-v \
- -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;compiler-rt"
+ -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" \
+ -DLLVM_ENABLE_RUNTIMES="compiler-rt"
ninja
```
diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst
index 8c0d007e89192..0e536ccfecf0e 100644
--- a/libcxx/docs/BuildingLibcxx.rst
+++ b/libcxx/docs/BuildingLibcxx.rst
@@ -523,8 +523,8 @@ We can now run CMake:
.. code-block:: bash
- $ cmake -G Ninja -S llvm -B build \
- -DLLVM_ENABLE_PROJECTS="libcxx" \
+ $ cmake -G Ninja -S runtimes -B build \
+ -DLLVM_ENABLE_RUNTIMES="libcxx" \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
$ ninja -C build install-cxx
@@ -549,8 +549,8 @@ We can now run CMake like:
.. code-block:: bash
- $ cmake -G Ninja -S llvm -B build \
- -DLLVM_ENABLE_PROJECTS="libcxx" \
+ $ cmake -G Ninja -S runtimes -B build \
+ -DLLVM_ENABLE_RUNTIMES="libcxx" \
-DLIBCXX_CXX_ABI=libcxxrt \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
$ ninja -C build install-cxx
diff --git a/libunwind/docs/BuildingLibunwind.rst b/libunwind/docs/BuildingLibunwind.rst
index d4e051e93a74f..99e52761515cc 100644
--- a/libunwind/docs/BuildingLibunwind.rst
+++ b/libunwind/docs/BuildingLibunwind.rst
@@ -32,7 +32,7 @@ The basic steps needed to build libc++ are:
* ``cd where you want to build llvm``
* ``mkdir build``
* ``cd build``
- * ``cmake -G <generator> -DLLVM_ENABLE_PROJECTS=libunwind [options] <path to llvm sources>``
+ * ``cmake -G <generator> -DLLVM_ENABLE_RUNTIMES=libunwind [options] <llvm-monorepo>/runtimes``
For more information about configuring libunwind see :ref:`CMake Options`.
diff --git a/llvm/docs/BuildingADistribution.rst b/llvm/docs/BuildingADistribution.rst
index ee7abe1f5cd7f..e52e55cb996c0 100644
--- a/llvm/docs/BuildingADistribution.rst
+++ b/llvm/docs/BuildingADistribution.rst
@@ -199,8 +199,8 @@ Relevant CMake Options
This section provides documentation of the CMake options that are intended to
help construct distributions. This is not an exhaustive list, and many
additional options are documented in the :doc:`CMake` page. Some key options
-that are already documented include: *LLVM_TARGETS_TO_BUILD*,
-*LLVM_ENABLE_PROJECTS*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
+that are already documented include: *LLVM_TARGETS_TO_BUILD*, *LLVM_ENABLE_PROJECTS*,
+*LLVM_ENABLE_RUNTIMES*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
**LLVM_ENABLE_RUNTIMES**:STRING
When building a distribution that includes LLVM runtime projects (i.e. libcxx,
diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index a567c8e501044..ac635fc7df885 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -221,6 +221,10 @@ description is in `LLVM-related variables`_ below.
Control which projects are enabled. For example you may want to work on clang
or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.
+**LLVM_ENABLE_RUNTIMES**:STRING
+ Control which runtimes are enabled. For example you may want to work on
+ libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
+
**LLVM_LIBDIR_SUFFIX**:STRING
Extra suffix to append to the directory where libraries are to be
installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
@@ -505,17 +509,17 @@ enabled sub-projects. Nearly all of these variable names begin with
**LLVM_ENABLE_PROJECTS**:STRING
Semicolon-separated list of projects to build, or *all* for building all
- (clang, lldb, compiler-rt, lld, polly, etc) projects. This flag assumes
- that projects are checked out side-by-side and not nested, i.e. clang
- needs to be in parallel of llvm instead of nested in `llvm/tools`.
- This feature allows to have one build for only LLVM and another for clang+llvm
- using the same source checkout.
+ (clang, lldb, lld, polly, etc) projects. This flag assumes that projects
+ are checked out side-by-side and not nested, i.e. clang needs to be in
+ parallel of llvm instead of nested in `llvm/tools`. This feature allows
+ to have one build for only LLVM and another for clang+llvm using the same
+ source checkout.
The full list is:
- ``clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;openmp;polly;pstl``
+ ``clang;clang-tools-extra;cross-project-tests;libc;libclc;lld;lldb;openmp;polly;pstl``
**LLVM_ENABLE_RUNTIMES**:STRING
- Build libc++, libc++abi or other projects using that a just-built compiler.
- This is the correct way to build libc++ when putting together a toolchain.
+ Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler.
+ This is the correct way to build runtimes when putting together a toolchain.
It will build the builtins separately from the other runtimes to preserve
correct dependency ordering. If you want to build the runtimes using a system
compiler, see the `libc++ documentation <https://libcxx.llvm.org/BuildingLibcxx.html>`_.
diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index d1eaa09cfc26b..7d699d87491bb 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -623,10 +623,15 @@ used by people developing LLVM.
| | other LLVM subprojects to additionally build. (Only|
| | effective when using a side-by-side project layout |
| | e.g. via git). The default list is empty. Can |
-| | include: clang, clang-tools-extra, compiler-rt, |
-| | cross-project-tests, flang, libc, libclc, libcxx, |
-| | libcxxabi, libunwind, lld, lldb, mlir, openmp, |
-| | polly, or pstl. |
+| | include: clang, clang-tools-extra, |
+| | cross-project-tests, flang, libc, libclc, lld, |
+| | lldb, mlir, openmp, polly, or pstl. |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_RUNTIMES | A semicolon-delimited list selecting which of the |
+| | runtimes to build. (Only effective when using the |
+| | full monorepo layout). The default list is empty. |
+| | Can include: compiler-rt, libc, libcxx, libcxxabi, |
+| | libunwind, or openmp. |
+-------------------------+----------------------------------------------------+
| LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source |
| | code. This is disabled by default because it is |
@@ -1217,6 +1222,11 @@ following options with cmake:
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.)
+ 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
should improve your build time slightly.
More information about the cfe-commits
mailing list