diff options
Diffstat (limited to 'UPGRADE.cli')
| -rw-r--r-- | UPGRADE.cli | 91 |
1 files changed, 63 insertions, 28 deletions
diff --git a/UPGRADE.cli b/UPGRADE.cli index 7b15afd..f5fcc65 100644 --- a/UPGRADE.cli +++ b/UPGRADE.cli @@ -23,9 +23,9 @@ toolchain (similar to what we did during bootstrap), test it, uninstall the old toolchain, install the new toolchain as \"final\", and finally uninstall \c{-stage}. -We recommend that you use a dirty upgrade for patch releases with the same -\c{X.Y} (\c{MAJOR.MINOR}) version and a staged upgrade otherwise. With patch -releases we guarantee not to alter the installation file set. +We recommend that you use a dirty upgrade for toolchain patch releases with +the same \c{X.Y} (\c{MAJOR.MINOR}) version and a staged upgrade otherwise. +With patch releases we guarantee not to alter the installation file set. \N|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 @@ -37,31 +37,43 @@ Windows} for details). We recommend using the bootstrap process to upgrade these packages since all the straightforward upgrade sequences would lead to either the old toolchain using the new utilities or vice versa.| +\N|For both ways of upgrading we need to make sure that the build system +modules are built and installed with the new version of the toolchain. The set +of build system modules can also change from version to version.| + +\N|If using the Windows command prompt, the \c{!config.install.scope=project} +command line argument should not be quoted.| + The dirty upgrade is straightforward: \ $ cd build2-toolchain-X.Y +$ bpkg uninstall '!config.install.scope=project' \ + --all-pattern=libbuild2-* +$ bpkg drop --all-pattern=libbuild2-* $ bpkg fetch -$ bpkg build --for install -ur build2 bpkg bdep -$ bpkg install build2 bpkg bdep +$ bpkg build --for install -pr +$ bpkg install --all +$ bpkg build --for install libbuild2-autoconf libbuild2-kconfig +$ bpkg install '!config.install.scope=project' \ + --all-pattern=libbuild2-* \ -\N|The \c{-ur} options stands for \c{--upgrade} and \c{--recursive} \- upgrade -the listed packages and their dependencies, recursively. See -\l{bpkg-pkg-build(1)} for details.| +\N|The \c{-pr} options stands for \c{--patch} and \c{--recursive} \- upgrade +the built packages and their dependencies to the latest patch version, +recursively. See \l{bpkg-pkg-build(1)} for details.| -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: +You can also issue the \c{status} command after \c{fetch} to examine which +versions are available. The above \c{build} command will upgrade all the +packages to the latest available patch versions but you can override this by +specifying the desired packages and/or versions explicitly, for example: \ -$ bpkg status build2 bpkg bdep -!build2 configured 1.0.0 available 1.0.1 2.0.0 -!bpkg configured 1.0.0 available 1.0.1 2.0.0 -!bdep configured 1.0.0 available 1.0.1 2.0.0 +$ bpkg status +!build2 configured 1.0.0 available 1.0.1 1.0.2 2.0.0 +... -$ bpkg build --for install build2/1.0.1 bpkg/1.0.1 bdep/1.0.1 +$ bpkg build --for install build2/1.0.1 \ The staged upgrade consists of several steps: @@ -106,19 +118,33 @@ Or, using Windows command prompt: \li|\n\b{2. Build and Install as \c{-stage}}\n -This step is similar to the dirty upgrade except we use the copied -configuration and install the new toolchain with the \c{-stage} suffix: +This step is similar to the dirty upgrade except that we use the copied +configuration, upgrade (\c{--upgrade|-u}) instead of patching +(\c{--patch|-p}), and install the new toolchain with the \c{-stage} suffix: \ $ cd build2-toolchain-X.Z -$ bpkg build --for install -ur build2 bpkg bdep +$ bpkg drop --all-pattern=libbuild2-* +$ bpkg build --for install -ur +\ + +Once this is done, we can proceed to installing: + +\ $ bpkg install \ config.bin.suffix=-stage \ config.install.data_root=root/stage \ - build2 bpkg bdep + --all \ -| +\N|If during installation you have added a custom prefix/suffix to the +toolchain executables names with \c{config.bin.exe.prefix} and/or +\c{config.bin.exe.suffix}, add \c{config.bin.exe.prefix=[null]} and/or +\c{config.bin.exe.suffix=[null]} to suppress them in the executables being +staged.| + +You can also specify the desired packages and/or versions explicitly, again, +similar to the dirty upgrade.| \li|\n\b{3. Test Staged}\n @@ -141,10 +167,13 @@ one and install the new one: \ $ cd ../build2-toolchain-X.Y -$ bpkg uninstall build2 bpkg bdep +$ bpkg uninstall --all $ cd ../build2-toolchain-X.Z -$ bpkg-stage install build2 bpkg bdep +$ bpkg-stage install --all +$ bpkg build --for install libbuild2-autoconf libbuild2-kconfig +$ bpkg install '!config.install.scope=project' \ + --all-pattern=libbuild2-* \ | @@ -153,13 +182,14 @@ $ bpkg-stage install build2 bpkg bdep Finally, we clean up by removing the staged toolchain (hint: use the command line history to find the corresponding \c{install} command and change it to -\c{uninstall}): +\c{uninstall}; see also a note at step 2 about toolchain executables +prefix/suffix): \ $ bpkg uninstall \ config.bin.suffix=-stage \ config.install.data_root=root/stage \ - build2 bpkg bdep + --all \ You can also remove the old configuration in \c{build2-toolchain-X.Y/} if you @@ -176,11 +206,13 @@ For UNIX-like operating systems (GNU/Linux, Mac OS X, FreeBSD, etc): \ $ bpkg-stage create \ cc \ +config.config.hermetic=true \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.bin.lib=shared \ config.bin.rpath=/usr/local/lib \ config.install.root=/usr/local \ +config.install.private=build2 \ config.install.sudo=sudo \ @@ -190,6 +222,7 @@ Prompt\"): \ > bpkg-stage create ^ cc ^ + config.config.hermetic=true ^ config.cxx=cl ^ config.cc.coptions=/O2 ^ config.bin.lib=shared ^ @@ -202,8 +235,9 @@ For Windows with Clang (from a suitable command prompt, see \ > bpkg-stage create ^ cc ^ - config.cxx=clang++ ^ - \"config.cc.coptions=-m64 -O2\" ^ + config.config.hermetic=true ^ + \"config.cxx=clang++ -m64\" ^ + config.cc.coptions=-O2 ^ config.bin.lib=shared ^ config.install.root=C:\build2 \ @@ -213,6 +247,7 @@ For Windows with MinGW (from the command prompt): \ > bpkg-stage create ^ cc ^ + config.config.hermetic=true ^ config.cxx=g++ ^ config.cc.coptions=-O3 ^ config.bin.lib=shared ^ |