ldionne created this revision.
Herald added subscribers: libcxx-commits, ayermolo, arphaman, mgorny.
Herald added a reviewer: sscalpone.
Herald added a reviewer: rafauler.
Herald added a reviewer: Amir.
Herald added a reviewer: maksfb.
Herald added projects: libunwind, Flang.
Herald added a reviewer: libunwind.
ldionne requested review of this revision.
Herald added a reviewer: jdoerfert.
Herald added subscribers: llvm-commits, Sanitizers, cfe-commits, yota9,
sstefan1, jdoerfert.
Herald added projects: clang, Sanitizers, libc++, LLVM.
Herald added a reviewer: libc++.
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.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D119351
Files:
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
Index: llvm/docs/GettingStarted.rst
===================================================================
--- llvm/docs/GettingStarted.rst
+++ llvm/docs/GettingStarted.rst
@@ -623,10 +623,15 @@
| | 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: libcxx, libcxxabi, libunwind, |
+| | compiler-rt, libc, 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 @@
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.
Index: llvm/docs/CMake.rst
===================================================================
--- llvm/docs/CMake.rst
+++ llvm/docs/CMake.rst
@@ -221,6 +221,10 @@
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 @@
**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>`_.
Index: llvm/docs/BuildingADistribution.rst
===================================================================
--- llvm/docs/BuildingADistribution.rst
+++ llvm/docs/BuildingADistribution.rst
@@ -199,8 +199,8 @@
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,
Index: libunwind/docs/BuildingLibunwind.rst
===================================================================
--- libunwind/docs/BuildingLibunwind.rst
+++ libunwind/docs/BuildingLibunwind.rst
@@ -32,7 +32,7 @@
* ``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] <path to llvm monorepo>/runtimes``
For more information about configuring libunwind see :ref:`CMake Options`.
Index: libcxx/docs/BuildingLibcxx.rst
===================================================================
--- libcxx/docs/BuildingLibcxx.rst
+++ libcxx/docs/BuildingLibcxx.rst
@@ -523,8 +523,8 @@
.. 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 @@
.. 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
Index: flang/README.md
===================================================================
--- flang/README.md
+++ flang/README.md
@@ -33,7 +33,7 @@
and
also review [how flang uses modern C++ features](docs/C++17.md).
-If you are interested in writing new documentation, follow
+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).
## Building flang
@@ -55,7 +55,7 @@
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 @@
-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
```
Index: compiler-rt/www/index.html
===================================================================
--- compiler-rt/www/index.html
+++ compiler-rt/www/index.html
@@ -112,7 +112,7 @@
<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
Index: clang/docs/Toolchain.rst
===================================================================
--- clang/docs/Toolchain.rst
+++ clang/docs/Toolchain.rst
@@ -230,7 +230,7 @@
^^^^^^^^^^^^^^^^
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``
Index: clang/docs/DataFlowSanitizer.rst
===================================================================
--- clang/docs/DataFlowSanitizer.rst
+++ clang/docs/DataFlowSanitizer.rst
@@ -32,17 +32,14 @@
.. code-block:: console
- cd libcxx-build
-
# An example using ninja
- cmake -GNinja path/to/llvm-project/llvm \
+ cmake -GNinja -S <monorepo-root>/runtimes -B <build> \
-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
+ ninja -C <build> cxx cxxabi
Note: Ensure you are building with a sufficiently new version of Clang.
Index: bolt/docs/OptimizingClang.md
===================================================================
--- bolt/docs/OptimizingClang.md
+++ bolt/docs/OptimizingClang.md
@@ -41,7 +41,7 @@
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
@@ -207,15 +207,16 @@
compiler-rt components that are known to cause build issues at release/7.x.
```bash
$ mkdir ${TOPLEV}/stage1
-$ cd ${TOPLEV}/stage1
-$ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
+$ cmake -G Ninja -S ${TOPLEV}/llvm-project/llvm -B ${TOPLEV}/stage1 \
+ -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
-$ ninja install
+$ ninja -C ${TOPLEV}/stage1 install
```
### Building Stage 2 Compiler With Instrumentation
@@ -224,15 +225,15 @@
profile generation capabilities:
```bash
$ mkdir ${TOPLEV}/stage2-prof-gen
-$ cd ${TOPLEV}/stage2-prof-gen
$ CPATH=${TOPLEV}/stage1/install/bin/
-$ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
+$ cmake -G Ninja -S ${TOPLEV}/llvm-project/llvm -B ${TOPLEV}/stage2-prof-gen \
+ -DLLVM_TARGETS_TO_BUILD=X86 \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=$CPATH/clang -DCMAKE_CXX_COMPILER=$CPATH/clang++ \
-DLLVM_ENABLE_PROJECTS="clang;lld" \
-DLLVM_USE_LINKER=lld -DLLVM_BUILD_INSTRUMENTED=ON \
-DCMAKE_INSTALL_PREFIX=${TOPLEV}/stage2-prof-gen/install
-$ ninja install
+$ ninja -C ${TOPLEV}/stage2-prof-gen install
```
### Generating Profile for PGO
@@ -242,14 +243,14 @@
while building Clang itself:
```bash
$ mkdir ${TOPLEV}/stage3-train
-$ cd ${TOPLEV}/stage3-train
$ CPATH=${TOPLEV}/stage2-prof-gen/install/bin
-$ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
+$ cmake -G Ninja -S ${TOPLEV}/llvm-project/llvm -B ${TOPLEV}/stage3-train \
+ -DLLVM_TARGETS_TO_BUILD=X86 \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=$CPATH/clang -DCMAKE_CXX_COMPILER=$CPATH/clang++ \
-DLLVM_ENABLE_PROJECTS="clang" \
-DLLVM_USE_LINKER=lld -DCMAKE_INSTALL_PREFIX=${TOPLEV}/stage3-train/install
-$ ninja clang
+$ ninja -C ${TOPLEV}/stage3-train clang
```
Once the build is completed, the profile files will be saved under
`${TOPLEV}/stage2-prof-gen/profiles`. We will merge them before they can be
@@ -270,10 +271,10 @@
on disk:
```bash
$ mkdir ${TOPLEV}/stage2-prof-use-lto
-$ cd ${TOPLEV}/stage2-prof-use-lto
$ CPATH=${TOPLEV}/stage1/install/bin/
$ export LDFLAGS="-Wl,-q"
-$ cmake -G Ninja ${TOPLEV}/llvm-project/llvm -DLLVM_TARGETS_TO_BUILD=X86 \
+$ cmake -G Ninja -S ${TOPLEV}/llvm-project/llvm -B ${TOPLEV}/stage2-prof-use-lto \
+ -DLLVM_TARGETS_TO_BUILD=X86 \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_C_COMPILER=$CPATH/clang -DCMAKE_CXX_COMPILER=$CPATH/clang++ \
-DLLVM_ENABLE_PROJECTS="clang;lld" \
@@ -281,7 +282,7 @@
-DLLVM_PROFDATA_FILE=${TOPLEV}/stage2-prof-gen/profiles/clang.profdata \
-DLLVM_USE_LINKER=lld \
-DCMAKE_INSTALL_PREFIX=${TOPLEV}/stage2-prof-use-lto/install
-$ ninja install
+$ ninja -C ${TOPLEV}/stage2-prof-use-lto install
```
Now we have a Clang compiler that can build itself much faster. As we will see,
it builds other applications faster as well, and, with BOLT, the compile time
Index: README.md
===================================================================
--- README.md
+++ README.md
@@ -63,13 +63,15 @@
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, or compiler-rt.
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
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
