% TERMINAL SETUP:
%
% PS1="\\W/$ "
% alias l=ls
% alias t=tree
%
% cd /tmp
% rm -rf /tmp/hello* /tmp/example && cp -r .../example /tmp/
% sudo rm -r /usr/include/hello /usr/lib/x86_64-linux-gnu/libhello.*
% clear
%

% TERMINAL repo-web-interface
%
% firefor https://cppget.org
% firefox https://build2.org/pkg/hello

% TERMINAL package-manager-usage
%
% cd /tmp/
% mkdir hello-gcc5-release
% cd hello-gcc5-release/
% bpkg create cxx config.cxx=g++-5 config.cxx.coptions=-O3
% t
%
% bpkg add https://build2.org/pkg/1/hello/stable
% bpkg fetch
% bpkg status hello
% bpkg build hello
%
% bpkg clean hello
% bpkg update hello -v
%
% bpkg add https://build2.org/pkg/1/hello/testing
% bpkg fetch
% bpkg status libhello
% bpkg build libhello
% bpkg update hello
%
% bpkg build libhello/1.0.1
% bpkg update hello
%
% t
%
% bpkg help
%
% bpkg install config.install.root=/tmp/install hello
% t /tmp/install
% /tmp/install/bin/hello
%
% bpkg install config.install.root=/tmp/install \
%   config.bin.rpath=/tmp/install/lib hello
% /tmp/install/bin/hello
%

% TERMINAL examine-manifest
%
% What makes a package? Well, first of all it must use the
% build2 build system. Other than that, it should include a
% manifest file which describes the package.
%
% cd hello-1.0.1/
% t
% edit manifest
%

% TERMINAL build-system-usage
%
% cd .../hello/
% l
%
% cd hello/
% t
%
% edit buildfile
%
% cd build/
% edit bootstrap.build
% edit root.build
%
% cd ..
% b                    # fail: config.import.libhello
%
% cd ../libhello
% t
%
% edit hello/buildfile
%
% b                    # all good
% t
%
% ../hello
% b config.import.libhello=../libhello
% ./hello
% ./hello C++Now

% TERMINAL persistent-configuration
%
% b                                              # fail
% b config.import.libhello=../libhello           # ok
% b config.import.libhello=../libhello configure
% edit build/config.build
% b config.import.libhello=../libhello config.cxx=g++-5 configure
% edit build/config.build
% b
%
% cd ../libhello
% b config.cxx=g++-5 configure
% b

% TERMINAL out-of-source-builds
%
% cd ..
% l
%
% b config.cxx=clang++ 'configure(libhello/@libhello-clang/)'
%
% b config.cxx=clang++ config.import.libhello=libhello-clang/ \
%  'configure(hello/@hello-clang/)'
%
% b hello-clang/ -v
% hello-clang/hello
%
% b config.cxx=g++ config.import.libhello=libhello-gcc/ \
%   'configure(libhello/@libhello-gcc/ hello/@hello-gcc/)'
%
% cd hello-gcc/
% b -v
% ./hello
% cd ..
%
% l
%

% TERMINAL multi-config-build
%
% The result is that build2 projects can't step on each
% other's toes. And we can build independent projects or even
% multiple configurations of the same project at once.
%
% cd example/
% b 'clean(hello-gcc/ hello-clang/)'
% b hello-gcc/ hello-clang/ -v

% TERMINAL var-override
%
% Override scope: by default the override only affects the
% project being built and its subprojects. But not imported
% projects.
%
% b 'clean(libhello-gcc/)'
% cd hello-gcc/
% b config.cxx=clang++ -v
%
% As you can see, gcc is still used to build libhello/
%
% We can make the override global by prefixing it with the
% bang:
%
% b '!config.cxx=clang++' -v
%
% As you can see, even libhello/ is being rebuild with clang.
% It is also possible to restrict an override to a specific
% directory scope. For example, we may only want to rebuild
% tests with clang:
%
% b tests/:config.cxx=clang++
%
% Did anyone notice something odd? How does build2 know to
% update what exactly was affected by our overrides?

% TERMINAL "examine-dot-d"
%
% cd hello
% less hello.o.d # DONT talk about rule name/version
%

% TERMINAL "compiler-checksum"
%
% Let's talk a bit about how we calculate the compiler checksum.
% This is done in a compiler-specific way with the goal to
% capture as much information as possible. For example, for
% gcc/clang this is done by hashing the -v output:
%
% g++ -v
%

% TERMINAL "hfb-example"
%
% Let's see an example of high fidelity builds and command
% line overrides. Say our hello program dumps core and we want
% to re-build it with debug info so that we can analyze the stack
% trace:
%
% cd hello/
% b # everything is up-to-date
% b config.cxx.coptions+=-g -v
%
% Say the stack trace leads to libhello (which wasn't affected by
% the above override). So it seems we will have to rebuild
% everything with debug info:
%
% b '!config.cxx.coptions+=-g' -v
%
% Say we fixed our bug and would like to revert to our original
% build. All we have to do is to remove the override:
%
% b -v

% TERMINAL compiler-detection
%
% cd ../libhello
% b disfigure
% b config.cxx=g++-5 configure -v
%
% b config.cxx=clang++ configure -v
%
% b config.cxx=clang++ configure -v config.cxx.coptions=-m32
%
% b disfigure
% b config.cxx=g++ configure
%

% TERMINAL cross-compilation
%
% So as I said in build2 cross-compilation is nothing special.
% Remember we setup gcc and clang builds of our example:
%
% l
%
% Those were native builds. Let's now add a Windows build using
% the MinGW cross-compiler:
%
% b config.cxx=i686-w64-mingw32-g++ \
%   config.bin.ar=i686-w64-mingw32-ar \
%   config.cxx.loptions=-static \
%   config.bin.lib=static \
%   config.import.libhello=libhello-mingw-gcc/ \
%   'configure(libhello/@libhello-mingw-gcc/ hello/@hello-mingw-gcc/)' \
%   -v
%
% l
%
% b hello-mingw-gcc/
%
% hello-mingw-gcc/hello.exe Windows

% TERMINAL install-libhello
%
% cd libhello
% b clean
%
% b install config.install.root=/usr \
%           config.install.lib=root/lib/x86_64-linux-gnu \
%           config.install.root.sudo=sudo
%
% l /usr/include/hello/hello
% l /usr/lib/x86_64-linux-gnu/libhello*
%
% re-run with -v to see what's called with sudo

% TERMINAL import-installed
%
% Let's see how it all works on importing libhello which we
% just installed. Rememer we used that multiarch library
% location? I did that on purpose: make would never find it
% there. Let's see if build2 will.
%
% cd hello
% b clean disfigure
%
% Remember we used to get that import error if we tried to
% build hello without specifying where libhello is? Let's see
% if that changes now seeing that we have libhello installed.
%
% b configure
% b -v
%

% TERMINAL libhello-subproject
%
% l
% b '{clean disfigure}(hello/ libhello/)'
% cp -r hello/ hello-amalgam/
% cp -r libhello/ hello-amalgam/
% t hello-amalgam/
%
% cd hello-amalgam/
% b configure config.cxx=clang++ # notice both got configured
%
% edit libhello/build/config.build
%
% b configure config.cxx=clang++ \
%   libhello/:config.cxx.coptions+=-O3
%
% edit libhello/build/config.build
%
% b -v
%

% TERMINAL examine-bpkg-configuration
%
% cd /tmp/hello-gcc5-release
% t -L 2
% edit build/config.build
% ^-R bpkg create
%