aboutsummaryrefslogtreecommitdiff
path: root/INSTALL.cli
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.cli')
-rw-r--r--INSTALL.cli234
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}.
"