Officially deprecate LLVM_ENABLE_PROJECTS for libc++, libc++abi and libunwind

[ldionne]

Summary

This updates the LLVM wide documentation for building LLVM and the runtimes
and adds a CMake warning when folks specify libcxx, libcxxabi or libunwind
in LLVM_ENABLE_PROJECTS, pointing them to the updated instructions for
building the runtimes.

[awarzynski]

This has been a source of confusion for many people - many thanks for clarifying this!

LGTM

[thakis]

llvm/CMakeLists.txt

67

libcxx libcxxabi libunwind are still part of LLVM_ALL_PROJECTS and...

87

...this is below the warning you added. So if you say LLVM_ALL_PROJECTS=all you still get the old behavior, without a warning. Is that intentional?

(Doesn't affect us, just happened to notice it while reading this file.)

[ldionne]

llvm/CMakeLists.txt

87

I think it was intentional -- I didn't intend to issue a warning for folks who use all if they are not using libcxx, libcxxabi or libunwind explicitly. I think the next step would be to remove libcxx, libcxxabi` and libunwind from all, and to make this warning into an error since we don't support this anymore as of the branch point.

llvm/CMakeLists.txt

if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   message(STATUS "No build type selected, default to Debug")
   set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Build type (default Debug)" FORCE)
 endif()
 
 # Side-by-side subprojects layout: automatically set the
 # LLVM_EXTERNAL_${project}_SOURCE_DIR using LLVM_ALL_PROJECTS
 # This allows an easy way of setting up a build directory for llvm and another
 # one for llvm+clang+... using the same sources.
 set(LLVM_ALL_PROJECTS "clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;libcxx;libcxxabi;libunwind;lld;lldb;mlir;openmp;polly;pstl")
 # The flang project is not yet part of "all" projects (see C++ requirements)
 set(LLVM_EXTRA_PROJECTS "flang")
 # List of all known projects in the mono repo
 set(LLVM_KNOWN_PROJECTS "${LLVM_ALL_PROJECTS};${LLVM_EXTRA_PROJECTS}")
 set(LLVM_ENABLE_PROJECTS "" CACHE STRING
   "Semicolon-separated list of projects to build (${LLVM_KNOWN_PROJECTS}), or \"all\".")
 foreach(proj ${LLVM_ENABLE_PROJECTS})
   if (NOT proj STREQUAL "all" AND NOT proj STREQUAL "llvm" AND NOT "${proj}" IN_LIST LLVM_KNOWN_PROJECTS)
      MESSAGE(FATAL_ERROR "${proj} isn't a known project: ${LLVM_KNOWN_PROJECTS}")
   endif()
 endforeach()
+foreach(proj "libcxx" "libcxxabi" "libunwind")
+  if (${proj} IN_LIST LLVM_ENABLE_PROJECTS)
+    message(WARNING "Using LLVM_ENABLE_PROJECTS=${proj} is deprecated now, please use -DLLVM_ENABLE_RUNTIMES=${proj} or "
+                    "see the instructions at https://libcxx.llvm.org/BuildingLibcxx.html for building the runtimes.")
+  endif()
+endforeach()
 
 if( LLVM_ENABLE_PROJECTS STREQUAL "all" )
   set( LLVM_ENABLE_PROJECTS ${LLVM_ALL_PROJECTS})
 endif()
 
 if ("flang" IN_LIST LLVM_ENABLE_PROJECTS)
   if (NOT "mlir" IN_LIST LLVM_ENABLE_PROJECTS)
     message(STATUS "Enabling MLIR as a dependency to flang")
     list(APPEND LLVM_ENABLE_PROJECTS "mlir")
   endif()
 

llvm/docs/CMake.rst

**LLVM_ENABLE_PEDANTIC**:BOOL
   possible. Defaults to ON.
 
 **LLVM_ENABLE_PIC**:BOOL
   Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
   this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
 
 **LLVM_ENABLE_PROJECTS**:STRING
   Semicolon-separated list of projects to build, or *all* for building all
-  (clang, libcxx, libcxxabi, 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`.
+  (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.
   The full list is:
-  ``clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;libcxx;libcxxabi;libunwind;lld;lldb;openmp;polly;pstl``
+  ``clang;clang-tools-extra;compiler-rt;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.
   It will build the builtins separately from the other runtimes to preserve
-  correct dependency ordering.
+  correct dependency ordering. If you want to build the runtimes using a system
+  compiler, see the `libc++ documentation <https://libcxx.llvm.org/BuildingLibcxx.html>`_.
   Note: the list should not have duplicates with `LLVM_ENABLE_PROJECTS`.
   The full list is:
   ``compiler-rt;libc;libcxx;libcxxabi;libunwind;openmp``
   To enable all of them, use:
   ``LLVM_ENABLE_RUNTIMES=all``
 
 
 **LLVM_ENABLE_RTTI**:BOOL

llvm/docs/GettingStarted.rst

* ``cmake -G <generator> [options] ../llvm``
      * ``Visual Studio`` --- for generating Visual Studio projects and
        solutions.
      * ``Xcode`` --- for generating Xcode projects.
 
      Some Common options:
 
      * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
        subprojects you'd like to additionally build. Can include any of: clang,
-       clang-tools-extra, libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld,
-       polly, or cross-project-tests.
+       clang-tools-extra, lldb, compiler-rt, lld, polly, or cross-project-tests.
 
        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
        pathname of where you want the LLVM tools and libraries to be installed
        (default ``/usr/local``).
 
      * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
        Release, RelWithDebInfo, and MinSizeRel. Default is Debug.