From 3944dea331b1d5840e45abcbea0572ddcdf80332 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 6 Sep 2016 15:59:08 +0200 Subject: Rewrite INSTALL --- INSTALL.cli | 123 ++++++++++++++++++++++++++---------------------------------- 1 file changed, 53 insertions(+), 70 deletions(-) diff --git a/INSTALL.cli b/INSTALL.cli index 659b803..7debe2b 100644 --- a/INSTALL.cli +++ b/INSTALL.cli @@ -3,118 +3,101 @@ // license : MIT; see accompanying LICENSE file " -Note: unless you specifically only need the \c{build2} build system and not the +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. +The instructions outlined below are essentially a summary of the first three +steps of the manual bootstrap process described in \c{build2-toolchain}. Also, +below we only show commands for UNIX-like operating systems. For other +operating systems and for more details on each step, refer to the +\c{build2-toolchain} documentation. + +\c{build2} requires a C++14 compiler. GCC 4.8 or later and Clang 3.4 or later +are known to work. The build system 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, we use the \c{bootstrap.sh} shell script (or +equivalent batch files for Windows) found in the root directory of the +\c{build2} distribution. The following is the recommended sequence of steps: -\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.sh}' 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 +\li|0. Prerequisites\n -Get \c{libbutl} and place it next to \c{build2}, so that you have: +Get \c{libbutl} (normally from the same place where you got \c{build2}) and +place it \i{inside} \c{build2}, so that you have: \ -libbutl/ (or libbutl-X.Y.Z/) -build2/ (or build2-X.Y.Z/) +build2-X.Y.Z +| +`-- libbutl-X.Y.Z \ | -\li|\n2. Bootstrapping\n +\li|\n1. Bootstrap, Phase 1\n -Change to the \c{build2/} directory and execute \c{bootstrap.sh} specifying -the C++ compiler to be used, if necessary (default is \c{g++}; run -\c{./bootstrap.sh --help} for other options). For example: +First, we build a minimal build system using \c{bootstrap.sh} (run +\c{bootstrap.sh -h} for options): \ -$ cd build2/ -$ ./bootstrap.sh --cxx clang++-3.5 -\ +$ cd build2-X.Y.Z +$ ./bootstrap.sh g++ -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 +\li|\n2. Bootstrap, Phase 2\n -Next, build \c{libbutl} and the \c{build2} binary using the bootstrapped -binary from step 2: +Then, we rebuild the build system with the result of Phase 1 linking +libraries statically. \ -$ 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=g++ config.bin.lib=static +$ mv build2/b build2/b-boot -\ -$ build2/b-boot config.cxx=clang++-3.5 ... +$ build2/b-boot --version \ -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. +\li|\n3. Build and Install\n -@@ 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: +Finally, we configure, build, and optionally install the \"final\" version +using shared libraries: \ -$ cd verify/build2 -$ ../../build2/build2/b '{configure update}(../libbutl-X.Y.Z/)' -$ ../../build2/build2/b config.import.libbutl=../../libbutl-X.Y.Z \ -configure update +$ build2/b-boot configure \ + config.cxx=g++ \ + config.cc.coptions=-O3 \ + config.bin.rpath=/usr/local/lib \ + config.install.root=/usr/local \ + config.install.sudo=sudo + +$ build2/b-boot \ -Once this is done, compare the \c{libbutl} libraries and \c{build2} binaries, -for example: +I you are not planning to install the result you can omit the +\c{config.install.*} values as well as \c{.rpath}. + + +To install: \ -$ cd ../.. -$ diff libbutl/butl/libbutl.so verify/libbutl/butl/libbutl.so -$ diff build2/build2/b verify/build2/build2/b +$ build2/b-boot install +$ which b +$ b --version \ -| - -\li|\n5. Installation\n +To uninstall: \ -$ build2/b config.install.root=/usr/local config.install.root.sudo=sudo \ -'install(../libbutl-X.Y.Z/ ./)' +$ b uninstall +$ which b \ -Note: you may want to add the \c{config.bin.rpath} configuration variable -if your installation location is not searched automatically for shared -libraries. See the \c{INSTALL} file in \c{build2-toolchain} for details.|| +|| " -- cgit v1.1