aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2016-09-03 17:27:33 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2016-09-03 17:27:33 +0200
commit879d7e92d823c9dfe6fb3691541f30b662f2a510 (patch)
tree7b4705029c81f2b5decc16cc63cfc1a88e5c7ff3
parent8622308eefe9a1d63bb4128548260d0ba3d50d7a (diff)
First take on new installation and upgrade instructions
-rw-r--r--.gitignore4
-rw-r--r--BOOTSTRAP-MACOSX.cli30
-rw-r--r--BOOTSTRAP-MINGW.cli27
-rw-r--r--BOOTSTRAP-MSVC.cli29
-rw-r--r--BOOTSTRAP-UNIX.cli80
-rw-r--r--BOOTSTRAP-WINDOWS.cli136
-rw-r--r--INSTALL164
-rw-r--r--INSTALL.cli234
-rw-r--r--UPGRADE.cli175
-rw-r--r--build/root.build16
-rw-r--r--buildfile16
-rw-r--r--doc/.gitignore6
-rw-r--r--doc/buildfile19
-rwxr-xr-xdoc/cli.sh46
-rw-r--r--doc/install.cli47
-rw-r--r--doc/intro.cli5
16 files changed, 652 insertions, 382 deletions
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{<arch>} 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-<arch>.zip
+build2-mingw-X.Y.Z-<arch>.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-<arch>.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-<arch>.tar.xz} archive into
+\c{C:\\build2\\}:
+
+\
+> tar xf build2-mingw-X.Y.Z-<arch>-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 () # <name>
+{
+ 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 () # <name>
+{
+ 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 <pre> 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";