Rename intro2 to intro, old intro to intro1

1 files changed, 1169 insertions, 0 deletions

diff --git a/doc/intro1.cli b/doc/intro1.cli
new file mode 100644
index 0000000..f53544d
--- /dev/null
+++ b/doc/intro1.cli
@@ -0,0 +1,1169 @@
+// file      : doc/intro1.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+"\name=build2-toolchain-intro"
+"\subject=toolchain"
+"\title=Toolchain Introduction"
+
+// TODO
+//
+// @@ refs to further docs
+//
+// STYLE
+//
+// @@ section boundary page breaks (<hr class="page-break"/>)
+// @@ when printed, code background is gone, but spaces still there
+//
+// PDF
+//
+// @@ tree output is garbled
+// @@ Install list margins missing
+// @@ Could we use a nicer font, seeing that we embed them?
+//
+
+// NOTES
+//
+// - Maximum <pre> line is 70 characters.
+//
+
+"
+\h#tldr|TL;DR|
+
+\
+$ bpkg create -d hello cc
+created new configuration in hello/
+
+$ cd hello/
+$ bpkg add https://build2.org/pkg/1/hello/stable
+added repository build2.org/hello/stable
+
+$ bpkg fetch
+fetching build2.org/hello/stable
+2 package(s) in 1 repository(s)
+
+$ bpkg build hello
+  build libhello/1.0.0 (required by hello)
+  build hello/1.0.0
+continue? [Y/n] y
+
+libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
+fetched libhello/1.0.0
+unpacked libhello/1.0.0
+
+hello-1.0.0.tar.gz           100% of 1057  B 6882 kBps 00m01s
+fetched hello/1.0.0
+unpacked hello/1.0.0
+
+configured libhello/1.0.0
+configured hello/1.0.0
+
+c++ hello-1.0.0/cxx{hello}
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/libs{hello}
+ld hello-1.0.0/exe{hello}
+
+updated hello/1.0.0
+\
+"
+
+"
+\h#warning|Warning|
+
+The \c{build2} toolchain \c{0.X.Y} series are alpha releases. Interfaces
+\i{will} most likely change in backwards-incompatible ways. But if you want
+to start playing with it, welcome and join the \l{https://lists.build2.org
+mailing list}!
+
+Our approach to developing \c{build2} is to first get the hard parts right
+before focusing on completeness. So while we might still have no support for
+custom build rules, we do handle auto-generated source code (and, in
+particular, headers) properly. In other words, we go depth rather than
+breadth-first. As a result, there are some limitations and missing pieces,
+especially in the build system. The most notable ones are:
+
+\ul|
+
+\li|Limited documentation.|
+
+\li|No support for custom build system rules/modules.|
+
+|
+"
+
+"
+\h#intro|Introduction|
+
+The \c{build2} toolchain is a set of tools designed for building and packaging
+C and C++ code (though, if it can handle C++, it can handle anything,
+right?). The toolchain currently includes the \i{build system} (\c{build2}),
+the \i{package manager} (\c{bpkg}), and the \i{repository web interface}
+(\c{brep}). More tools, such as the \i{build robot} (\c{bbot}), are in the
+works. Then there is \l{https://cppget.org/ cppget.org} (running \c{brep})
+which we hope will become \i{the C++ package repository}.
+
+The goal of this document is to give you a basic idea of what the \c{build2}
+toolchain can do so that you can decide if you are interested and want to learn
+more. Further documentation is referenced at the end of this introduction.
+
+The \c{build2} toolchain is self-hosted and self-packaged (and, yes, it is on
+\l{https://cppget.org/ cppget.org}). It could have served as its own example,
+however, before the toolchain can build itself, we have to bootstrap it (that
+chicken and egg problem again). And this step wouldn't serve our goal of
+quickly learning what \c{build2} is about. So, instead, we will start with a
+customary \i{\"Hello, World!\"} example which you won't yet be able to try
+yourself (but don't worry, complete terminal output will be shown). If at the
+end you find \c{build2} appealing, you can jump straight to
+\l{build2-toolchain-install.xhtml The \c{build2} Toolchain Installation and
+Upgrade} (and, yes, there you get to run that coveted \c{bpkg build bpkg}).
+Once the \c{build2} installation is complete, you can come back to the
+\i{\"Hello, World!\"} example and try all of the steps for yourself.
+
+This introduction explores the \i{consumer} side of \i{\"Hello, World!\"}.
+That is, we assume that someone was kind enough to create and package the
+\c{libhello} library as well as the \c{hello} program and we will learn how to
+obtain and build them as well as keep up with their updates. At the end we
+will also see how to write our own, \c{hello2}, program that depends on
+\c{libhello}.  And so, without further ado, let's begin.
+
+Actually, one more thing: if you have a recent enough compiler and would like
+to try the new C++ Modules support, then you can instead use the modularized
+variants of these packages: simply replace \c{hello} with \c{mhello} and
+\c{libhello} with \c{libmhello} in the commands below.
+
+The first step in using \c{bpkg} is to create a \i{configuration}. A
+configuration is a directory where packages that require similar compile
+settings will be built. You can create as many configurations as you want: for
+different C++ compilers, targets (\c{build2} is big on cross-compiling),
+debug/release, 32/64-bit, or even for different days of the week, if you are
+so inclined. Say we are in the mood for a GCC 5 release build today:
+
+\
+$ mkdir hello-gcc5-release
+$ cd hello-gcc5-release
+$ bpkg create cxx config.cxx=g++-5 config.cxx.coptions=-O3
+created new configuration in /tmp/hello-gcc5-release/
+\
+
+Or perhaps you are on Windows and prefer Visual Studio (running from the
+Visual Studio Tools Command Prompt):
+
+\
+> mkdir hello-vc14-release
+> cd hello-vc14-release
+> bpkg create cxx config.cxx=cl config.cxx.coptions=/O2
+created new configuration in C:\projects\hello-vc14-release\
+\
+
+One of the primary goals of the \c{build2} toolchain is to provide a uniform
+build interface across all the platforms and compilers. While the following
+examples use the \c{hello-gcc5-release} configuration and assume a UNIX-like
+operation system, everything will work if you use \c{hello-vc14-release} (or
+\c{hello-mingw-release}) on Windows. Just use appropriate paths, compilers,
+and options.
+
+Let's discuss that last command line: \l{bpkg-cfg-create(1) \c{bpkg create}}
+is the command for creating a new configuration. As a side note, if you ever
+want to get help for any \c{bpkg} command, run \c{bpkg help \i{<command>}}. To
+see the list of commands, run just \l{bpkg-help(1) \c{bpkg help}} (or see
+\l{bpkg(1)}). While we are at it, if you ever want to see what \c{bpkg} is
+running underneath, there is the \c{-v} (essential commands) and \c{-V} (all
+commands) options. And if you really want to get under the hood, use
+\l{bpkg-common-options(1) \c{--verbose <level>}}.
+
+After the command we have \c{cxx} which is the name of the \c{build2} build
+system module. As you might have guessed, \c{cxx} provides support for the C++
+compilation. By specifying this module when creating the configuration we
+configure it (yes, with those \c{config.cxx.*} variables that follow) for the
+entire configuration. That is, every package that we will build in this
+configuration and that uses the \c{cxx} module will by default inherit these
+settings.
+
+The rest of the command line are the configuration variables for the \c{cxx}
+module with \c{coptions} standing for \i{compile options} (there are also
+\c{poptions} for \i{preprocess options}, \c{loptions} for \i{link options}, and
+\c{libs} for extra libraries to link).
+
+There is also the \c{c} module for the C compilation. So if we were planning
+to build both C and C++ projects, then we could have run:
+
+\
+$ bpkg create c cxx ...
+\
+
+The problem, of course, is that you may not know what mix of languages those
+projects (or their dependencies) might use. For example, the use of C might be
+an implementation detail of a C++ library. To solve this, \c{build2} provides
+another module called \c{cc} which stands for \i{C-common}. So, in this
+context, instead of using the \c{c} and \c{cxx} modules directly, it's a good
+idea to get into the habit of using \c{cc}:
+
+\
+$ bpkg create cc config.cxx=g++-5 config.cc.coptions=-O3
+\
+
+Notice two things about this command line: we don't need to specify the C
+compiler with \c{config.c} \- \c{build2} is smart enough to figure it out
+from \c{config.cxx} (or vice versa). We also used \c{config.cc.coptions}
+instead of \c{config.cxx.coptions} so that the options apply to all the
+C-common languages (we can still use \c{config.{c,cxx\}.*} for the
+language-specific options).
+
+Ok, configuration in hand, where can we get some packages? \c{bpkg} packages
+come from \i{repositories}. A repository can be a local filesystem directory
+or a remote URL. Our example packages come from their own remote \i{\"Hello,
+World!\"} repository: \c{\l{https://build2.org/pkg/1/hello/stable/}} (go ahead,
+browse it, I will wait).
+
+Instead of scouring repository manifests by hand (I know you couldn't resist),
+we can ask \c{bpkg} to interrogate a repository location for us:
+
+\
+$ bpkg rep-info https://build2.org/pkg/1/hello/stable
+warning: authenticity of the certificate for repository build2.org/hello/stable cannot be established
+certificate is for build2.org, \"Code Synthesis\" <admin@build2.org>
+certificate SHA256 fingerprint:
+FF:DF:7D:38:67:4E:C3:82:[...]:30:56:B9:77:B9:F2:01:94
+trust this certificate? [y/n]
+\
+
+The \c{bpkg} repositories are normally signed to prevent tampering with
+packages. If the repository certificate is seen (in this configuration) for
+the first time, \c{bpkg} will ask you to authenticate it. A good way to
+authenticate a certificate is to compare the displayed fingerprint to the one
+you have received earlier, for example, in an email announcement. The
+repository's about page also lists the fingerprint (see the
+\l{https://build2.org/pkg/hello/?about about page} for our repository). For
+more details on repository signing see the \l{bpkg-repository-signing(1)} help
+topic.
+
+If we answer \i{yes}, we will see the basic repository information (its
+\i{canonical name}, location, certificate subject and fingerprint) followed
+by the list of available packages:
+
+\
+build2.org/hello/stable https://build2.org/pkg/1/hello/stable
+CN=build2.org/O=Code Synthesis/admin@build2.org
+FF:DF:7D:38:67:4E:C3:82:[...]:30:56:B9:77:B9:F2:01:94
+
+hello/1.0.0
+libhello/1.0.0
+\
+
+We can also use the repository's web interface (implemented by \c{brep}). Our
+repository has one, check it out: \c{\l{https://build2.org/pkg/hello/}}.
+
+Ok, back to the command line. If we want to use a repository as a source of
+packages in our configuration, we have to first add it:
+
+\
+$ bpkg add https://build2.org/pkg/1/hello/stable
+added repository build2.org/hello/stable
+\
+
+If we want to add several repositories, we just execute the \l{bpkg-rep-add(1)
+\c{bpkg add}} command for each of them. Once this is done, we fetch the list of
+available packages for all the added repositories:
+
+\
+$ bpkg fetch
+fetching build2.org/hello/stable
+2 package(s) in 1 repository(s)
+\
+
+Note that you would normally re-run the \l{bpkg-rep-fetch(1) \c{bpkg fetch}}
+command after you've added another repository or to refresh the list of
+available packages.
+
+Now that \c{bpkg} knows where to get the packages, we can finally get down to
+business:
+
+\
+$ bpkg build hello
+  build libhello/1.0.0 (required by hello)
+  build hello/1.0.0
+continue? [Y/n]
+\
+
+Let's see what's going on here. We ran \l{bpkg-pkg-build(1) \c{bpkg build}} to
+build the \c{hello} program which happens to depend on the \c{libhello}
+library. So \c{bpkg} presents us with a \i{plan of action}, that is, the steps
+it will have to perform in order to build us \c{hello} and then asks us to
+confirm if that's what we want to do (you can add \c{--yes|-y} to skip the
+confirmation). In the real-world usage the plan will be more complex, with
+upgrades/downgrades, reconfigurations, etc.
+
+Let's answer \i{yes} and see what happens:
+
+\
+libhello-1.0.0.tar.gz        100% of 2428  B 1364 kBps 00m01s
+fetched libhello/1.0.0
+unpacked libhello/1.0.0
+hello-1.0.0.tar.gz           100% of 1057  B   20 MBps 00m01s
+fetched hello/1.0.0
+unpacked hello/1.0.0
+configured libhello/1.0.0
+configured hello/1.0.0
+c++ hello-1.0.0/cxx{hello}
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/libs{hello}
+ld hello-1.0.0/exe{hello}
+updated hello/1.0.0
+\
+
+While the output is mostly self-explanatory, in short, \c{bpkg} downloaded,
+unpacked, and configured both packages and then proceeded to building the
+\c{hello} executable which happens to require building the \c{libhello}
+library. Note that the download progress may look differently on your machine
+depending on which \i{fetch tool} (\c{wget}, \c{curl}, or \c{fetch}) is
+used. If you ever considered giving that \c{-v} option a try, now would be a
+good time. But let's first drop (\l{bpkg-pkg-drop(1) \c{bpkg drop}}) the
+\c{hello} package so that we get the same build from scratch:
+
+\
+$ bpkg drop hello
+following prerequisite packages were automatically built and will no longer be necessary:
+  libhello
+drop prerequisite packages? [Y/n] y
+  drop hello
+  drop libhello
+continue? [Y/n] y
+disfigured hello
+disfigured libhello
+purged hello
+purged libhello
+\
+
+Ok, ready for some \c{-v} details? Feel free to skip the following listing
+if you are not interested.
+
+\
+$ bpkg build -v -y hello
+fetching libhello-1.0.0.tar.gz from build2.org/hello/stable
+curl ... https://build2.org/pkg/1/hello/stable/libhello-1.0.0.tar.gz
+  % Total    % Received Average Speed   Time    Time     Time  Current
+                        Dload  Upload   Total   Spent    Left  Speed
+100  2428  100  2428      1121      0  0:00:01  0:00:01 --:--:--  1122
+fetched libhello/1.0.0
+tar -xf libhello-1.0.0.tar.gz
+unpacked libhello/1.0.0
+fetching hello-1.0.0.tar.gz from build2.org/hello/stable
+curl ... https://build2.org/pkg/1/hello/stable/hello-1.0.0.tar.gz
+  % Total    % Received Average Speed   Time    Time     Time  Current
+                        Dload  Upload   Total   Spent    Left  Speed
+100  1057  100  1057      773      0  0:00:01  0:00:01 --:--:--   772
+fetched hello/1.0.0
+tar -xf hello-1.0.0.tar.gz
+unpacked hello/1.0.0
+b -v configure(./libhello-1.0.0/)
+cat >libhello-1.0.0/build/config.build
+configured libhello/1.0.0
+b -v configure(./hello-1.0.0/)
+cat >hello-1.0.0/build/config.build
+configured hello/1.0.0
+hold package hello
+b -v update(./hello-1.0.0/)
+g++-5 -I libhello-1.0.0 -O3 -std=c++11 -o hello-1.0.0/hello.o -c hello-1.0.0/hello.cxx
+g++-5 -I libhello-1.0.0 -O3 -std=c++11 -fPIC -o libhello-1.0.0/hello/hello.so.o -c libhello-1.0.0/hello/hello.cxx
+g++-5 -O3 -std=c++11 -shared -o libhello-1.0.0/hello/libhello-1.0.so libhello-1.0.0/hello/hello.so.o
+g++-5 -O3 -std=c++11 -o hello-1.0.0/hello hello-1.0.0/hello.o libhello-1.0.0/hello/libhello-1.0.so
+updated hello/1.0.0
+\
+
+Another handy command is \l{bpkg-pkg-status(1) \c{bpkg status}}. It can be
+used to examine the state of a package in the configuration. Here are a few
+examples (if you absolutely must know what \c{hold_package} and \c{sys:?}
+mean, check \l{bpkg-pkg-status(1)}):
+
+\
+$ bpkg status libhello
+configured 1.0.0; available sys:?
+
+$ bpkg status hello
+configured 1.0.0 hold_package; available sys:?
+
+$ bpkg drop -y hello
+disfigured hello
+disfigured libhello
+purged hello
+purged libhello
+
+$ bpkg status hello
+available 1.0.0 sys:?
+
+$ bpkg status libfoobar
+unknown
+\
+
+Let's say we got wind of a new development: the \c{libhello} author released a
+new version of the library. It is such an advance in the art of \i{\"Hello,
+World!\"}, it's only currently available from \c{testing}. Of course, we must
+check it out.
+
+Now, what exactly is \c{testing}? You must have noticed that the repository
+location that we've been using so far ended with \c{/stable}. Quite often it is
+useful to split our repository into sub-repositories or \i{sections}. For
+example, to reflect the maturity of packages (say, \c{stable} and \c{testing},
+as in our case) or to divide them into sub-categories (\c{misc} and \c{math})
+or even some combination (\c{math/testing}). Note, however, that to \c{bpkg}
+these sub-repositories or \i{sections} are just normal repositories and there
+is nothing special about them.
+
+We are impatient to try the new version so we will skip interrogating the
+repository with \c{rep-info} and just add it to our configuration. After all,
+we can always check with \c{status} if any upgrades are available for packages
+we are interested in. Here we assume the configuration has \c{hello} built (run
+\c{bpkg build -y hello} to get to that state).
+
+\
+$ bpkg add https://build2.org/pkg/1/hello/testing
+added repository build2.org/hello/testing
+
+$ bpkg fetch
+fetching build2.org/hello/stable
+fetching build2.org/hello/testing
+5 package(s) in 2 repository(s)
+\
+
+Notice that this time we don't see any authentication-related messages or
+prompts since \c{bpkg} remembered (in this configuration) that we trust the
+certificate (\c{testing} naturally uses the same one as \c{stable}).
+
+Let's see what's new:
+
+\
+$ bpkg status libhello
+configured 1.0.0; available 1.1.0 sys:?
+\
+
+Ok, \c{libhello/1.1.0} is now available. How do we upgrade? We can try to
+build \c{hello} again:
+
+\
+$ bpkg build -y hello
+info: dir{hello-1.0.0/} is up to date
+updated hello/1.0.0
+\
+
+Why did nothing happen? Because \c{bpkg} will only upgrade (or downgrade)
+to a new version if we explicitly ask it to. As things stand, all dependencies
+for \c{hello} are satisfied and \c{bpkg} is happy to twiddle its thumbs. Let's
+tell \c{bpkg} to build us \c{libhello} instead:
+
+\
+$ bpkg build libhello
+  build libformat/1.0.0 (required by libhello)
+  build libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  reconfigure hello (dependent of libhello)
+continue? [Y/n]
+\
+
+Ok, now we are getting somewhere. It looks like the new version of \c{libhello}
+went really enterprise-grade (or is it called web-scale these days?). There are
+now two new dependencies (\c{libformat} and \c{libprint}) that we will have to
+build in order to upgrade. Maybe we should answer \i{no} here?
+
+Notice also that \c{reconfigure hello} line. If you think about this, it makes
+sense: we are getting a new version of \c{libhello} and \c{hello} depends on it
+so it might need a chance to make some adjustments to its configuration.
+
+Let's answer \i{yes} if only to see what happens:
+
+\
+update dependent packages? [Y/n]
+\
+
+Another question. This one has to do with that \c{reconfigure hello} line we
+just talked about. If you were wondering why we were only offered to
+reconfigure and not actually update the dependent package, you should know
+that \c{bpkg} is a very lazy package manager, it only does what it must do,
+not what might be nice to do. It must reconfigure but it doesn't really have
+to update. And this could be a good thing if, for example, you have a hundred
+dependents in your configuration but right now you only want to build just
+those specific packages. However, quite often, you do want to keep all the
+packages in your configuration up to date and \c{bpkg} graciously offers to
+take care of this task. Ok, let's answer \i{yes} again:
+
+\
+...
+update dependent packages? [Y/n] y
+disfigured hello/1.0.0
+disfigured libhello/1.0.0
+libformat-1.0.0.tar.gz       100% of 1064  B   11 MBps 00m01s
+fetched libformat/1.0.0
+unpacked libformat/1.0.0
+libprint-1.0.0.tar.gz        100% of 1040  B    9 MBps 00m01s
+fetched libprint/1.0.0
+unpacked libprint/1.0.0
+libhello-1.1.0.tar.gz        100% of 1564  B 4672 kBps 00m01s
+fetched libhello/1.1.0
+unpacked libhello/1.1.0
+configured libformat/1.0.0
+configured libprint/1.0.0
+configured libhello/1.1.0
+configured hello/1.0.0
+c++ libhello-1.1.0/hello/cxx{hello}
+c++ libformat-1.0.0/format/cxx{format}
+ld libformat-1.0.0/format/liba{format}
+c++ libprint-1.0.0/print/cxx{print}
+ld libprint-1.0.0/print/liba{print}
+ld libhello-1.1.0/hello/liba{hello}
+c++ libhello-1.1.0/hello/cxx{hello}
+c++ libformat-1.0.0/format/cxx{format}
+ld libformat-1.0.0/format/libs{format}
+c++ libprint-1.0.0/print/cxx{print}
+ld libprint-1.0.0/print/libs{print}
+ld libhello-1.1.0/hello/libs{hello}
+c++ libhello-1.1.0/tests/test/cxx{driver}
+ld libhello-1.1.0/tests/test/exe{driver}
+c++ hello-1.0.0/cxx{hello}
+ld hello-1.0.0/exe{hello}
+updated libhello/1.1.0
+updated hello/1.0.0
+\
+
+A lot of output but nothing really new. If you were to answer \i{no} to the
+\"update dependent packages?\" question above, it is easy to make sure a
+package is up-to-date at a later time with the \l{bpkg-pkg-update(1) \c{bpkg
+update}} command (there is also \l{bpkg-pkg-clean(1) \c{bpkg clean}}), for
+example:
+
+\
+$ bpkg clean hello
+rm hello-1.0.0/exe{hello}
+rm hello-1.0.0/obje{hello}
+cleaned hello/1.0.0
+
+$ bpkg update hello
+c++ hello-1.0.0/cxx{hello.cxx}
+ld hello-1.0.0/exe{hello}
+updated hello/1.0.0
+\
+
+Let's say we really don't like the direction \c{libhello} is going and would
+rather stick to version \c{1.0.0}. Just like upgrades, downgrades are explicit
+plus, in this case, we need to specify the version (you can also specify
+the desired version for upgrades).
+
+\
+$ bpkg build libhello/1.0.0
+  downgrade libhello/1.0.0
+  reconfigure hello (dependent of libhello)
+continue? [Y/n] y
+update dependent packages? [Y/n] y
+disfigured hello/1.0.0
+disfigured libhello/1.1.0
+libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
+fetched libhello/1.0.0
+unpacked libhello/1.0.0
+configured libhello/1.0.0
+configured hello/1.0.0
+following prerequisite packages were automatically built and will no longer be necessary:
+  libprint
+  libformat
+drop prerequisite packages? [Y/n] y
+disfigured libprint
+disfigured libformat
+purged libprint
+purged libformat
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/liba{hello}
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/libs{hello}
+c++ libhello-1.0.0/tests/test/cxx{driver}
+ld libhello-1.0.0/tests/test/exe{driver}
+c++ hello-1.0.0/cxx{hello}
+ld hello-1.0.0/exe{hello}
+updated libhello/1.0.0
+updated hello/1.0.0
+\
+
+Notice how \c{bpkg} helpfully offered to get rid of \c{libprint} and
+\c{libformat} which we won't be needing anymore. Note also that while we
+can use \c{--yes|y} as an answer to all the numerous prompts, there are
+also more granular options. For example, this is how we can instruct
+\c{bpkg} to drop prerequisites (\c{--drop-prerequisite|-D}) but leave
+dependents just reconfigured (\c{--leave-dependent|-L}):
+
+\
+$ bpkg build -D -L libhello/1.0.0
+\
+
+Ok, so all this might look nice and all, but we haven't actually seen anything
+of what we've presumably built; it can all be a charade, for all we know. Can
+we see some libraries and run the \c{hello} program?
+
+There are several ways we can do this. If the package provides tests (as all
+good packages should), we can run them with the \l{bpkg-pkg-test(1) \c{bpkg
+test}} command:
+
+\
+$ bpkg test libhello hello
+test libhello-1.0.0/tests/test/exe{driver}
+test hello-1.0.0/exe{hello}
+tested libhello/1.0.0
+tested hello/1.0.0
+\
+
+But that doesn't quite count for seeing libraries and running programs. Well,
+if you insist, let's see what's inside \c{hello-gcc5-release/}. The \c{bpkg}
+configuration (this \c{hello-gcc5-release/} directory) is, in the \c{build2}
+build system terms, an \i{amalgamation} \- a project that contains
+\i{subprojects}. Not surprisingly, the subprojects in this amalgamation are the
+packages that we've built:
+
+\
+$ ls -1F
+build/
+hello-1.0.0/
+libhello-1.0.0/
+buildfile
+hello-1.0.0.tar.gz
+libhello-1.0.0.tar.gz
+\
+
+And if we look inside \c{hello-1.0.0/} we will see what looks like the
+\c{hello} program:
+
+\
+$ ls -1F hello-1.0.0/
+build/
+buildfile
+hello*
+hello.d
+hello.cxx
+hello.o
+hello.o.d
+manifest
+test.out
+version
+
+$ hello-1.0.0/hello
+usage: hello <name>...
+
+$ hello-1.0.0/hello World
+Hello, World!
+\
+
+The important point here is this: the \c{bpkg} configuration is not some black
+box that you should never look inside of. On the contrary, it is a normal and
+predictable concept of the build system and as long as you understand what you
+are doing, feel free to muck around.
+
+Another way to get hold of a package's goodies is to install it with
+\l{bpkg-pkg-install(1) \c{bpkg install}}. Let's try that:
+
+\
+$ bpkg install                   \
+  config.install.root=/opt/hello \
+  config.install.sudo=sudo       \
+  hello
+
+install /opt/hello/
+install /opt/hello/include/
+install /opt/hello/include/hello/
+install libhello-1.0.0/hello/hxx{hello}
+install libhello-1.0.0/hello/hxx{export}
+install /opt/hello/lib/
+install libhello-1.0.0/hello/libs{hello}
+install /opt/hello/bin/
+install hello-1.0.0/exe{hello}
+install /opt/hello/share/
+install /opt/hello/share/doc/
+install /opt/hello/share/doc/hello/
+install hello-1.0.0/doc{version}
+installed hello/1.0.0
+\
+
+The \c{config.install.sudo} value is the optional \i{sudo}-like program
+that should be used to run the \c{install} program. For those feeling queasy
+running \c{sudo make install}, here is your answer. If you are wondering
+whether you could have specified those \c{config.install.*} values during the
+configuration creation, the answer is yes, indeed!
+
+Let's see what we've got:
+
+\
+$ tree -F /opt/hello/
+/opt/hello/
+├── bin/
+│   └── hello*
+├── include/
+│   └── libhello/
+│       ├── export
+│       └── hello
+├── lib/
+│   ├── libhello-1.0.so*
+│   └── libhello.so -> libhello-1.0.so*
+└── share/
+    └── doc/
+        └── hello/
+            └── version
+\
+
+We can also try to run the installed program:
+
+\
+$ /opt/hello/bin/hello World
+/opt/hello/bin/hello: error while loading shared libraries: libhello-1.0.so: cannot open shared object file: No such file or directory
+\
+
+Not what we hoped to see. Note to the Windows users: this will actually work
+since \c{hello-1.0.dll} will be installed into \c{bin\\}, next to the
+executable; for once things are working better on Windows.
+
+The problem is with our installation location: the runtime linker won't look
+for \c{libhello-1.0.so} in \c{/opt/hello/lib} unless we somehow tell it to
+(for example, using \c{LD_LIBRARY_PATH} or equivalent).  There are several
+ways we can resolve this. We could give up on shared libraries and link our
+prerequisite libraries statically (\c{config.bin.exe.lib=static}). Or we could
+use the \i{rpath} mechanism:
+
+\
+$ bpkg install                    \
+  config.install.root=/opt/hello  \
+  config.install.sudo=sudo        \
+  config.bin.rpath=/opt/hello/lib \
+  hello
+
+ld hello-1.0.0/exe{hello}
+install /opt/hello/
+install /opt/hello/include/
+install /opt/hello/include/hello/
+install libhello-1.0.0/hello/hxx{hello}
+install libhello-1.0.0/hello/hxx{export}
+install /opt/hello/lib/
+install libhello-1.0.0/hello/libs{hello}
+install /opt/hello/bin/
+install hello-1.0.0/exe{hello}
+install /opt/hello/share/
+install /opt/hello/share/doc/
+install /opt/hello/share/doc/hello/
+install hello-1.0.0/doc{version}
+installed hello/1.0.0
+
+$ /opt/hello/bin/hello World
+Hello, World!
+\
+
+Notice that \c{ld} line above \- this is where our executable is re-linked
+with the \c{-rpath} option.
+
+We can also uninstall what we have installed with \l{bpkg-pkg-uninstall(1)
+\c{bpkg uninstall}}:
+
+\
+$ bpkg uninstall                  \
+  config.install.root=/opt/hello  \
+  config.install.sudo=sudo        \
+  hello
+
+uninstall hello-1.0.0/doc{version}
+uninstall /opt/hello/share/doc/hello/
+uninstall /opt/hello/share/doc/
+uninstall /opt/hello/share/
+uninstall hello-1.0.0/exe{hello}
+uninstall /opt/hello/bin/
+uninstall libhello-1.0.0/hello/libs{hello}
+uninstall /opt/hello/lib/
+uninstall libhello-1.0.0/hello/hxx{export}
+uninstall libhello-1.0.0/hello/hxx{hello}
+uninstall /opt/hello/include/hello/
+uninstall /opt/hello/include/
+uninstall /opt/hello/
+uninstalled hello/1.0.0
+
+$ ls /opt/hello
+ls: cannot access /opt/hello: No such file or directory
+\
+
+What if we wanted to use \c{libhello} in our own project? While installing it
+is always an option, this may not be convenient when we develop our code. We
+may have multiple builds per project, for example, with GCC and Clang to catch
+all the warnings. We may also want to make sure our application works well
+with several versions of \c{libhello} (and maybe even with that heinous
+\c{1.1.X}). While we can install different configurations into different
+directories, it's hard to deny things are getting a bit hairy: multiple
+configurations, multiple installations... I guess we will have to get our
+hands into that cookie jar, I mean, configuration, again.
+
+In fact, let's just start writing our own version of the \c{hello} program
+and see how it goes:
+
+\
+$ mkdir hello2
+$ cd hello2
+
+$ cat >hello.cpp
+
+#include <libhello/hello>
+
+int main ()
+{
+  hello::say (\"World\");
+}
+
+\
+
+What build system shall we use? I can't believe you are even asking this
+question...
+
+\
+$ mkdir build
+
+$ cat >build/bootstrap.build
+
+project = hello2              # project name
+using config                  # config module (those config.*)
+
+$ cat >build/root.build
+
+cxx.std = 11                  # C++ standard
+using cxx                     # C++ module
+cxx{*}: extension = cpp       # C++ source file extension
+
+$ cat >buildfile
+
+import libs = libhello%lib{hello}
+exe{hello}: cxx{hello} $libs
+\
+
+While some of this might not be crystal clear (like why do we have
+\c{bootstrap.build} \i{and} \c{root.build}), I am sure you at least have a
+fuzzy idea of what's going on. And that's enough for what we are after here.
+Completely explaining what's going on here and, more importantly, \i{why} it's
+going this way is for another time and place (the \c{build2} build system
+manual).
+
+To recap, these are the contents of our project so far:
+
+\
+$ tree -F
+.
+├── build/
+│   ├── bootstrap.build
+│   └── root.build
+├── buildfile
+└── hello.cpp
+\
+
+Let's try to build it and see what happens \- maybe it will magically work
+(\l{b(1)} is the \c{build2} build system driver).
+
+\
+$ b config.cxx=g++-5
+error: unable to import target libhello%lib{hello}
+  info: use config.import.libhello command line variable to specifying its project out_root
+  info: while applying rule cxx.link to update exe{hello}
+  info: while applying rule alias to update dir{./}
+\
+
+No magic, unfortunately (or fortunately). But we got a hint: looks like we
+need to tell \c{build2} where \c{libhello} is using
+\c{config.import.libhello}. Without fretting too much about what exactly
+\c{out_root} means, let's point \c{build2} to our \c{bpkg} configuration and
+see what happens. After all, that's where, more or less, our \i{out}-put for
+\c{libhello} is.
+
+\
+$ b config.cxx=g++-5 \
+    config.import.libhello=/tmp/hello-gcc5-release
+c++ cxx{hello}
+ld exe{hello}
+\
+
+Almost magic. Let's see what we've got:
+
+\
+$ tree -F
+.
+├── build/
+│   ├── bootstrap.build
+│   └── root.build
+├── buildfile
+├── hello*
+├── hello.d
+├── hello.cpp
+├── hello.o
+└── hello.o.d
+
+$ ./hello
+Hello, World!
+\
+
+Let's change something in our source code and try to update:
+
+\
+$ touch hello.cpp
+
+$ b
+error: unable to import target libhello%lib{hello}
+  info: use config.import.libhello command line variable to specifying its project out_root
+  info: while applying rule cxx.link to update exe{hello}
+  info: while applying rule alias to update dir{./}
+\
+
+Looks like we have to keep repeating those \c{config.*} values and who wants
+that? To get rid of this annoyance we have to make our configuration
+\i{permanent}. Also, seeing that we plan to have several of them (GCC/Clang,
+different version of \c{libhello}), it makes sense to create them \i{out of
+source tree}. Let's get to it:
+
+\
+$ cd ..
+$ mkdir hello2-gcc5-release
+$ ls -1F
+hello2/
+hello2-gcc5-release/
+
+$ b config.cxx=g++-5                             \
+  config.cc.coptions=-O3                         \
+  config.import.libhello=/tmp/hello-gcc5-release \
+  'configure(hello2/@hello2-gcc5-release/)'
+
+mkdir -p hello2-gcc5-release/build/
+save hello2-gcc5-release/build/config.build
+\
+
+Translated, \c{configure(hello2/@hello2-gcc5-release/)} means \i{\"configure
+the \c{hello2/} source directory in the \c{hello2-gcc5-release/} output
+directory\"}. In \c{build2} this \i{source directory} is called \c{src_root}
+and \i{output directory} \- \c{out_root}. Hm, we've already heard \c{out_root}
+mentioned somewhere before...
+
+Once the configuration is saved, we can develop our project without any
+annoyance:
+
+\
+$ b hello2-gcc5-release/
+c++ hello2/cxx{hello}
+ld hello2-gcc5-release/exe{hello}
+
+$ cd hello2-gcc5-release/
+
+$ b
+info: dir{./} is up to date
+
+$ b clean
+rm exe{hello}
+rm obje{hello}
+
+$ b -v
+g++-5 -I/tmp/hello-gcc5-release/libhello-1.0.0 -O3 -std=c++11 -o hello.o -c ../hello2/hello.cpp
+g++-5 -O3 -std=c++11 -o hello hello.o /tmp/hello-gcc5-release/libhello-1.0.0/hello/libhello-1.0.so
+\
+
+Some of you might have noticed that \c{hello2-gcc5-release/} and
+\c{/tmp/hello-gcc5-release/} look awfully similar and are now wondering if we
+could instead build \c{hello2} \i{inside} \c{/tmp/hello-gcc5-release/}? I am
+glad you've asked. In fact, we can just do:
+
+\
+$ cd ..
+$ ls -1F
+hello2/
+hello2-gcc5-release/
+
+$ b 'configure(hello2/@/tmp/hello-gcc5-release/hello2/)'
+mkdir -p /tmp/hello-gcc5-release/hello2/build/
+save /tmp/hello-gcc5-release/hello2/build/config.build
+
+$ b /tmp/hello-gcc5-release/hello2/
+c++ hello2/cxx{hello}@/tmp/hello-gcc5-release/hello2/
+ld /tmp/hello-gcc5-release/hello2/exe{hello}
+\
+
+Now that might seem like magic, but it's actually pretty logical. Why don't we
+need to specify any of the \c{config.c*} values this time? Because they are
+inherited from those specified for \c{/tmp/hello-gcc5-release} when we created
+the configuration with \c{bpkg create}. What about \c{config.import.libhello},
+don't we need at least that? Not really \- \c{libhello} will be found
+automatically since it is part of the same amalgamation.
+
+Of course, \c{bpkg} has no idea \c{hello2} is now part of its configuration:
+
+\
+$ bpkg status -d /tmp/hello-gcc5-release/ hello2
+unknown
+\
+
+This is what I meant when I said you can muck around in \c{bpkg}'s back yard as
+long as you understand the implications.
+
+But is there a way to make \c{bpkg} aware of our little project? You seem to
+really have all the right questions today. Actually, there is a very good
+reason why we would want that: if we upgrade \c{libhello} we would want
+\c{bpkg} to automatically reconfigure our project. As it is now, we will have
+to remember and do it ourselves.
+
+The only way to make \c{bpkg} aware of \c{hello2} is to turn it from merely a
+\c{build2} \i{project} into a \c{build2} \i{package}. While the topic of
+packaging is also for another time and place (the \c{build2} package manager
+manual), we can get away with something as simple as this:
+
+\
+$ cat >hello2/manifest
+: 1
+name: hello2
+version: 1.0.0
+summary: Improved \"Hello World\" program
+license: proprietary
+url: http://example.org/hello2
+email: hello2@example.org
+depends: libhello >= 1.0.0
+\
+
+For our purposes, the only really important value in this manifest is
+\c{depends} since it tells \c{bpkg} which package(s) we need. Let's give it a
+try. But first we will clean up our previous attempt at building \c{hello2}
+inside \c{/tmp/hello-gcc5-release/}:
+
+\
+$ b '{clean disfigure}(/tmp/hello-gcc5-release/hello2/)'
+rm /tmp/hello-gcc5-release/hello2/exe{hello}
+rm /tmp/hello-gcc5-release/hello2/obje{hello}
+rm /tmp/hello-gcc5-release/hello2/build/config.build
+rmdir /tmp/hello-gcc5-release/hello2/
+\
+
+Next, we use the \l{bpkg-pkg-build(1) \c{bpkg build}} command but instead of
+giving it a package name like we did before, we will point it to our \c{hello2}
+package directory (\c{bpkg} can fetch packages or it can build local package
+archives or package directories):
+
+\
+$ bpkg build -d /tmp/hello-gcc5-release/ ./hello2/
+  build hello2/1.0.0
+continue? [Y/n] y
+unpacked hello2/1.0.0
+configured hello2/1.0.0
+c++ hello2/cxx{hello}@/tmp/hello-gcc5-release/hello2-1.0.0/
+ld /tmp/hello-gcc5-release/hello2-1.0.0/exe{hello}
+updated hello2/1.0.0
+\
+
+Let's upgrade \c{libhello} and see what happens:
+
+\
+$ bpkg build -d /tmp/hello-gcc5-release/ -L libhello
+  build libformat/1.0.0 (required by libhello)
+  build libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  reconfigure hello2 (dependent of libhello)
+continue? [Y/n] y
+disfigured hello2/1.0.0
+disfigured libhello/1.0.0
+[ ... fetching & unpacking ... ]
+configured libformat/1.0.0
+configured libprint/1.0.0
+configured libhello/1.1.0
+configured hello2/1.0.0
+[ ... updating libprint, libformat, and libhello ... ]
+updated libhello/1.1.0
+\
+
+As promised, \c{hello2} got reconfigured (it didn't get updated because of the
+\c{-L} option). We can now update it and give it a try:
+
+\
+$ bpkg update -d /tmp/hello-gcc5-release/ hello2
+c++ hello2/cxx{hello}@/tmp/hello-gcc5-release/hello2-1.0.0/
+ld /tmp/hello-gcc5-release/hello2-1.0.0/exe{hello}
+updated hello2/1.0.0
+
+$ /tmp/hello-gcc5-release/hello2-1.0.0/hello
+Hello, World!
+\
+
+To finish off, let's see how hard it will be to get a Clang build going:
+
+\
+$ cd /tmp
+$ mkdir hello-clang36-release
+$ cd hello-clang36-release
+
+$ bpkg create cc config.cxx=clang++-3.6 config.cc.coptions=-O3
+created new configuration in /tmp/hello-clang36-release/
+
+$ bpkg add https://build2.org/pkg/1/hello/testing
+added repository build2.org/hello/testing
+
+$ bpkg fetch
+fetching build2.org/hello/testing
+[... certificate authentication ...]
+fetching build2.org/hello/stable (complements build2.org/hello/testing)
+5 package(s) in 2 repository(s)
+
+$ bpkg build libhello/1.0.0 path/to/hello2/
+  build libhello/1.0.0
+  build hello2/1.0.0
+continue? [Y/n] y
+libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
+fetched libhello/1.0.0
+unpacked libhello/1.0.0
+unpacked hello2/1.0.0
+configured libhello/1.0.0
+configured hello2/1.0.0
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/liba{hello}
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/libs{hello}
+c++ libhello-1.0.0/tests/test/cxx{driver}
+ld libhello-1.0.0/tests/test/exe{driver}
+c++ /path/to/hello2/cxx{hello}@hello2-1.0.0/
+ld hello2-1.0.0/exe{hello}
+updated libhello/1.0.0
+updated hello2/1.0.0
+\
+
+Are you still there? Ok, one last example. Let's see how hard it is to
+cross-compile.
+
+\
+$ mkdir hello-mingw64
+$ cd hello-mingw64
+
+$ bpkg create cc config.cxx=x86_64-w64-mingw32-g++
+created new configuration in /tmp/hello-mingw64/
+
+$ bpkg add https://build2.org/pkg/1/hello/stable
+added repository build2.org/hello/stable
+
+$ bpkg fetch
+fetching build2.org/hello/stable
+[... certificate authentication ...]
+2 package(s) in 1 repository(s)
+
+$ bpkg build -y hello
+libhello-1.0.0.tar.gz        100% of 2428  B  983 kBps 00m01s
+fetched libhello/1.0.0
+unpacked libhello/1.0.0
+hello-1.0.0.tar.gz           100% of 1057  B 6882 kBps 00m01s
+fetched hello/1.0.0
+unpacked hello/1.0.0
+configured libhello/1.0.0
+configured hello/1.0.0
+c++ hello-1.0.0/cxx{hello}
+c++ libhello-1.0.0/hello/cxx{hello}
+ld libhello-1.0.0/hello/libs{hello}
+ld hello-1.0.0/exe{hello}
+updated hello/1.0.0
+
+$ wine hello-1.0.0/hello.exe Windows
+Hello, Windows!
+\
+
+In fact, on a properly setup GNU/Linux machine (that automatically uses
+\c{wine} as an \c{.exe} interpreter) we can even run tests:
+
+\
+$ bpkg test libhello hello
+c++ libhello-1.0.0/tests/test/cxx{driver}
+ld libhello-1.0.0/tests/test/exe{driver}
+test libhello-1.0.0/tests/test/exe{driver}
+test hello-1.0.0/exe{hello}
+tested libhello/1.0.0
+tested hello/1.0.0
+\
+"