diff options
Diffstat (limited to 'INSTALL.cli')
| -rw-r--r-- | INSTALL.cli | 234 |
1 files changed, 47 insertions, 187 deletions
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}. " |