Move INSTALL to cli, update

3 files changed, 184 insertions, 44 deletions

diff --git a/INSTALL b/INSTALL
index d92779e..d067a99 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,68 +1,87 @@
 Note: unless you specifically only need the build2 build system and not the
-complete build2 toolchain, you should use the build2-toolchain distribution.
+complete build2 toolchain, you should use the build2-toolchain distribution
+instead.
 
 build2 requires a C++11 compiler with limited C++14 support. GCC 4.8 or later
 and Clang 3.4 or later are known to work.
 
-Build2 is self-hosted, which means that unless you have obtained a pre-built
+build2 is self-hosted, which means that unless you have obtained a pre-built
 binary from somewhere else, you will need to bootstrap it. To accomplish this,
 use the 'bootstrap' shell script found in the root directory of the build2
-distribution. The following is a recommended sequence of steps:
+distribution. The following is the recommended sequence of steps:
 
-0. Get libbutl and place it next to build2, so that you have:
+1. Prerequisites
 
-   libbutl/ (or libbutl-X.Y.Z/)
-   build2/  (or build2-X.Y.Z/)
+    Get libbutl and place it next to build2, so that you have:
 
-1. Change to the build2 directory and execute 'bootstrap' specifying
-   the C++ compiler to be used, if necessary (default is 'g++'; run
-   ./bootstrap --help for other options). For example:
+    libbutl/ (or libbutl-X.Y.Z/)
+    build2/  (or build2-X.Y.Z/)
 
-   $ cd build2/
-   $ ./bootstrap --cxx clang++-3.5
+2. Bootstrapping
 
-   Once the script completes successfully (which may take some time), the
-   build2 binary is saved as 'build2/b-boot':
+    Change to the build2/ directory and execute bootstrap specifying the C++
+    compiler to be used, if necessary (default is g++; run ./bootstrap --help
+    for other options). For example:
 
-   $ build2/b-boot --version
+    $ cd build2/
+    $ ./bootstrap --cxx clang++-3.5
 
-2. Next, build libbutl and the build2 binary using the bootstrapped binary
-   from step 1 above:
+    Once the script completes successfully (which may take some time), the
+    build2 binary is saved as build2/b-boot:
 
-   $ build2/b-boot 'configure(../libbutl/)'
-   $ build2/b-boot config.import.libbutl=../libbutl configure update
+    $ build2/b-boot --version
 
-   Again, if necessary, you can also specify the C++ compiler:
+3. Rebuilding
 
-   $ build2/b-boot config.cxx=clang++-3.5 ...
+    Next, build libbutl and the build2 binary using the bootstrapped binary
+    from step 2:
 
-   The resulting build2 binary is saved as 'build2/b':
+    $ build2/b-boot 'configure(../libbutl/)'
+    $ build2/b-boot config.import.libbutl=../libbutl configure update
 
-   $ build2/b --version
+    Again, if necessary, you can also specify the C++ compiler:
 
-3. The last step is optional and involves building libbutl and build2 using
-   the binary built on step 2 above and verifying that the two builds are
-   identical.
+    $ build2/b-boot config.cxx=clang++-3.5 ...
 
-   @@ This is currently broken since the resulting binary contains full
-      object file paths. So we would need to build in exactly the same
-      place as the original, but that would make the binary from step 2
-      unusable. It seems the only way to make it work is via staging.
+    The resulting build2 binary is saved as build2/b:
 
-   To perform this step, first unpack new copies of libbutl and build2 into
-   a different directory, for example, a verify/ sub-directory. Then complete
-   step 2 for these new copies but using build2/b binary from step 2 rather
-   than build2/b-boot from step 1. Also, use the libbutl from step 2 in the
-   config.import.libbutl value (otherwise rpath differences will result in
-   different build2 binaries). For example:
+    $ build2/b --version
 
-   $ cd verify/build2
-   $ ../../build2/build2/b '{configure update}(../libbutl/)'
-   $ ../../build2/build2/b config.import.libbutl=../../libbutl configure update
+4. Verification
 
-   Once this is done, compare the libbutl libraries and build2 binaries, for
-   example:
+    This step is optional and involves re-building libbutl and build2 yet again
+    using the binary built on step 3 and verifying that the two builds are
+    identical.
 
-   $ cd ../..
-   $ diff libbutl/butl/libbutl.so verify/libbutl/butl/libbutl.so
-   $ diff build2/build2/b verify/build2/build2/b
+    @@ This is currently broken since the resulting binary contains full object
+    file paths. So we would need to build in exactly the same place as the
+    original, but that would make the binary from step 2 unusable. It seems the
+    only way to make it work is via installation/staging.
+
+    To perform this step, first unpack new copies of libbutl and build2 into a
+    different directory, for example, a verify/ sub-directory. Then complete
+    step 2 for these new copies but using build2/b binary from step 3 rather
+    than build2/b-boot from step 2. Also, use the libbutl from step 2 in the
+    config.import.libbutl value (otherwise rpath differences will result in
+    different build2 binaries). For example:
+
+    $ cd verify/build2
+    $ ../../build2/build2/b '{configure update}(../libbutl-X.Y.Z/)'
+    $ ../../build2/build2/b config.import.libbutl=../../libbutl-X.Y.Z \
+    configure update
+
+    Once this is done, compare the libbutl libraries and build2 binaries, for
+    example:
+
+    $ cd ../..
+    $ diff libbutl/butl/libbutl.so verify/libbutl/butl/libbutl.so
+    $ diff build2/build2/b verify/build2/build2/b
+
+5. Installation
+
+    $ build2/b config.install.root=/usr/local config.install.root.sudo=sudo \
+    'install(../libbutl-X.Y.Z/ ./)'
+
+    Note: you may want to use the config.bin.rpath configuration variable on
+    step 3 if your installation location is not searched automatically for
+    shared libraries. See the INSTALL file in build2-toolchain for details.
diff --git a/INSTALL.cli b/INSTALL.cli
new file mode 100644
index 0000000..9f0f52a
--- /dev/null
+++ b/INSTALL.cli
@@ -0,0 +1,121 @@
+// file      : INSTALL.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"
+Note: unless you specifically only need the \c{build2} build system and not the
+complete \c{build2} toolchain, you should use the \c{build2-toolchain}
+distribution instead.
+
+\c{build2} requires a C++11 compiler with limited C++14 support. GCC 4.8 or
+later and Clang 3.4 or later are known to work.
+
+\c{build2} is self-hosted, which means that unless you have obtained a
+pre-built binary from somewhere else, you will need to bootstrap it. To
+accomplish this, use the '\c{bootstrap}' shell script found in the root
+directory of the \c{build2} distribution. The following is the recommended
+sequence of steps:
+
+\dl|
+
+\li|1. Prerequisites\n
+
+Get \c{libbutl} and place it next to \c{build2}, so that you have:
+
+\
+libbutl/ (or libbutl-X.Y.Z/)
+build2/  (or build2-X.Y.Z/)
+\
+
+|
+
+\li|\n2. Bootstrapping\n
+
+Change to the \c{build2/} directory and execute \c{bootstrap} specifying
+the C++ compiler to be used, if necessary (default is \c{g++}; run
+\c{./bootstrap --help} for other options). For example:
+
+\
+$ cd build2/
+$ ./bootstrap --cxx clang++-3.5
+\
+
+Once the script completes successfully (which may take some time), the
+\c{build2} binary is saved as \c{build2/b-boot}:
+
+\
+$ build2/b-boot --version
+\
+
+|
+
+\li|\n3. Rebuilding\n
+
+Next, build \c{libbutl} and the \c{build2} binary using the bootstrapped
+binary from step 2:
+
+\
+$ build2/b-boot 'configure(../libbutl/)'
+$ build2/b-boot config.import.libbutl=../libbutl configure update
+\
+
+Again, if necessary, you can also specify the C++ compiler:
+
+\
+$ build2/b-boot config.cxx=clang++-3.5 ...
+\
+
+The resulting \c{build2} binary is saved as \c{build2/b}:
+
+$ build2/b --version
+
+|
+
+\li|\n4. Verification\n
+
+This step is optional and involves re-building \c{libbutl} and \c{build2}
+yet again using the binary built on step 3 and verifying that the two builds
+are identical.
+
+@@ This is currently broken since the resulting binary contains full object
+file paths. So we would need to build in exactly the same place as the
+original, but that would make the binary from step 2 unusable. It seems the
+only way to make it work is via installation/staging.
+
+To perform this step, first unpack new copies of \c{libbutl} and \c{build2}
+into a different directory, for example, a \c{verify/} sub-directory. Then
+complete step 2 for these new copies but using \c{build2/b} binary from step
+3 rather than \c{build2/b-boot} from step 2. Also, use the \c{libbutl} from
+step 2 in the \c{config.import.libbutl} value (otherwise rpath differences
+will result in different \c{build2} binaries). For example:
+
+\
+$ cd verify/build2
+$ ../../build2/build2/b '{configure update}(../libbutl-X.Y.Z/)'
+$ ../../build2/build2/b config.import.libbutl=../../libbutl-X.Y.Z \
+configure update
+\
+
+Once this is done, compare the \c{libbutl} libraries and \c{build2} binaries,
+for example:
+
+\
+$ cd ../..
+$ diff libbutl/butl/libbutl.so verify/libbutl/butl/libbutl.so
+$ diff build2/build2/b verify/build2/build2/b
+\
+
+|
+
+\li|\n5. Installation\n
+
+\
+$ build2/b config.install.root=/usr/local config.install.root.sudo=sudo \
+'install(../libbutl-X.Y.Z/ ./)'
+\
+
+Note: you may want to use the \c{config.bin.rpath} configuration variable on
+step 3 if your installation location is not searched automatically for
+shared libraries. See the \c{INSTALL} file in \c{build2-toolchain} for
+details.||
+"
diff --git a/buildfile b/buildfile
index 77dc3bd..5bb9dd9 100644
--- a/buildfile
+++ b/buildfile
@@ -3,7 +3,7 @@
 # license   : MIT; see accompanying LICENSE file
 
 d = build2/ tests/
-./: $d doc{INSTALL LICENSE version} file{bootstrap manifest}
+./: $d doc{INSTALL LICENSE version} file{INSTALL.cli bootstrap manifest}
 include $d
 
 $src_base/doc{INSTALL}: install = false