From 730c7a45f5f653cba662224a98e79ee9ce7ae2c3 Mon Sep 17 00:00:00 2001
From: Francesco Petrogalli <francesco.petrogalli@apple.com>
Date: Mon, 16 Jan 2023 10:29:11 +0100
Subject: [PATCH] [docs] Expand example on stand-alone builds.

1. Make explicit that the folder where to build a subproject in stand-alone mode can not be the same folder where LLVM was build.
2. Add a cut 'n paste example for building stand-alone `clang`.

Differential Revision: https://reviews.llvm.org/D141825
---
 llvm/docs/GettingStarted.rst | 47 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst
index c9eae85..f1bb2d7 100644
--- a/llvm/docs/GettingStarted.rst
+++ b/llvm/docs/GettingStarted.rst
@@ -127,7 +127,7 @@ like this:
 
 .. code-block:: console
 
-  cmake -G Ninja -S llvm -B $builddir \
+  cmake -G Ninja -S path/to/llvm-project/llvm -B $builddir \
         -DLLVM_INSTALL_UTILS=ON \
         -DCMAKE_INSTALL_PREFIX=/path/to/llvm/install/prefix \
         < other options >
@@ -138,15 +138,23 @@ Once llvm is installed, to configure a project for a stand-alone build, invoke C
 
 .. code-block:: console
 
-  cmake -G Ninja -S $subproj -B $buildir \
+  cmake -G Ninja -S path/to/llvm-project/$subproj \
+        -B $buildir_subproj \
         -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.
+Notice that:
+
+* The stand-alone build needs to happen in a folder that is not the
+  original folder where LLVMN was built
+  (`$builddir!=$builddir_subproj`).
+* ``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.
@@ -159,6 +167,31 @@ clang        clang, cmake             CLANG_INCLUDE_TESTS=ON (Required for check
 lld          lld, cmake
 ============ ======================== ======================
 
+Example for building stand-alone `clang`:
+
+.. code-block:: console
+
+   #!/bin/sh
+
+   build_llvm=`pwd`/build-llvm
+   build_clang=`pwd`/build-clang
+   installprefix=`pwd`/install
+   llvm=`pwd`/llvm-project
+   mkdir -p $build_llvm
+   mkdir -p $installprefix
+
+   cmake -G Ninja -S $llvm/llvm -B $build_llvm \
+         -DLLVM_INSTALL_UTILS=ON \
+         -DCMAKE_INSTALL_PREFIX=$installprefix \
+         -DCMAKE_BUILD_TYPE=Release
+
+   ninja -C $build_llvm install
+
+   cmake -G Ninja -S $llvm/clang -B $build_clang \
+         -DLLVM_EXTERNAL_LIT=$build_llvm/utils/lit \
+         -DLLVM_ROOT=$installprefix
+
+   ninja -C $build_clang
 
 Requirements
 ============
-- 
2.7.4