From 27ca5821492ace53e1006c3643c8add8ebbe2f6c Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 30 Jan 2016 18:19:46 +0200 Subject: Move INSTALL to cli, update --- INSTALL | 105 +++++++++++++++++++++++++++++++--------------------- INSTALL.cli | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ buildfile | 2 +- 3 files changed, 184 insertions(+), 44 deletions(-) create mode 100644 INSTALL.cli 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 -- cgit v1.1