From 879d7e92d823c9dfe6fb3691541f30b662f2a510 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 3 Sep 2016 17:27:33 +0200 Subject: First take on new installation and upgrade instructions --- .gitignore | 4 + BOOTSTRAP-MACOSX.cli | 30 +++++++ BOOTSTRAP-MINGW.cli | 27 ++++++ BOOTSTRAP-MSVC.cli | 29 +++++++ BOOTSTRAP-UNIX.cli | 80 +++++++++++++++++ BOOTSTRAP-WINDOWS.cli | 136 +++++++++++++++++++++++++++++ INSTALL | 164 ----------------------------------- INSTALL.cli | 234 ++++++++++---------------------------------------- UPGRADE.cli | 175 +++++++++++++++++++++++++++++++++++++ build/root.build | 16 +++- buildfile | 16 +++- doc/.gitignore | 6 +- doc/buildfile | 19 ++-- doc/cli.sh | 46 ++++++++-- doc/install.cli | 47 ++++++++++ doc/intro.cli | 5 -- 16 files changed, 652 insertions(+), 382 deletions(-) create mode 100644 .gitignore create mode 100644 BOOTSTRAP-MACOSX.cli create mode 100644 BOOTSTRAP-MINGW.cli create mode 100644 BOOTSTRAP-MSVC.cli create mode 100644 BOOTSTRAP-UNIX.cli create mode 100644 BOOTSTRAP-WINDOWS.cli delete mode 100644 INSTALL create mode 100644 UPGRADE.cli create mode 100644 doc/install.cli diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..68e3c03 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +INSTALL +UPGRADE +BOOTSTRAP-* +!BOOTSTRAP-*.cli diff --git a/BOOTSTRAP-MACOSX.cli b/BOOTSTRAP-MACOSX.cli new file mode 100644 index 0000000..a60a145 --- /dev/null +++ b/BOOTSTRAP-MACOSX.cli @@ -0,0 +1,30 @@ +// file : BOOTSTRAP-MACOSX.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +The \c{build2} toolchain requires Mac OS version 10.5 (Leopard) or later. We +will also be using the system C++ toolchain that comes with the Xcode Command +Line Tools (you should be able to use a custom C++ toolchain, however, this +is the only configuration that is tested and guaranteed to work). + +To verify Command Line Tools are installed, run: + +\ +$ clang++ --version +\ + +It should produce something along these lines: + +\ +Apple LLVM version X.Y.Z (clang-A.B.C) (based on LLVM M.N.P) +\ + +To install Command Line Tools, run: + +\ +$ xcode-select --install +\ + +Once this is done continue with \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}. +" diff --git a/BOOTSTRAP-MINGW.cli b/BOOTSTRAP-MINGW.cli new file mode 100644 index 0000000..75a1c49 --- /dev/null +++ b/BOOTSTRAP-MINGW.cli @@ -0,0 +1,27 @@ +// file : BOOTSTRAP-MINGW.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +Continuing with Windows Bootstrap, to build with MinGW you can either perform +the following steps manually or, if you are happy with using the defaults, run +the \c{build-mingw.bat} batch file. It performs (and echoes) the same set of +steps as outline below but only allows you to customization the compiler and +installation directory (run \c{build-mingw.bat /?} for usage) and you can also +specify an alternative package repository with the \c{BUILD2_REPO} environment +variable. + +For example, if your MinGW distribution is in \c{C:\\mingw\\}, then you could +run it (from the command prompt that we have started earlier) like this: + +\ +> build-mingw.bat C:\mingw\bin\g++ +\ + +If you are using the \c{build2-mingw} package then you should be able to +use just \c{g++} for the compiler: + +\ +> build-mingw.bat g++ +\ +" diff --git a/BOOTSTRAP-MSVC.cli b/BOOTSTRAP-MSVC.cli new file mode 100644 index 0000000..36b666e --- /dev/null +++ b/BOOTSTRAP-MSVC.cli @@ -0,0 +1,29 @@ +// file : BOOTSTRAP-MSVC.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +Continuing with Windows Bootstrap, if you have already started an appropriate +Visual Studio command prompt, then you can continue using it. Otherwise, start +the \"x64 Native Tools Command Prompt\" if you are on 64-bit Windows or \"x86 +Native Tools Command Prompt\" if you are on 32-bit. Also set the \c{PATH} +environment variable: + +\ +> set PATH=C:\build2\bin;%PATH% +\ + +To build with MSVC you can either perform the following steps manually or, if +you are happy with using the defaults, run the \c{build-msvc.bat} batch file. +It performs (and echoes) the same set of steps as outline below but only +allows you to customization the installation directory (run \c{build-msvc.bat +/?} for usage) and you can also specify an alternative package repository with +the \c{BUILD2_REPO} environment variable. + +For example, you could run thsi batch file (from the above-mentioned command +prompt) like this: + +\ +> build-msvc.bat +\ +" diff --git a/BOOTSTRAP-UNIX.cli b/BOOTSTRAP-UNIX.cli new file mode 100644 index 0000000..864db7d --- /dev/null +++ b/BOOTSTRAP-UNIX.cli @@ -0,0 +1,80 @@ +// file : BOOTSTRAP-UNIX.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +The following instructions are for bootstrapping \c{build2} on UNIX-like +operating systems (GNU/Linux, FreeBSD, etc). For Mac OS X first see +\l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}. These instructions should +also be used for UNIX emulation layers on Windows (for example, MSYS2 or +Cygwin) where you already have a UNIX shell with standard utilitis. + +\dl| + +\li|1. Create Build Directory\n + +Note that you will want to keep this directory around in order to upgrade to +new toolchain versions in the future. In this guide we will use +\c{~/build2-build/} as the build directory and \c{/usr/local/} as the +installation directory but you can use other paths. + +\ +$ cd +$ mkdir build2-build +$ cd build2-build +\ + +| + +\li|\n2. Download, Verify, and Unpack\n + +Download \c{build2-toolchain-X.Y.Z.tar.xz} (or its \c{.tar.gz} variant if you +don't have \cb{xz(1)}) as well as its \c{.sha256} checksum from +\l{https://download.build2.org}, into \c{~/build2-build/} (build directory). + +Verify the archive checksum matches: + +\ +# Linux, MSYS, Cygwin: +# +$ sha256sum -c build2-toolchain-X.Y.Z.tar.xz.sha256 + +# Mac OS X: +# +$ shasum -a 256 -c build2-toolchain-X.Y.Z.tar.xz.sha256 + +# FreeBSD: +# +$ sha256 -r build2-toolchain-X.Y.Z.tar.xz +$ cat build2-toolchain-X.Y.Z.tar.xz.sha256 +\ + +Unpack the archive and change to its directory: + +\ +> tar xf build2-toolchain-X.Y.Z.tar.xz +> cd build2-toolchain-X.Y.Z +\ + +|| + +Next you can either perform the rest of the steps manually or, if you are +happy with using the defaults, run the \c{build.sh} shell script. It performs +(and echoes) the same set of steps as outline below but only allows you to +customization the compiler and installation directory (run \c{build.sh -h} for +usage) and you can also specify an alternative package repository with the +\c{BUILD2_REPO} environment variable. + +For example, this command will use \c{g++-5} and install the toolchain into +\c{/usr/local/}. + +\ +$ build.sh g++-5 +\ + +While this will use Clang and install into \c{/opt/build2}: + +\ +$ build.sh --install-dir /opt/build2 --sudo sudo clang++ +\ +" diff --git a/BOOTSTRAP-WINDOWS.cli b/BOOTSTRAP-WINDOWS.cli new file mode 100644 index 0000000..872a10a --- /dev/null +++ b/BOOTSTRAP-WINDOWS.cli @@ -0,0 +1,136 @@ +// file : BOOTSTRAP-WINDOWS.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +The following instructions are for bootstrapping \c{build2} with either MSVC +or MinGW using the Windows command prompt. If you are using any kind of UNIX +emulation layer (for example, MSYS2 or Cygwin) and already have a UNIX shell +with standard utilitis, then you most likely should follow \l{#BOOTSTRAP-UNIX +Bootstrapping on UNIX} instead. + +The \c{build2} toolchain on Windows requires a set of extra utilities +(\c{install}, \c{diff}, \c{wget}, \c{tar}, etc). These are provided in the +\c{build2-baseutils} package (see the \c{README} file inside for details). +Normally the \c{build2} toolchain itself is installed into the same directory +as the utilities in order to produce a combined \c{build2+utilities} +installation. + +To build on Windows you will need either MSVC 14 Update 2 or later or MinGW +GCC 4.8 or later. Note also that MinGW GCC must be configured with the +\c{posix} threading model (this is currently the only configuration that +implements C++11 threads; run \c{g++ --version} to verify). + +If you don't already have a suitable C++ compiler, then you can use the +\c{build2-mingw} package which provides a minimal MinGW-W64 GCC distribution +(see the \c{README} file inside for details). If used, then it should be +unpacked into the same directory as \c{build2-baseutils} as described below. + +\dl| + +\li|1. Open Command Prompt\n + +Start the standard Windows Command Prompt. If you plan to build with MSVC, +then you may go ahead and start the Visual Studio Command Prompt (or wait +until MSVC-specific instructions). +| + +\li|\n2. Create Build Directory\n + +Note that you will want to keep this directory around in order to upgrade +to new toolchain versions in the future. In this guide we will use +\c{C:\\build2-build\\} as the build directory and \c{C:\\build2\\} as the +installation directory but you can use other paths. + +\ +> C: +> cd \ +> mkdir build2-build +> cd build2-build +\ + +| + +\li|\n3. Download Archives\n + +Download the following files as well as their \c{.sha256} checksums from +\l{https://download.build2.org}, replacing \i{} with \c{x86_64} for +64-bin Windows and with \c{i686} for 32-bit. Place everything into +\c{C:\\build2-build\\} (build directory). + +\ +build2-baseutils-X.Y.Z-.zip +build2-mingw-X.Y.Z-.tar.xz (if required) +build2-toolchain-X.Y.Z.tar.xz +\ + +| + +\li|\n4. Verify Archive Checksums\n + +Verify archive checksums match: + +\ +> type *.sha256 +> for %f in (*.zip *.xz) do certutil -hashfile %f SHA256 +\ + +| + +\li|\n5. Unpack \c{build2-baseutils}\n + +Unpack the \c{build2-baseutils-X.Y.Z-.zip} archive into to \c{C:\\} using +Windows Explorer (for example, copy the archive directory and paste it). +Rename it to \c{C:\\build2\\}. This will be the toolchain installation +directory. +| + +\li|\n6. Set \c{PATH}\n + +Also verify the utilities are found and work: + +\ +> set PATH=C:\build2\bin;%PATH% +> where tar +> tar --version +\ + +| + +\li|\n7. Unpack \c{build2-mingw}\n + +If required, unpack the \c{build2-mingw-X.Y.Z-.tar.xz} archive into +\c{C:\\build2\\}: + +\ +> tar xf build2-mingw-X.Y.Z--windows.tar.xz ^ + --one-top-level=C:\build2 --strip-components=1 +\ + +Verify the MinGW GCC is found and works: + +\ +> where g++ +> g++ --version +\ + +| + +\li|\n8. Unpack \c{build2-toolchain}\n + +Unpack the \c{build2-toolchain-X.Y.Z.tar.xz} archive and change to its +directory: + +\ +> tar xf build2-toolchain-X.Y.Z.tar.xz +> cd build2-toolchain-X.Y.Z +\ + +|| + +If building with MSVC, continue with \l{#BOOTSTRAP-MSVC Bootstrapping with +MSVC}. + +If building with MinGW, continue with \l{#BOOTSTRAP-MINGW Bootstrapping with +MINGW}. +" diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 7c7516d..0000000 --- a/INSTALL +++ /dev/null @@ -1,164 +0,0 @@ -The build2 toolchain 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. If you only need the -build2 build system without the bpkg package manager, then the C++ compiler is -all you will need. If, however, you would also like to build bpkg, then you -will also need to obtain SQLite as well as the libodb and libodb-sqlite -libraries (discussed below). - -In this guide we install everything that we build into /usr/local. If you would -like to use a different installation location, you will need to make -adjustments to the commands below. - -Note on /usr/local: most distributions these days "cripple" this location by -either not searching /usr/local/include for headers during compilation (so we -add the -I option) or not searching /usr/local/lib for libraries either during -linking (so we add the -L option) or at runtime (which we fix with the help of --rpath). If you know that your installation doesn't suffer from (some of) these -issues, then you can adjust the commands below accordingly. Note that even if -/usr/local/lib is searched in at runtime, you may still have to run ldconfig(1) -(as root) after the installation to refresh the library cache. - -Note to Mac OS users: you will need version 10.5 (Leopard) or later. We will -also be using the system C++ toolchain that comes with the Xcode Command Line -Tools. To verify it is installed, run: - -$ g++ --version - -To install Command Line Tools, run: - -$ xcode-select --install - -1. Installing SQLite - - Skip this step if you are only interested in the build2 build system. - - To install SQLite, use your distribution's package manager and make sure - you install both the libraries (most likely already installed) and the - development files. - - For Debian/Ubuntu: - - $ sudo apt-get install libsqlite3-dev - - For RedHat/Fedora: - - $ sudo yum install sqlite-devel - - For FreeBSD: - - # pkg install sqlite3 - - For Mac OS: - - You should already have a system-default version installed. To verify: - - $ ls /usr/include/sqlite3.h /usr/lib/libsqlite3.dylib - - To see which version you have, run: - - $ grep '#define SQLITE_VERSION' /usr/include/sqlite3.h - - Any recent version (i.e., greater than 3.5.0) should work. If for some - reason you don't seem to have SQLite, download the source code then build - and install it into /usr/local. - -2. Installing libodb and libodb-sqlite - - Again, skip this step if you are only interested in the build2 build - system. - - [Currently we use pre-release versions of these libraries so they have to - be built from source.] - - Download source packages for the two libraries from the same location as - build2-toolchain (https://download.build2.org). Then unpack, build, and - install: - - $ cd lib*-X.Y.Z - - $ ./configure --prefix=/usr/local \ - CPPFLAGS=-I/usr/local/include \ - LDFLAGS=-L/usr/local/lib - - $ make - $ sudo make install - - See the INSTALL file for each library for more information. - -3. Bootstrapping build2 - - Download build2-toolchain (https://download.build2.org) then unpack and - bootstrap the build2 build system: - - $ cd build2-toolchain-X.Y.Z - $ cd build2/ - $ ./bootstrap - $ cd .. - $ ./build2/build2/b-boot build2/ - - For more information on this step (for example, how to specify the C++ - compiler, options, etc.), refer to the INSTALL file in the build2/ - subdirectory of build2-toolchain. Note that you must use global overrides - (!) if specifying any config.* variables on the last line. For example: - - $ ./build2/build2/b-boot '!config.cxx=clang++' build2/ - -4. Configuring, Building, and Installing the Rest of the Toolchain - - $ ./build2/build2/b \ - config.cxx.poptions=-I/usr/local/include \ - config.cxx.loptions=-L/usr/local/lib \ - config.bin.rpath=/usr/local/lib \ - config.install.root=/usr/local \ - config.install.root.sudo=sudo \ - configure - - $ ./build2/build2/b update - $ ./build2/build2/b install - - To test the installation, run: - - $ which b - /usr/local/bin/b - $ b --version - - $ which bpkg - /usr/local/bin/bpkg - $ bpkg --version - -5. Setting up updates with the package manager - - If you only need to build this specific version of the toolchain, then you - are done and can skip this step. However, if you are planning to upgrade to - future versions, then going every time through the bootstrap steps will be - tedious. Instead, we can use the bpkg package manager to manage upgrades - automatically. Note also that without periodic upgrades your version of the - toolchain may become too old to be able to upgrade itself. In this case you - will have to fall back onto the bootstrap process. - - First, choose a directory where you would like bpkg to build everything, - for example, build2-toolchain. Then: - - $ cd # back to home directory - $ mkdir build2-toolchain - $ cd build2-toolchain - - $ bpkg create \ - cxx \ - config.cxx.poptions=-I/usr/local/include \ - config.cxx.loptions=-L/usr/local/lib \ - config.bin.rpath=/usr/local/lib \ - config.install.root=/usr/local \ - config.install.root.sudo=sudo - - $ bpkg add https://pkg.cppget.org/1/alpha - $ bpkg fetch - $ bpkg build build2 bpkg - $ bpkg install build2 bpkg - - Later, to upgrade to a new version of the toolchain, simply do: - - $ bpkg fetch - $ bpkg status build2 bpkg # See if any upgrades are available. - $ bpkg build build2 bpkg - $ bpkg install build2 bpkg diff --git a/INSTALL.cli b/INSTALL.cli index 9a05afc..a8442fa 100644 --- a/INSTALL.cli +++ b/INSTALL.cli @@ -3,208 +3,68 @@ // license : MIT; see accompanying LICENSE file " -The \c{build2} toolchain 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. If you only need the -\c{build2} build system without the \c{bpkg} package manager, then the C++ -compiler is all you will need. If, however, you would also like to build -\c{bpkg}, then you will also need to obtain SQLite as well as the \c{libodb} -and \c{libodb-sqlite} libraries (discussed below). - -In this guide we install everything that we build into \c{/usr/local}. If you -would like to use a different installation location, you will need to make -adjustments to the commands below. - -Note on \c{/usr/local}: most distributions these days \"cripple\" this location -by either not searching \c{/usr/local/include} for headers during compilation -(so we add the \c{-I} option) or not searching \c{/usr/local/lib} for libraries -either during linking (so we add the \c{-L} option) or at runtime (which we fix -with the help of \c{-rpath}). If you know that your installation doesn't suffer -from (some of) these issues, then you can adjust the commands below -accordingly. Note that even if \c{/usr/local/lib} is searched in at runtime, -you may still have to run \cb{ldconfig(1)} (as \c{root}) after the installation -to refresh the library cache. - -Note to Mac OS users: you will need version 10.5 (Leopard) or later. We will -also be using the system C++ toolchain that comes with the Xcode Command Line -Tools. To verify it is installed, run: - -\ -$ g++ --version -\ - -To install Command Line Tools, run: - -\ -$ xcode-select --install -\ +One of the primary goals of the \c{build2} toolchain is to provide a uniform +build interface across all the platforms and compilers. If you already have +the toolchain installed and would like to upgrade to a newer version, then +there is a single set of \l{#UPGRADE upgrade instructions} for all the +platforms. + +If, however, you need to install the toolchain for the first time, then it has +to be bootstrapped and that process is platform-specific. The rest of this +section discusses a few general bootstrap considerations and then directs +you to appropriate platform-specific instructions. + +The \c{build2} toolchain requires a C++14 compiler. From the commonly-used +options, GCC 4.8, Clang 3.4, and MSVC 2015/14 Update 2 or later +versions are known to work. Note also that the C++ compiler that you use to +build the \c{build2} toolchain and the one that you will use to build your +projects need not be the same. For example, if you are using MSVC 2013/12 +(which cannot build \c{build2}), it is perfectly fine to get a minimal +MinGW toolchain and use that to build \c{build2}; you will still be able +to use MSVC to build your own projects. + +At the high level, the bootstrap process involves the following 5 steps. \dl| -\li|1. Installing SQLite\n +\li|1. Bootstrap, Phase 1\n - Skip this step if you are only interested in the \c{build2} build system. +First, a minimal build system executable is built using provided shell +scripts/batch files. The result is only guaranteed to be able to rebuild the +build system itself.| - To install SQLite, use your distribution's package manager and make sure - you install both the libraries (most likely already installed) and the - development files. +\li|\n2. Bootstrap, Phase 2\n - For Debian/Ubuntu: +Then, the build system is rebuilt with static libraries. The result is only +guaranteed to be able to build the toolchain.| - \ - $ sudo apt-get install libsqlite3-dev - \ +\li|\n3. Stage\n - For RedHat/Fedora: +On this step the entire toolchain is built and staged.| - \ - $ sudo yum install sqlite-devel - \ +\li|\n4. Install\n - For FreeBSD: +Next, the staged toolchain is used to build and install the toolchain from +the package repository and using the \c{bpkg} package manager.| - \ - # pkg install sqlite3 - \ +\li|\n5. Clean\n - For Mac OS: +Finally, the staged toolchain is uninstalled.|| - You should already have a system-default version installed. To verify: +The end result of the bootstrap process is the installed toolchain as well as +the \c{bpkg} configuration (created on step 4) that can be used to upgrade to +newer versions. You can also skip step 4 and instead install on step 3 if +you would prefer not to use the package manager (for example, because the +machine is offline). - \ - $ ls /usr/include/sqlite3.h /usr/lib/libsqlite3.dylib - \ - To see which version you have, run: +For Windows, if using either MSVC or MinGW, continue with +\l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}. If using MSYS or Cygwin, +then instead refer to \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}. - \ - $ grep '#define SQLITE_VERSION' /usr/include/sqlite3.h - \ +For Mac OS X, continue with \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}. - Any recent version (i.e., greater than 3.5.0) should work. If for some - reason you don't seem to have SQLite, download the source code then build - and install it into \c{/usr/local}. - - | - -\li|\n2. Installing \c{libodb} and \c{libodb-sqlite}\n - - Again, skip this step if you are only interested in the \c{build2} build - system. - - [Currently we use pre-release versions of these libraries so they have to be - built from source.] - - Download source packages for the two libraries from the same location as - \l{https://download.build2.org \c{build2-toolchain}}. Then unpack, build, - and install: - - \ - $ cd lib*-X.Y.Z - - $ ./configure --prefix=/usr/local \ - CPPFLAGS=-I/usr/local/include \ - LDFLAGS=-L/usr/local/lib - - $ make - $ sudo make install - \ - - See the \c{INSTALL} file for each library for more information.| - -\li|\n3. Bootstrapping \c{build2}\n - - Download \l{https://download.build2.org \c{build2-toolchain}} then unpack - and bootstrap the \c{build2} build system: - - \ - $ cd build2-toolchain-X.Y.Z - $ cd build2/ - $ ./bootstrap - $ cd .. - $ ./build2/build2/b-boot build2/ - \ - - For more information on this step (for example, how to specify the C++ - compiler, options, etc.), refer to the \c{INSTALL} file in the \c{build2/} - subdirectory of \c{build2-toolchain}. Note that you must use global - overrides (\c{!}) if specifying any \c{config.*} variables on the last - line. For example: - - \ - $ ./build2/build2/b-boot '!config.cxx=clang++' build2/ - \ - - | - -\li|\n4. Configuring, Building, and Installing the Rest of the Toolchain\n - - \ - $ ./build2/build2/b \ - config.cxx.poptions=-I/usr/local/include \ - config.cxx.loptions=-L/usr/local/lib \ - config.bin.rpath=/usr/local/lib \ - config.install.root=/usr/local \ - config.install.root.sudo=sudo \ - configure - - $ ./build2/build2/b update - $ ./build2/build2/b install - \ - - To test the installation, run: - - \ - $ which b - /usr/local/bin/b - $ b --version - - $ which bpkg - /usr/local/bin/bpkg - $ bpkg --version - \ - - | - -\li|\n5. Setting up updates with the package manager\n - - If you only need to build this specific version of the toolchain, then you - are done and can skip this step. However, if you are planning to upgrade to - future versions, then going every time through the bootstrap steps will be - tedious. Instead, we can use the \c{bpkg} package manager to manage upgrades - automatically. Note also that without periodic upgrades your version of the - toolchain may become too old to be able to upgrade itself. In this case you - will have to fall back onto the bootstrap process. - - First, choose a directory where you would like \c{bpkg} to build everything, - for example, \c{build2-toolchain}. Then: - - \ - $ cd # back to home directory - $ mkdir build2-toolchain - $ cd build2-toolchain - - $ bpkg create \ - cxx \ - config.cxx.poptions=-I/usr/local/include \ - config.cxx.loptions=-L/usr/local/lib \ - config.bin.rpath=/usr/local/lib \ - config.install.root=/usr/local \ - config.install.root.sudo=sudo - - $ bpkg add https://pkg.cppget.org/1/alpha - $ bpkg fetch - $ bpkg build build2 bpkg - $ bpkg install build2 bpkg - \ - - Later, to upgrade to a new version of the toolchain, simply do: - - \ - $ bpkg fetch - $ bpkg status build2 bpkg # See if any upgrades are available. - $ bpkg build build2 bpkg - $ bpkg install build2 bpkg - \ - - || +For other UNIX-like operating systems (GNU/Linux, FreeBSD, etc; this also +includes MSYS/Cygwin), continue with \l{#BOOTSTRAP-UNIX Bootstrapping on +UNIX}. " diff --git a/UPGRADE.cli b/UPGRADE.cli new file mode 100644 index 0000000..5c07bf3 --- /dev/null +++ b/UPGRADE.cli @@ -0,0 +1,175 @@ +// file : UPGRADE.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +" +At this point we assume that you have the build2 toolchain installed and would +like to upgrade it to a newer version. We also expect that you have the +toolchain \c{bpkg} configuration in the \c{build2-toolchain} directory, as +produced by the bootstrap process. If you don't have the \c{bpkg} +configuration but do have the toolchain installed somehow (for example, using +your distribution's package manager), then you can create one as shown at the +end. If you have neither, then you will need to go through the bootstrap +process. + +There are two ways to upgrade: dirty (but quick) and staged (but more involved). In +the \i{dirty upgrade} we override the existing installation without first +uninstalling it. If some installed files no longer exist in the new version, +they will remain \"installed\" until cleaned up manually. Also, with this +approach we never get a chance to make sure the new build is functional. + +In the \i{staged upgrade} we first install a \c{-stage} build of the new +toolchain (similar to what we did during bootstrap), test it, uninstall the +old toolchain, install the new toolchain as non-staged, and finally uninstall +the \c{-stage} installation. + +We recommend that you use a dirty upgrade for a bugfix-only release (the same +\c{MAJOR.MINOR} version) and a staged upgrade otherwise. With bugfix-only +releases we guarantee not to alter the installation file set. Note also that +without periodic upgrades your version of the toolchain may become too old to +be able to upgrade itself. In this case you will have to fall back onto the +bootstrap process. + +The dirty upgrade is fairly simple: + +\ +$ cd build2-toolchain +$ bpkg fetch +$ bpkg build build2 bpkg +$ bpkg install build2 bpkg +\ + +You may also want to issue the \c{status} command after \c{fetch} to examine +which versions are available. By default \c{bpkg} will upgrade to the latest +available but you can override this by specifying the desired version +explicitly, for example: + +\ +$ bpkg status build2 bpkg +build2: configured 1.0.0; available 1.0.1 2.0.0 +bpkg: configured 1.0.0; available 1.0.1 2.0.0 +$ bpkg build build2/1.0.1 bpkg/1.0.1 +\ + +The staged upgrade consists of several steps: + +\dl| + +\li|1. Save Old Configuration\n + +First we make a copy of the old configuration. We will need it later to +cleanly uninstall the old toolchain. + +\ +$ rm -r build2-toolchain-old +$ cp -r build2-toolchain build2-toolchain-old +\ + +Or, using Windows command prompt: + +\ +> rmdir /s /q build2-toolchain-old +> xcopy /s /q /i build2-toolchain build2-toolchain-old +\ + +| + +\li|\n2. Build and Install as \c{-stage}\n + +This step is similar to the dirty upgrade except we install the toolchain with +the \c{-stage} suffix. + +\ +$ cd build2-toolchain +$ bpkg fetch +$ bpkg build build2 bpkg +$ bpkg install \ + config.bin.suffix=-stage \ + config.install.data_root=root/stage \ + build2 bpkg +\ + +| + +\li|\n3. Test Staged\n + +Now you can optionally test the new toolchain on your projects, etc. Remember +to use the \c{-stage}-suffixed binaries (\c{bpkg-stage} will automatically use +\c{b-stage}): + +\ +$ b-stage --version +$ bpkg-stage --version +\ + +| + +\li|\n4. Uninstall Old, Install New\n + +Once we are satisfied the new toolchain works, we can uninstall the old +one and install the new: + +\ +$ cd ../build2-toolchain-old +$ bpkg uninstall build2 bpkg + +$ cd ../build2-toolchain +$ bpkg-stage install build2 bpkg +\ + +| + +\li|\n5. Uninstall Staged\n + +Finally we clean up by removing the staged toolchain (hint: use command line +history to find the corresponding \cb{install} command change it to +uninstall): + +\ +$ bpkg uninstall \ + config.bin.suffix=-stage \ + config.install.data_root=root/stage \ + build2 bpkg +\ + +|| + +If you ever need to (re-)create the \c{bpkg} configuration for the toolchain +from scratch, it is fairly simple (you may need to adjust the compiler, +options, installation directory, etc): + +For UNIX-like operating systems (GNU/Linux, Mac OS X, FreeBSD, etc): + +\ +$ bpkg-stage create \ +cc \ +config.cxx=g++ \ +config.cc.coptions=-O3 \ +config.bin.lib=shared \ +config.bin.rpath=/usr/local/lib \ +config.install.root=/usr/local \ +config.install.sudo=sudo +\ + +For Windows with MSVC (from the Visual Studio command prompt): + +\ +> bpkg-stage create ^ + cc ^ + config.cxx=cl ^ + \"config.cc.coptions=/O2 /Oi\" ^ + config.bin.lib=shared ^ + config.install.root=C:\build2 +\ + +For Windows with MinGW (from the command prompt): + +\ +> bpkg-stage create ^ + cc ^ + config.cxx=g++ ^ + config.cc.coptions=-O3 ^ + config.bin.lib=shared ^ + config.install.root=C:\build2 +\ +" diff --git a/build/root.build b/build/root.build index ac55324..b21d615 100644 --- a/build/root.build +++ b/build/root.build @@ -5,6 +5,16 @@ # Load common modules that are used by subproject so that they use common # configuration. # -using cxx.config -using c.config -using? cli.config +using cxx +using c + +# Load the cli module but only if it's available. This way a distribution +# that includes pre-generated files can be built without installing cli. +# +using? cli + +if! $cli.configured +{ + define cli: file + cli{*}: extension = cli +} diff --git a/buildfile b/buildfile index 26b18e6..ccc2f78 100644 --- a/buildfile +++ b/buildfile @@ -3,10 +3,22 @@ # license : MIT; see accompanying LICENSE file d = libbutl/ build2/ libsqlite3/ libodb/ libodb-sqlite/ libbpkg/ bpkg/ doc/ -./: $d doc{INSTALL README version} file{INSTALL.cli} \ + +i = \ +INSTALL \ +UPGRADE \ +BOOTSTRAP-MACOSX \ +BOOTSTRAP-MINGW \ +BOOTSTRAP-MSVC \ +BOOTSTRAP-UNIX \ +BOOTSTRAP-WINDOWS + +./: $d doc{$i README version} cli{$i} \ file{build.sh build-msvc.bat build-mingw.bat} + include $d -# Don't install the INSTALL file. +# Don't install the BOOTSTRAP/INSTALL files. But UPGRADE could be useful. # doc{INSTALL}@./: install = false +doc{BOOTSTRAP-*}: install = false diff --git a/doc/.gitignore b/doc/.gitignore index 4bb8225..585f985 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,3 @@ -build2-toolchain-intro*.ps -build2-toolchain-intro*.pdf -build2-toolchain-intro.xhtml +build2-toolchain-*.ps +build2-toolchain-*.pdf +build2-toolchain-*.xhtml diff --git a/doc/buildfile b/doc/buildfile index fb23206..6914d41 100644 --- a/doc/buildfile +++ b/doc/buildfile @@ -5,12 +5,13 @@ define css: file css{*}: extension = css -./: doc{build2-toolchain-intro.xhtml \ - build2-toolchain-intro-a4.pdf \ - build2-toolchain-intro-a4.ps \ - build2-toolchain-intro-letter.pdf \ - build2-toolchain-intro-letter.ps} \ - css{code-box common doc pre-box toc} \ - file{a4.html2ps letter.html2ps doc.html2ps} \ - file{doc-prologue.xhtml doc-epilogue.xhtml \ - intro.cli cli.sh} +intr = build2-toolchain-intro +inst = build2-toolchain-install + +./: \ +doc{$(intr).xhtml $intr-a4.pdf $intr-a4.ps $intr-letter.pdf $intr-letter.ps} \ +doc{$(inst).xhtml $inst-a4.pdf $inst-a4.ps $inst-letter.pdf $inst-letter.ps} \ +css{code-box common doc pre-box toc} \ +file{a4.html2ps letter.html2ps doc.html2ps} \ +file{doc-prologue.xhtml doc-epilogue.xhtml} \ +cli{intro.cli install.cli} file{cli.sh} diff --git a/doc/cli.sh b/doc/cli.sh index c9a3c8e..a376fad 100755 --- a/doc/cli.sh +++ b/doc/cli.sh @@ -13,7 +13,9 @@ while [ $# -gt 0 ]; do case $1 in --clean) rm -f build2-toolchain-intro.xhtml build2-toolchain-intro*.ps \ -build2-toolchain-intro*.pdf + build2-toolchain-intro*.pdf + rm -f build2-toolchain-install.xhtml build2-toolchain-install*.ps \ +build2-toolchain-install*.pdf exit 0 ;; *) @@ -22,16 +24,42 @@ build2-toolchain-intro*.pdf esac done -cli -I .. -v version="$version" -v date="$date" \ +function gen () # +{ + local n="$1" + shift + cli -I .. -v version="$version" -v date="$date" \ --generate-html --html-suffix .xhtml \ --html-prologue-file doc-prologue.xhtml \ --html-epilogue-file doc-epilogue.xhtml \ ---link-regex '%b([-.].+)%../../build2/doc/b$1%' \ ---link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$1%' \ ---output-prefix build2-toolchain- intro.cli +--link-regex '%b([-.].+)%../../build2/doc/b$n%' \ +--link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$n%' \ +--output-prefix build2-toolchain- "${@}" $n.cli -html2ps -f doc.html2ps:a4.html2ps -o build2-toolchain-intro-a4.ps build2-toolchain-intro.xhtml -ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true build2-toolchain-intro-a4.ps build2-toolchain-intro-a4.pdf +html2ps -f doc.html2ps:a4.html2ps -o build2-toolchain-$n-a4.ps build2-toolchain-$n.xhtml +ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-a4.ps build2-toolchain-$n-a4.pdf -html2ps -f doc.html2ps:letter.html2ps -o build2-toolchain-intro-letter.ps build2-toolchain-intro.xhtml -ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-intro-letter.ps build2-toolchain-intro-letter.pdf +html2ps -f doc.html2ps:letter.html2ps -o build2-toolchain-$n-letter.ps build2-toolchain-$n.xhtml +ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-letter.ps build2-toolchain-$n-letter.pdf +} + +# Auto-heading doesn't work since it is broken into multiple doc strings. +# +gen install --html-heading-map 2=h2 +gen intro + +# Generate INSTALL/BOOTSTRAP/UPGRADE file in ../ +# +function gen_txt () # +{ + cli --generate-txt --omit-link-check --link-regex '%#(.*)%\1 file%' \ +-o .. --txt-suffix "" ../$1.cli +} + +gen_txt INSTALL +gen_txt UPGRADE +gen_txt BOOTSTRAP-MACOSX +gen_txt BOOTSTRAP-MINGW +gen_txt BOOTSTRAP-MSVC +gen_txt BOOTSTRAP-UNIX +gen_txt BOOTSTRAP-WINDOWS diff --git a/doc/install.cli b/doc/install.cli new file mode 100644 index 0000000..f8042f7 --- /dev/null +++ b/doc/install.cli @@ -0,0 +1,47 @@ +// file : doc/install.cli +// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +"\name=build2-toolchain-install" +"\subject=toolchain" +"\title=Toolchain Installation and Upgrade" + +// NOTES +// +// - Maximum 
 line is 70 characters.
+//
+
+"
+\h#INSTALL|Introduction|
+"
+source "../INSTALL.cli";
+
+"
+\h#BOOTSTRAP-WINDOWS|Bootstrapping on Windows|
+"
+source "../BOOTSTRAP-WINDOWS.cli";
+
+"
+\h2#BOOTSTRAP-MSVC|Bootstrapping with MSVC|
+"
+source "../BOOTSTRAP-MSVC.cli";
+
+"
+\h2#BOOTSTRAP-MINGW|Bootstrapping with MINGW|
+"
+source "../BOOTSTRAP-MINGW.cli";
+
+"
+\h#BOOTSTRAP-MACOSX|Bootstrapping on Mac OS X|
+"
+source "../BOOTSTRAP-MACOSX.cli";
+
+"
+\h#BOOTSTRAP-UNIX|Bootstrapping on UNIX|
+"
+source "../BOOTSTRAP-UNIX.cli";
+
+"
+\h#UPGRADE|Upgrading|
+"
+source "../UPGRADE.cli";
diff --git a/doc/intro.cli b/doc/intro.cli
index e9782a3..791394c 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -1039,8 +1039,3 @@ $ wine hello-1.0.0/hello.exe Windows
 Hello, Windows!
 \
 "
-
-"
-\h#install|Installation|
-"
-source "../INSTALL.cli";
-- 
cgit v1.1