docs: Add instructions for stand-alone builds of clang

[tstellar]

Summary

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

[h-vetinari]

Sorry it took me a while to respond, was AFK last week. This looks like a good start, I can try testing the instructions with the LLVM 15 builds (also RCs) and report back with what I find.

llvm/docs/GettingStarted.rst

142

Isn't CLANG_BUILT_STANDALONE also necessary (honest question)?

[mgorny]

llvm/docs/GettingStarted.rst

142

In Gentoo, we also check llvm/lib/Transforms/Hello out unconditionally (don't recall why we added it, maybe it's not needed anymore, gotta check at some point), and llvm/lib/Testing/Support and llvm/utils for tests.

[MaskRay]

llvm/docs/GettingStarted.rst

130

What files are needed for the llvm installation? LLVM_ENABLE_PROJECTS=llvm with everything installed by ninja install ?

132

Add backsticks for /usr/bin, -D, etc.

Is Clang_DIR worth mentioning? See https://lldb.llvm.org/resources/build.html#standalone-builds

[tstellar]

Add a section about how to build LLVM so that it is consumable by
stand-alone builds, and fix some formatting.

[tstellar]

llvm/docs/GettingStarted.rst

130

I updated the patch now with instructions about how to build LLVM.

132

Is Clang_DIR worth mentioning? See https://lldb.llvm.org/resources/build.html#standalone-builds

I will mention this if/when I add documention for lldb, but it's not needed for the clang builds.

142

Transforms/Hello is only needed if you build clang-tools-extra (which is not enabled with these instructions). I also have a patch to make the D120301.

Testing/Support is only needed for the unittests which aren't run in the documented configuration (because there is no googletest).

I don't think llvm/utils is needed after https://github.com/llvm/llvm-project/commit/74384c7fcec71cb040b0c874743e5fc38b2cd7a6

This documentation is for the most minimal config that I could get working without any additional changes, so no clang-tools-extra and no unittests.

142

Isn't CLANG_BUILT_STANDALONE also necessary (honest question)?

No, this value is auto-detected based on the source layout.

[MaskRay]

LGTM, but worth getting opinions from actual standalone (stand-alone) build users

llvm/docs/GettingStarted.rst

110

I just read https://brians.wsu.edu/2016/05/31/standalone-stand-alone/

When one greps in llvm-project, which word do they more likely use, standalone or stand-alone? I tend to use standalone. Then I checked git shortlog -sn --grep standalone and git shortlog -sn --grep stand-alone. The former is more popular while the latter is not too uncommon...

134

Does install-distribution with LLVM_DISTRIBUTION_COMPONENTS work? From the name, LLVM_DISTRIBUTION_COMPONENTS is recommended for distributions and standalone builds are preferred by distributions.

144

146

Is the formal CMake term "variable" instead of "option"?

157

You may check what flang requires and make the second column sufficiently long to accommodate its needs.

[tstellar]

More formatting fixes.

[tstellar]

llvm/docs/GettingStarted.rst

110

I agree we should be consistent, but I have not preference about which spelling to use.

134

For Fedora, we don't use LLVM_DISTRIBUTION_COMPONENT, mainly because we already install everything, but also because it's very hard to keep the variable updated when new things are added. My concern with using it is that we would easily miss new features.

146

Technically, those are both variables internally, but the cmake man page refers to anything passed to cmake command line as an option.

157

This is going to take a lot of work to figure out, maybe I can just make the column 20 chars longer? I think ideally flang would require just cmake, but I don't have any experience trying to do a stand-alone build.

[mgorny]

llvm/docs/GettingStarted.rst

142

Testing/Support is only needed for the unittests which aren't run in the documented configuration (because there is no googletest).

Well, I don't want to hijack your effort but I think unittests are quite important if we're running tests in the first place, and I don't recall needing anything "that special" to run them these days — just llvm/lib/Testing/Support and llvm/utils/{lit,llvm-lit,unittest} (however, given its size I suppose we could just take whole llvm/utils).

[tstellar]

llvm/docs/GettingStarted.rst

142

Enabling and documenting the unit tests are something that I'm planning to do, but I wanted to get the minimal configuration documentation done first. I also want to find a solution that doesn't involve having source from the llvm directory available, which will take some time. See D131919.

[tstellar]

@mgorny Are you OK with this as is for now?

[mgorny]

LGTM

llvm/docs/GettingStarted.rst

134

https://gitweb.gentoo.org/repo/gentoo.git/tree/sys-devel/llvm/llvm-16.0.0.9999.ebuild#n113 ;-)

[MaskRay]

llvm/docs/GettingStarted.rst

136

[MaskRay]

llvm/docs/GettingStarted.rst

112

There is usually one blank line after the header.

llvm/docs/GettingStarted.rst

#. Configure and build LLVM and Clang:
 
    * If you get an "internal compiler error (ICE)" or test failures, see
      `below`_.
 
 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
 ============
 
 Before you begin to use the LLVM system, review the requirements given below.
 This may save you some trouble by knowing ahead of time what hardware and
 software you will need.
 
 Hardware