diff options
Diffstat (limited to 'UPGRADE.cli')
| -rw-r--r-- | UPGRADE.cli | 175 |
1 files changed, 175 insertions, 0 deletions
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 +\ +" |