[llvm] 1cb97a1 - docs: Add instructions for stand-alone builds of clang

[Tom Stellard via llvm-commits]

Author: Tom Stellard
Date: 2022-11-10T12:29:20-08:00
New Revision: 1cb97a1e2dab33c62f17db6a57e556bde26d4da5

URL: https://github.com/llvm/llvm-project/commit/1cb97a1e2dab33c62f17db6a57e556bde26d4da5
DIFF: https://github.com/llvm/llvm-project/commit/1cb97a1e2dab33c62f17db6a57e556bde26d4da5.diff

LOG: docs: Add instructions for stand-alone builds of clang

More sub-projects will be added to the table once they have been verified
to be buildable in stand-alone mode.

Reviewed By: MaskRay, mgorny

Differential Revision: https://reviews.llvm.org/D123968

Added: 
    

Modified: 
    llvm/docs/GettingStarted.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index e14ee9d8c8c5c..8d898fb985a70 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -107,6 +107,58 @@ Consult the `Getting Started with LLVM`_ section for detailed information on
 configuring and compiling LLVM.  Go to `Directory Layout`_ to learn about the
 layout of the source code tree.
 
+Stand-alone Builds
+------------------
+
+Stand-alone builds allow you to build a sub-project against a pre-built
+version of the clang or llvm libraries that is already present on your
+system.
+
+You can use the source code from a standard checkout of the llvm-project
+(as described above) to do stand-alone builds, but you may also build
+from a :ref:`sparse checkout<workflow-multicheckout-nocommit>` or from the
+tarballs available on the `releases <https://github.com/llvm/llvm-project/releases/>`_
+page.
+
+For stand-alone builds, you must have an llvm install that is configured
+properly to be consumable by stand-alone builds of the other projects.
+This could be a distro provided LLVM install, or you can build it yourself,
+like this:
+
+.. code-block:: console
+
+  cmake -G Ninja -S llvm -B $builddir \
+        -DLLVM_INSTALL_UTILS=ON \
+        -DCMAKE_INSTALL_PREFIX=/path/to/llvm/install/prefix \
+        < other options >
+
+  ninja -C $builddir install
+
+Once llvm is installed, to configure a project for a stand-alone build, invoke CMake like this:
+
+.. code-block:: console
+
+  cmake -G Ninja -S $subproj -B $buildir \
+        -DLLVM_EXTERNAL_LIT=/path/to/lit \
+        -DLLVM_ROOT=/path/to/llvm/install/prefix
+
+``LLVM_ROOT`` should point to the prefix of your llvm installation, so for example,
+if llvm is installed into ``/usr/bin`` and ``/usr/lib64``, then you should pass
+``-DLLVM_ROOT=/usr/``.  Both the ``LLVM_ROOT`` and ``LLVM_EXTERNAL_LIT`` options
+are required to do stand-alone builds for all sub-projects.  Additional required
+options for each sub-project can be found in the table below.
+
+The ``check-$subproj`` and ``install`` build targets are supported for the
+sub-projects listed in the table below.
+
+============ ======================== ======================
+Sub-Project  Required Sub-Directories Required CMake Options
+============ ======================== ======================
+llvm         llvm, cmake, third-party LLVM_INSTALL_UTILS=ON
+clang        clang, cmake             CLANG_INCLUDE_TESTS=ON (Required for check-clang only)
+============ ======================== ======================
+
+
 Requirements
 ============