Rename intro2 to intro, old intro to intro1

4 files changed, 2270 insertions, 2270 deletions

diff --git a/doc/cli.sh b/doc/cli.sh
index 1747730..7126f5c 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -49,8 +49,8 @@ html2ps -f doc.html2ps:letter.html2ps -o build2-toolchain-$n-letter.ps build2-to
 ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-letter.ps build2-toolchain-$n-letter.pdf
 }
 
-gen intro2
 gen intro
+#gen intro1
 
 # Auto-heading doesn't work since it is broken into multiple doc strings.
 #
diff --git a/doc/intro.cli b/doc/intro.cli
index ac43311..a90a3ae 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -18,7 +18,6 @@
 // PDF
 //
 // @@ tree output is garbled
-// @@ Install list margins missing
 // @@ Could we use a nicer font, seeing that we embed them?
 //
 
@@ -28,1142 +27,1364 @@
 //
 
 "
-\h#tldr|TL;DR|
+\h1#tldr|TL;DR|
 
 \
-$ bpkg create -d hello cc
-created new configuration in hello/
+$ git clone ssh://example.org/hello.git
+$ tree hello
+hello/
+├── hello/
+│   ├── hello.cxx
+│   └── buildfile
+├── manifest
+└── repositories.manifest
 
-$ cd hello/
-$ bpkg add https://build2.org/pkg/1/hello/stable
-added repository build2.org/hello/stable
+$ cd hello
+$ bdep init --config-create ../hello-gcc cc config.cxx=g++
+initializing project /tmp/hello/
+created configuration /tmp/hello-gcc/ (default, auto-synchronized)
+synchronizing:
+  new hello/0.1.0
 
-$ 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
+$ b
+c++ hello/cxx{hello}@../hello-gcc/hello/hello/
+ld ../hello-gcc/hello/hello/exe{hello}
+ln ../hello-gcc/hello/hello/exe{hello} -> hello/
 
-hello-1.0.0.tar.gz           100% of 1057  B 6882 kBps 00m01s
-fetched hello/1.0.0
-unpacked hello/1.0.0
+$ hello/hello World
+Hello, World!
 
-configured libhello/1.0.0
-configured hello/1.0.0
+$ edit repositories.manifest   # add https://example.org/libhello.git
+$ edit manifest                # add 'depends: libhello ^1.0.0'
+$ edit hello/buildfile         # import libhello
+$ edit hello/hello.cxx         # use libhello
 
-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}
+$ b
+fetching from https://example.org/libhello.git
+synchronizing /tmp/hello-gcc/:
+  new libhello/1.0.0 (required by hello)
+  reconfigure hello/0.1.0
+c++ ../hello-gcc/libhello-1.0.0/libhello/cxx{hello}
+ld ../hello-gcc/libhello-1.0.0/libhello/libs{hello}
+c++ hello/cxx{hello}@../hello-gcc/hello/hello/
+ld ../hello-gcc/hello/hello/exe{hello}
+ln ../hello-gcc/hello/hello/exe{hello} -> hello/
+
+$ bdep fetch                   # refresh available versions
+$ bdep status -i               # review available versions
+hello configured 0.1.0
+  libhello ^1.0.0 configured 1.0.0 available [1.1.0]
+
+$ bdep sync libhello           # upgrade to latest
+synchronizing:
+  new libformat/1.0.0 (required by libhello)
+  new libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  reconfigure hello/0.1.0
 
-updated hello/1.0.0
+$ bdep sync libhello/1.0.0     # downgrade
+synchronizing:
+  drop libprint/1.0.0 (unused)
+  drop libformat/1.0.0 (unused)
+  downgrade libhello/1.0.0
+  reconfigure hello/0.1.0
 \
-"
 
-"
-\h#warning|Warning|
+\h1#guide|Getting Started Guide|
+
+The aim of this guide is to get you started developing C/C++ projects with the
+\c{build2} toolchain. All the examples in this section include the relevant
+command output so if you just want to get a sense of what \c{build2} is about,
+then you don't have to install the toolchain and run the commands in order to
+follow along. If at the end you find \c{build2} appealing and would like to
+start using it or try the examples for yourself, you can jump straight to
+\l{build2-toolchain-install.xhtml The \c{build2} Toolchain Installation and
+Upgrade}.
 
-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}!
+One of the primary goals of the \c{build2} toolchain is to provide a uniform
+interface across all the platforms and compilers. While the examples in this
+document assume a UNIX-like operation system, they will look pretty similar if
+you are on Windows. You just have to use appropriate paths, compilers, and
+options.
 
-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:
+The question we will try to answer in this section can be summarized as:
 
-\ul|
+\
+$ git clone .../hello.git && now-what?
+\
 
-\li|Limited documentation.|
+That is, we clone an existing C/C++ project or would like to create a new one
+and then start hacking on it. We want to spend as little time and energy as
+possible on the initial and ongoing infrastructure maintenance: setting up
+build configurations, managing dependencies, continuous integration and
+testing, release management, etc. Or, as one C++ user aptly put it, \"\i{All I
+want to do is program.}\"
 
-\li|No support for custom build system rules/modules.|
+\h#guide-hello|Hello, World|
 
-|
-"
+Let's see what programming with \c{build2} feels like by starting with a
+customary \i{\"Hello, World!\"} program (here we assume our current working
+directory is \c{/tmp}):
 
-"
-\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.
+\
+$ bdep new -t exe -l c++ hello
+created new executable project hello in /tmp/hello/
+\
 
-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.
+The \l{bdep-new(1)} command creates a \i{canonical} \c{build2} project. In
+our case it is an executable implemented in C++.
 
-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.
+\N|To create a library, pass \c{-t\ lib}. By default \c{new} also initializes
+a \c{git} repository and generates suitable \c{.gitignore} files (pass \c{-s\
+none} if you don't want that).|
 
-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:
+Let's take a look inside our new project:
 
 \
-$ 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/
+$ tree hello
+hello/
+├── .git/
+├── .bdep/
+├── build/
+├── hello/
+│   ├── hello.cxx
+│   ├── buildfile
+│   └── testscript
+├── buildfile
+├── manifest
+└── repositories.manifest
 \
 
-Or perhaps you are on Windows and prefer Visual Studio (running from the
-Visual Studio Tools Command Prompt):
+\N|While the canonical project structure is strongly recommended, especially
+for new projects, \c{build2} is flexible enough to allow most commonly used
+arrangements.|
+
+Similar to version control tools, we normally run all \c{build2} tools from
+the project's source directory or one of its subdirectories, so:
 
 \
-> 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\
+$ cd hello
 \
 
-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.
+While the project layout is discussed in more detail in later sections, let's
+examine a couple of interesting files to get a sense of what's going on. We
+start with the source file which should look familiar:
 
-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>}}.
+\
+$ cat hello/hello.cxx
 
-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.
+#include <iostream>
 
-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).
+using namespace std;
 
-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:
+int main (int argc, char* argv[])
+{
+  if (argc < 2)
+  {
+    cerr << \"error: missing name\" << endl;
+    return 1;
+  }
 
+  cout << \"Hello, \" << argv[1] << '!' << endl;
+}
 \
-$ bpkg create c cxx ...
+
+\N|If you prefer the \c{.?pp} extensions over \c{.?xx} for your C++ source
+files, pass \c{-l\ c++,cpp} to the \c{new} command. See \l{bdep-new(1)} for
+details on this and other customization options.|
+
+Let's take a look at the accompanying \c{buildfile}:
+
 \
+$ cat hello/buildfile
 
-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}:
+libs =
+#import libs += libhello%lib{hello}
 
+exe{hello}: {hxx ixx txx cxx}{*} $libs test{testscript}
 \
-$ bpkg create cc config.cxx=g++-5 config.cc.coptions=-O3
+
+As the name suggests, this file describes how to build things. While its
+content might look a bit cryptic, let's try to infer a couple of points
+without going into too much detail (the details are discussed in the following
+sections). That \c{exe{hello\}} on the left of \c{:} is a \i{target}
+(executable named \c{hello}) and what we have on the right are
+\i{prerequisites} (C++ source files, libraries, etc). This \c{buildfile} uses
+\l{b#name-patterns wildcard patterns} (that \c{*}) to automatically locate all
+the C++ source files. This means we don't have to edit our \c{buildfile} every
+time we add a source file to our project. There also appears to be some
+(commented out) infrastructure for importing and linking libraries (that
+\c{libs} variable). We will see how to use it in a moment. Finally, the
+\c{buildfile} also lists \c{testscript} as a prerequisite of \c{hello}. This
+file tests our target. Let's take a look inside:
+
 \
+$ cat hello/testscript
 
-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).
+: basics
+:
+$* 'World' >'Hello, World!'
+
+: missing-name
+:
+$* 2>>EOE != 0
+error: missing name
+EOE
+\
 
-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).
+Again, we are not going into detail here (see \l{testscript#intro Testscript
+Introduction} for a proper introduction), but to give you an idea, here we
+have two tests: the first (with id \c{basics}) verifies that our program
+prints the expected greeting while the second makes sure it handles the
+missing name error condition. Tests written in Testscript are concise,
+portable, and executed in parallel.
 
-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:
+Next up is \c{manifest}:
 
 \
-$ 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]
+$ cat manifest
+: 1
+name: hello
+version: 0.1.0-a.0.z
+summary: hello executable project
+license: proprietary
+url: https://example.org/hello
+email: you@example.org
+#depends: libhello ^1.0.0
 \
 
-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.
+The \c{manifest} file is what makes a build system project a \i{package}. It
+contains all the metadata that a user of a package might need to know: its
+name, version, license, dependencies, etc., all in one place.
 
-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:
+\N|Refer to \l{bpkg#manifest-format Manifest Format} for the general format of
+\c{build2} manifest files and to \l{bpkg#manifest-package Package Manifest}
+for details on the package manifest values.|
 
-\
-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
+As you can see, \c{manifest} created by \l{bdep-new(1)} contains some dummy
+values which you would want to adjust before publishing your package. But
+let's resist the urge to adjust that strange looking \c{0.1.0-a.0.z} until we
+discuss package versioning.
 
-hello/1.0.0
-libhello/1.0.0
-\
+\N|Next to \c{manifest} you might have noticed the \c{repositories.manifest}
+file \- we will discuss its function later, when we talk about dependencies
+and where they come from.|
 
-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/}}.
+Project in hand, let's build it. Unlike other programming languages, C++
+development usually involves juggling a handful of build configurations:
+several compilers and/or targets (\c{build2} is big on cross-compiling),
+debug/release, different sanitizers and/or static analysis tools, and so
+on. As a result, \c{build2} is optimized for multi-configuration
+usage. However, as we will see shortly, one build configuration can be
+designated as the default with additional conveniences.
 
-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:
+The \l{bdep-init(1)} command is used to initialize a project in a build
+configuration. As a shortcut, it can also create a new build configuration in
+the process, which is just what we need here. Let's start with GCC (remember
+we are in the project's root directory):
 
 \
-$ bpkg add https://build2.org/pkg/1/hello/stable
-added repository build2.org/hello/stable
+$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
+initializing project /tmp/hello/
+created configuration @gcc /tmp/hello-gcc/ (default, auto-synchronized)
+synchronizing:
+  new hello/0.1.0-a.0.19700101000000
 \
 
-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:
+The \cb{--create|-C} option instructs \c{init} to create a new configuration
+in the specified directory (\c{../hello-gcc} in our case). To make referring
+to configurations easier, we can give it a name, which is what we do with
+\c{@gcc}. The next argument (\c{cc}, stands for \i{C-common}) is the build
+system module we would like to configure. It implements compilation and
+linking rules for the C and C++ languages. Finally, \c{config.cxx=g++} is (one
+of) this module's configuration variables that specifies the C++ compiler we
+would like to use (the corresponding C compiler will be determined
+automatically). Let's for now also ignore that \c{synchronizing:...} bit along
+with strange-looking \c{19700101000000} in the version \- it will become clear
+what's going on here in a moment.
+
+Now the same for Clang:
 
 \
-$ bpkg fetch
-fetching build2.org/hello/stable
-2 package(s) in 1 repository(s)
+$ bdep init -C ../hello-clang @clang cc config.cxx=clang++
+initializing project /tmp/hello/
+created configuration @clang /tmp/hello-clang/ (auto-synchronized)
+synchronizing:
+  new hello/0.1.0-a.0.19700101000000
 \
 
-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:
+If we check the parent directory, we should now see two build configurations
+next to our project:
 
 \
-$ bpkg build hello
-  build libhello/1.0.0 (required by hello)
-  build hello/1.0.0
-continue? [Y/n]
+$ ls ..
+hello/
+hello-gcc/
+hello-clang/
 \
 
-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.
+Things will also look pretty similar if you are on Windows instead of a
+UNIX-like operating system. For example, to initialize our project on Windows
+with Visual Studio, start the Visual Studio development command prompt and
+then run:
 
-Let's answer \i{yes} and see what happens:
+\N|Currently we have to run \c{build2} tools from a suitable Visual Studio
+development command prompt. This requirement will likely be removed in the
+future.|
 
 \
-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
+> bdep init -C ..\hello-debug @debug cc     ^
+  config.cxx=cl                             ^
+  \"config.cc.coptions=/MDd /Z7\"             ^
+  config.cc.loptions=/DEBUG
+
+> bdep init -C ..\hello-release @release cc ^
+  config.cxx=cl                             ^
+  config.cc.coptions=/O2
 \
 
-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:
+\N|Besides the \c{coptions} (compile options) and \c{loptions} (link options),
+other commonly used \c{cc} module configuration variables are \c{poptions}
+(preprocess options) and \c{libs} (extra libraries to link). We can also use
+their \c{config.c.*} (C compilation) and \c{config.cxx.*} (C++ compilation)
+variants if we only want them applied during the respective language
+compilation. For example:
 
 \
-$ 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
+$ bdep init ... cc       \
+  config.cxx=clang++     \
+  config.cc.coptions=-g  \
+  config.cxx.coptions=-stdlib=libc++
 \
 
-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
+|
+
+One difference you might have noticed when creating the \c{gcc} and \c{clang}
+configurations above is that the first one was designated as the default. The
+default configuration is used by \c{bdep} commands if no configuration is
+specified explicitly (see \l{bdep-projects-configs(1)} for details). It is
+also the configuration that is used if we run the build system in the
+project's source directory. So, normally, you would make your every day
+development configuration the default. Let's try that:
+
 \
+$ bdep status
+hello configured 0.1.0-a.0.19700101000000
+
+$ b
+c++ hello/cxx{hello}@../hello-gcc/hello/hello/
+ld ../hello-gcc/hello/hello/exe{hello}
+ln ../hello-gcc/hello/hello/exe{hello} -> hello/
 
-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)}):
+$ b test
+test hello/test{testscript} ../hello-gcc/hello/hello/exe{hello}
 
+$ hello/hello World
+Hello, World!
 \
-$ bpkg status libhello
-configured 1.0.0; available sys:?
 
-$ bpkg status hello
-configured 1.0.0 hold_package; available sys:?
+In contrast, the Clang configuration has to be requested explicitly:
 
-$ bpkg drop -y hello
-disfigured hello
-disfigured libhello
-purged hello
-purged libhello
+\
+$ bdep status @clang
+hello configured 0.1.0-a.0.19700101000000
+
+$ b ../hello-clang/hello/
+c++ hello/cxx{hello}@../hello-clang/hello/hello/
+ld ../hello-clang/hello/hello/exe{hello}
 
-$ bpkg status hello
-available 1.0.0 sys:?
+$ b test: ../hello-clang/hello/
+test hello/test{testscript} ../hello-clang/hello/hello/exe{hello}
 
-$ bpkg status libfoobar
-unknown
+$ ../hello-clang/hello/hello/hello World
+Hello, World!
 \
 
-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.
+\N|To see the actual compilation command lines, run \c{b\ -v} and for even
+more details, run \c{b\ -V}. See \l{b(1)} for more information on these
+and other build system options.|
 
-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.
+While we are here, let's also check how hard it would be to cross-compile:
 
-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).
+\
+$ bdep init -C ../hello-mingw @mingw cc config.cxx=x86_64-w64-mingw32-g++
+initializing project /tmp/hello/
+created configuration @mingw /tmp/hello-mingw/ (auto-synchronized)
+synchronizing:
+  new hello/0.1.0-a.0.19700101000000
 
+$ b ../hello-mingw/hello/
+c++ hello/cxx{hello}@../hello-mingw/hello/hello/
+ld ../hello-mingw/hello/hello/exe{hello}
 \
-$ 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)
+As you can see, cross-compiling in \c{build2} is nothing special. In our case,
+on a properly setup GNU/Linux machine (that automatically uses \c{wine} as an
+\c{.exe} interpreter) we can even run tests (in \c{build2} this is called
+\i{cross-testing}):
+
 \
+$ b test: ../hello-mingw/hello/
+test hello/test{testscript} ../hello-mingw/hello/hello/exe{hello}
 
-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}).
+$ ../hello-mingw/hello/hello/hello.exe Windows
+Hello, Windows!
+\
 
-Let's see what's new:
+Let's review what it takes to initialize a project's infrastructure and
+perform the first build. For an existing project:
 
 \
-$ bpkg status libhello
-configured 1.0.0; available 1.1.0 sys:?
+$ git clone .../hello.git
+$ cd hello
+$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
+$ b
 \
 
-Ok, \c{libhello/1.1.0} is now available. How do we upgrade? We can try to
-build \c{hello} again:
+For a new project:
 
 \
-$ bpkg build -y hello
-info: dir{hello-1.0.0/} is up to date
-updated hello/1.0.0
+$ bdep new -t exe -l c++ hello
+$ cd hello
+$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
+$ b
 \
 
-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:
+If you prefer, the \c{new} and \c{init} steps can be combined into a single
+command:
+
+\
+$ bdep new -t exe -l c++ hello -C hello-gcc @gcc cc config.cxx=g++
+\
+
+Now is also a good time to get an overview of the \c{build2} toolchain. After
+all, we have already used two of its tools (\c{bdep} and \c{b}) without a
+clear understanding of what they actually are.
+
+Unlike most other programming languages that encapsulate the build system,
+package dependency manager, and project dependency manager into a single tool
+(such as Rust's \c{cargo} or Go's \c{go}), \c{build2} is a hierarchy of
+several tools that you will be using directly and which together with your
+version control system (VCS) will constitute the core of your project
+management toolset.
+
+\N|While \c{build2} can work without a VCS, this will result in reduced
+functionality.|
+
+At the bottom of the hierarchy is the build system, \l{b(1)}. Next comes the
+package dependency manager, \l{bpkg(1)}. It is primarily used for \i{package
+consumption} and depends on the build system. The top of the hierarchy is the
+project dependency manager, \l{bdep(1)}. It is used for \i{project
+development} and relies on \c{bpkg} for building project packages and their
+dependencies.
+
+\N|The main reason for this separation is modularity and the resulting
+flexibility: there are situations where we only need the build system (for
+example, when building a package for a system package manager where all the
+dependencies should be satisfied from the system repository), or only the
+build system and package manager (for example, when a build bot is building a
+package for testing).
+
+Note also that strictly speaking \c{build2} is not C/C++-specific; its build
+model is general enough to handle any DAG-based operations and its
+package/project dependency management can be used for any compiled language.|
+
+\N|As we will see in a moment, \c{build2} also integrates with your VCS in
+order to automate project versioning. Note that currently only \c{git(1)} is
+supported.|
+
+Let's now move on to the reason why there is \i{dep} in the \c{bdep} name:
+dependency management.
+
+
+\h#guide-repositories|Package Repositories|
+
+Say we have realized that writing \i{\"Hello, World!\"} programs is a fairly
+common task and that someone must have written a library to help with that. So
+let's see if we can find something suitable to use in our project.
+
+Where should we look? That's a good question. But before we can try to answer
+it, we need to understand where \c{build2} can source dependencies. In
+\c{build2} packages come from \i{package repositories}. Two commonly used
+repository types are \i{version control} and \i{archive}-based (see
+\l{bpkg-repository-types(1)} for details).
+
+As the name suggests, a version control-based repository uses a VCS as its
+distribution mechanism. \N{Currently, only \c{git} is supported.} Such a
+repository normally contains multiple versions of a single package or,
+perhaps, of a few related packages.
+
+An archive-based repository contains multiple, potentially unrelated
+packages/versions as archives along with some meta information (package list,
+prerequisite/complement repositories, signatures, etc) that are all accessible
+via HTTP(S).
+
+Version control and archive-based repositories have different
+trade-offs. Version control-based repositories are great for package
+developers: With services like GitHub they are trivial to setup. In fact, your
+project's (already existing) VCS repository will normally be the \c{build2}
+package repository \- you might need to add a few files, but that's about it.
+
+However, version control-based repositories are not without drawbacks: It will
+be hard for your users to discover your packages (try searching for \"hello
+library\" on GitHub \- most of the results are not even in C++ let alone
+packaged for \c{build2}). There is also the issue of continuous availability:
+users can delete their repositories, services may change their policies or go
+out of business, and so on. Version control-based repositories also lack
+repository authentication and package signing. Finally, obtaining the
+available package list for such repositories can be slow.
+
+A central, archive-based repository would address all these drawbacks: It
+would be a single place to search for packages. Published packages will never
+disappear and can be easily mirrored. Packages are signed and the repository
+is authenticated (see \l{bpkg-repository-signing(1)} for details). And, last,
+but not least, archive-based repositories are fast.
+
+\l{https://cppget.org cppget.org} is the \c{build2} community's central
+package repository (which we hope one day will become \i{the C++ package
+repository}). As an added benefit, packages on \l{https://cppget.org
+cppget.org} are continuously \l{https://cppget.org/?builds built and tested} on
+all the major platform/compiler combinations with the results available as
+part of the package description.
+
+\N|The main drawback of archive-based repositories is the setup cost. Getting
+a basic repository going is relatively easy \- all you need is an HTTP(S)
+server. Adding a repository web interface like that on \l{https://cppget.org
+cppget.org} will require running \l{https://cppget.org/brep \c{brep}}. And
+adding CI will require running a bunch of build bots
+(\l{https://cppget.org/bbot \c{bbot}}).|
+
+\N|CI support for version control-based repositories is a work in progress.|
+
+To summarize, version control-based repositories are great for package
+developers while a central, archive-based repository is convenient for package
+consumers. A reasonable strategy is then for package developers to publish
+their releases to a central repository. Package consumers can then decide
+which repository to use based on their needs. For example, one could use
+\l{https://cppget.org cppget.org} as a (fast, reliable, and secure) source of
+stable versions but also add, say, \c{git} repositories for select packages
+(perhaps with the \c{#HEAD} fragment filter to improve download speed) for
+testing development snapshots. In this model the two repository types
+complement each other.
+
+\N|Support for automated publishing of tagged releases to an archive-based
+repository is a work in progress.|
+
+Let's see how all this works in practice. Go over to \l{https://cppget.org
+cppget.org} and type \"hello library\" in the search box. At the top of the
+search result you should see the \l{https://cppget.org/libhello \c{libhello}}
+package and if you follow the link you will see the package description page
+along with a list of available versions. Pick a version that you like and you
+will see the package version description page with quite a bit of information,
+including the list of platform/compiler combinations that this version has
+been successfully (or unsuccessfully) tested with. If you like what you see,
+copy the \c{location} value \- this is the repository location where this
+package version can be sourced from.
+
+\N|The \l{https://cppget.org cppget.org} repository is split into several
+sections: \c{stable}, \c{testing}, \c{beta}, \c{alpha} and \c{legacy}, with
+each section having its own repository location (see the repository's
+\l{https://cppget.org/?about about} page for details on each section's
+policies). Note also that \c{testing} is complemented by \c{stable}, \c{beta}
+by \c{testing}, and so on, so you only need to choose the lowest stability
+level and you will automatically \"see\" packages from the more stable
+sections.|
+
+\N|The \l{https://cppget.org cppget.org} \c{stable} sections will always
+contain the \c{libhello} library version \c{1.0.X} that was generated using
+the following \l{bdep-new(1)} command line:
+
+\
+$ bdep new -t lib -l c++ libhello
+\
+
+It can be used as a predictable test dependency when setting up new projects.|
+
+Let's say we've visited the \c{libhello} project's
+\l{https://git.build2.org/cgit/hello/libhello/ home page} (for example by
+following a link from the package details page) and noticed that it is being
+developed in a \c{git} repository. How can we see what's available there? If
+the releases are tagged, then we can infer the available released versions
+from the tags. But that doesn't tell us anything about what's happening on the
+\c{HEAD} or in the branches. For that we can use the package manager's
+\l{bpkg-rep-info(1)} command:
+
+\
+$ bpkg rep-info https://git.build2.org/hello/libhello.git
+libhello/1.0.0
+libhello/1.1.0
+\
+
+As you can see, besides \c{1.0.0} that we have seen on \c{cppget.org/stable},
+there is also \c{1.1.0} (which is perhaps being tested in
+\c{cppget.org/testing}). We can also check what might be available on the
+\c{HEAD} (see \l{bpkg-repository-types(1)} for details on the \c{git}
+repository URL format):
 
 \
-$ 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]
+$ bpkg rep-info https://git.build2.org/hello/libhello.git#HEAD
+libhello/1.1.1-a.0.20180504111511.2e82f7378519
 \
 
-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?
+\N|We can also use the \c{rep-info} command on archive-based repositories,
+however, if available, the web interface is usually more convenient and
+provides more information.|
 
-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.
+To summarize, we found two repositories for the \c{libhello} package: the
+archive-based \l{https://cppget.org cppget.org} that contains the released
+versions as well as its development \c{git} repository where we can get the
+bleeding edge stuff. Let's now see how we can add \c{libhello} to our
+project.
 
-Let's answer \i{yes} if only to see what happens:
+
+\h#guide-add-remove-deps|Adding and Removing Dependencies|
+
+So we found \c{libhello} that we would like to use in our \c{hello}
+project. First, we edit the \c{repositories.manifest} file found in the root
+directory of our project and add one of the \c{libhello} repositories as a
+prerequisite. Let's start with \l{https://cppget.org cppget.org}:
 
 \
-update dependent packages? [Y/n]
+role: prerequisite
+location: https://pkg.cppget.org/1/stable
 \
 
-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:
+\N|Refer to \l{bpkg#manifest-repository Repository Manifest} for details on
+the repository manifest values.|
+
+Next, we edit the \c{manifest} file (again, found in the root of our project)
+and specify the dependency on \c{libhello} with optional version constraint.
+For example:
 
 \
-...
-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
+depends: libhello ^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:
+Let's briefly discuss version constraints (for details see the
+\l{bpkg#manifest-package-depends \c{depends}} value documentation). A version
+constraint can be expressed with a comparison operator (\c{==}, \c{>},
+\c{<}, \c{>=}, \c{<=}), a range shortcut operator (\c{~} and \c{^}), or a
+range. Here are a few examples:
 
 \
-$ bpkg clean hello
-rm hello-1.0.0/exe{hello}
-rm hello-1.0.0/obje{hello}
-cleaned hello/1.0.0
+depends: libhello == 1.2.3
+depends: libhello >= 1.2.3
 
-$ bpkg update hello
-c++ hello-1.0.0/cxx{hello.cxx}
-ld hello-1.0.0/exe{hello}
-updated hello/1.0.0
+depends: libhello ~1.2.3
+depends: libhello ^1.2.3
+
+depends: libhello [1.2.3 1.2.9)
 \
 
-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).
+You may already be familiar with the tilde (\c{~}) and caret (\c{^})
+constraints from dependency managers for other languages. To recap, tilde
+allows upgrades to any further patch versions while caret also allows upgrades
+to further minor versions. They are equivalent to the following ranges:
 
 \
-$ 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
+~X.Y.Z  [X.Y.Z  X.Y+1.0)
+
+^X.Y.Z  [X.Y.Z  X+1.0.0)  if X >  0
+^0.Y.Z  [0.Y.Z  0.Y+1.0)  if X == 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}):
+\N|Zero major version component is customarily used during early development
+where the minor version effectively becomes major. As a result, the tilde
+constraint has a special treatment of this case.|
+
+Unless you have good reasons not to (for example, a dependency does not use
+semantic versioning), we suggest that you use the \c{^} constraint which
+provides a good balance between compatibility and upgradability with \c{~}
+being a more conservative option.
+
+Ok, we've specified where our package comes from (\c{repositories.manifest})
+and which versions we find acceptable (\c{manifest}). The next step is to edit
+\c{hello/buildfile} and import the \c{libhello} library into our build:
 
 \
-$ bpkg build -D -L libhello/1.0.0
+import libs += libhello%lib{hello}
 \
 
-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?
+Finally, we modify our source code to use the library:
 
-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:
+\
+#include <libhello/hello.hxx>
+...
+
+int main (int argc, char* argv[])
+{
+  ...
+  hello::say_hello (cout, argv[1]);
+}
+\
+
+\N|You are probably wondering why we have to specify this repeating
+information in so many places. Let's start with the source code: we can't
+specify the version constraint or location there because it will have to be
+repeated in every source file that uses the dependency.
+
+Moving up, \c{buildfile} is also not a good place to specify this information
+for the same reason (a library can be imported in multiple buildfiles) plus
+the build system doesn't really know anything about version constraints or
+repositories which is the purview of the dependency management tools.
+
+Finally, we have to separate the version constraint and the location because
+the same package can be present in multiple repositories with different
+policies. For example, when a package from a version control-based repository
+is published in an archive-based repository, its \c{repositories.manifest}
+file is ignored and all its dependencies should be available from the
+archive-based repository itself (or its fixed set of prerequisite
+repositories). In other words, \c{manifest} belongs to a package while
+\c{repositories.manifest} \- to a repository.
+
+Also note that this is unlikely to become burdensome since adding new
+dependencies is not something that happens often. There are also plans to
+automate this with a \c{bdep-add(1)} command in the future.|
+
+To summarize, these are the files we had to modify to add a dependency
+to our project:
 
 \
-$ 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
+repositories.manifest   # add https://pkg.cppget.org/1/stable
+manifest                # add 'depends: libhello ^1.0.0'
+buildfile               # import libhello
+hello.cxx               # use libhello
 \
 
-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:
+With a new dependency added, let's check the status of our project:
 
 \
-$ ls -1F
-build/
-hello-1.0.0/
-libhello-1.0.0/
-buildfile
-hello-1.0.0.tar.gz
-libhello-1.0.0.tar.gz
+$ bdep status
+fetching pkg:cppget.org/stable (prerequisite of dir:/tmp/hello)
+warning: authenticity of the certificate for pkg:cppget.org/stable
+         cannot be established
+certificate is for cppget.org, \"Code Synthesis\" <admin@cppget.org>
+certificate SHA256 fingerprint:
+86:BA:D4:DE:2C:87:1A:EE:38:<...>:5A:EA:F4:F7:8C:1D:63:30:C6
+trust this certificate? [y/n] y
+
+hello configured 0.1.0-a.0.19700101000000
+      available  0.1.0-a.0.19700101000000#1
 \
 
-And if we look inside \c{hello-1.0.0/} we will see what looks like the
-\c{hello} program:
+The \l{bdep-status(1)} command has detected that the dependency information
+has changed and tells us that a new \i{iteration} of our project (that \c{#1})
+is now available for \i{synchronization} with the build configuration.
+
+We've also been prompted to authenticate the prerequisite repository. This
+will have to happen once for every build configuration we initialize our
+project in and can quickly become tedious. To overcome this, we can mention
+the certificate fingerprint that we wish to automatically trust in the
+\c{repositories.manifest} file (replace it with the actual fingerprint from
+the repository's about page):
 
 \
-$ ls -1F hello-1.0.0/
-build/
-buildfile
-hello*
-hello.d
-hello.cxx
-hello.o
-hello.o.d
-manifest
-test.out
-version
+role: prerequisite
+location: https://pkg.cppget.org/1/stable
+trust: 86:BA:D4:DE:2C:87:1A:EE:38:<...>:5A:EA:F4:F7:8C:1D:63:30:C6
+\
 
-$ hello-1.0.0/hello
-usage: hello <name>...
+To synchronize a project with one or more build configurations we use the
+\l{bdep-sync(1)} command:
 
-$ hello-1.0.0/hello World
-Hello, World!
+\
+$ bdep sync
+synchronizing:
+  new libhello/1.0.0 (required by hello)
+  upgrade hello/0.1.0-a.0.19700101000000#1
 \
 
-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!
+Or we could just build the project without an explicit \c{sync} \- if
+necessary, it will be automatically synchronized:
+
+\
+$ b
+synchronizing:
+  new libhello/1.0.0 (required by hello)
+  upgrade hello/0.1.0-a.0.19700101000000#1
+c++ ../hello-gcc/libhello-1.0.0/libhello/cxx{hello}
+ld ../hello-gcc/libhello-1.0.0/libhello/libs{hello}
+c++ hello/cxx{hello}@../hello-gcc/hello/hello/
+ld ../hello-gcc/hello/hello/exe{hello}
+ln ../hello-gcc/hello/hello/exe{hello} -> hello/
 \
 
-Notice that \c{ld} line above \- this is where our executable is re-linked
-with the \c{-rpath} option.
+The synchronization as performed by the \c{sync} command is two-way:
+dependency packages are first added, removed, upgraded, or downgraded in build
+configurations according to the project's version constraints and user
+input. Then the actual versions of the dependencies present in the build
+configurations are recorded in the project's \c{lockfile} so that if desired,
+the build can be reproduced exactly. \N{The \c{lockfile} functionality is not
+yet implemented.} For a new dependency the latest available version that
+satisfies the version constraint is used.
+
+\N|Synchronization is also the last step in the \l{bdep-init(1)} command's
+logic.|
 
-We can also uninstall what we have installed with \l{bpkg-pkg-uninstall(1)
-\c{bpkg uninstall}}:
+Let's now examine the status in all (\c{--all|-a}) the build configurations
+and include the immediate dependencies (\c{--immediate|-i}):
 
 \
-$ bpkg uninstall                  \
-  config.install.root=/opt/hello  \
-  config.install.sudo=sudo        \
-  hello
+$ bdep status -ai
+in configuration @gcc:
+hello configured 0.1.0-a.0.19700101000000#1
+  libhello ^1.0.0 configured 1.0.0
 
-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
+in configuration @clang:
+hello configured 0.1.0-a.0.19700101000000
+      available 0.1.0-a.0.19700101000000#1
+\
+
+Since we didn't specify a configuration explicitly, only the default (\c{gcc})
+was synchronized. Normally, you would try a new dependency in one
+configuration, make sure everything looks good, then synchronize the rest with
+\c{--all|-a} (or, again, just build what you need directly). Here are a few
+examples (see \l{bdep-projects-configs(1)} for details):
 
-$ ls /opt/hello
-ls: cannot access /opt/hello: No such file or directory
+\
+$ bdep sync -a
+$ bdep sync @gcc @clang
+$ bdep sync -c ../hello-mingw
 \
 
-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.
+To get rid of a dependency, we simply remove it from the \c{manifest} file
+and synchronize the project. For example, assuming \c{libhello} is no longer
+mentioned as a dependency in our \c{manifests}:
 
-In fact, let's just start writing our own version of the \c{hello} program
-and see how it goes:
+\
+$ bdep status
+hello configured 0.1.0-a.0.19700101000000#1
+      available  0.1.0-a.0.19700101000000#2
 
+$ bdep sync
+synchronizing:
+  drop libhello/1.0.0 (unused)
+  upgrade hello/0.1.0-a.0.19700101000000#2
 \
-$ mkdir hello2
-$ cd hello2
 
-$ cat >hello.cpp
 
-#include <libhello/hello>
+\h#guide-upgrade-downgrade-deps|Upgrading and Downgrading Dependencies|
 
-int main ()
-{
-  hello::say (\"World\");
-}
+Let's say we would like to try that \c{1.1.0} version we have seen in
+the \c{libhello} \c{git} repository. First, we need to add the
+repository to the \c{repositories.manifest} file:
 
 \
+role: prerequisite
+location: https://git.build2.org/hello/libhello.git
+\
 
-What build system shall we use? I can't believe you are even asking this
-question...
+\N|Note that we don't need the \c{trust} value since \c{git} repositories
+are not authenticated.|
 
-\
-$ mkdir build
+To refresh the list of available dependency versions we use the
+\l{bdep-fetch(1)} command (or the \c{--fetch|-f} option to \c{status}):
 
-$ cat >build/bootstrap.build
+\
+$ bdep fetch
+$ bdep status libhello
+libhello configured 1.0.0 available [1.1.0]
+\
 
-project = hello2              # project name
-using config                  # config module (those config.*)
+To upgrade (or downgrade) dependencies we again use the \l{bdep-sync(1)}
+command. We can upgrade one or more specific dependencies by listing them
+as arguments to \c{sync}:
 
-$ cat >build/root.build
+\
+$ bdep sync libhello
+synchronizing:
+  new libformat/1.0.0 (required by libhello)
+  new libprint/1.0.0 (required by libhello)
+  upgrade libhello/1.1.0
+  upgrade hello/0.1.0-a.0.19700101000000#3
+\
 
-cxx.std = 11                  # C++ standard
-using cxx                     # C++ module
-cxx{*}: extension = cpp       # C++ source file extension
+Without an explicit version or the \c{--patch|-p} option, \c{sync} will
+upgrade the specified dependencies to the latest available versions. For
+example, if we don't like version \c{1.1.0}, we can downgrade it back to
+\c{1.0.0} by specifying the version explicitly (we pass \c{--old-available|-o}
+to \c{status} to see the old versions):
 
-$ cat >buildfile
+\
+$ bdep status -o libhello
+libhello configured 1.1.0 available (1.1.0) [1.0.0]
 
-import libs = libhello%lib{hello}
-exe{hello}: cxx{hello} $libs
+$ bdep sync libhello/1.0.0
+synchronizing:
+  drop libprint/1.0.0 (unused)
+  drop libformat/1.0.0 (unused)
+  downgrade libhello/1.0.0
+  reconfigure hello/0.1.0-a.0.19700101000000#3
 \
 
-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).
+\N|The available versions are listed in the descending order with \c{[]}
+indicating that the version is only available as a dependency and \c{()}
+marking the current version.|
 
-To recap, these are the contents of our project so far:
+Instead of specific dependencies we can also upgrade (\c{--upgrade|-u}) or
+patch (\c{--patch|-p}) immediate (\c{--immediate|-i}) or all
+(\c{--recursive|-r}) dependencies of our project.
+
+As a more realistic example, version \c{1.1.0} of \c{libhello} depends on two
+other libraries: \c{libformat} and \c{libprint}. Here is our project's
+dependency tree while we were still using that version:
 
 \
-$ tree -F
-.
-├── build/
-│   ├── bootstrap.build
-│   └── root.build
-├── buildfile
-└── hello.cpp
+$ bdep status -r
+hello configured 0.1.0-a.0.19700101000000#3
+  libhello ^1.0.0 configured 1.1.0
+    libformat ^1.0.0 configured 1.0.0
+    libprint ^1.0.0 configured 1.0.0
 \
 
-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).
+A typical conservative dependency management workflow would look like this:
 
 \
-$ 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{./}
+$ bdep status -fi  # refresh and examine immediate dependencies
+hello configured 0.1.0-a.0.19700101000000#3
+  libhello configured 1.1.0 available [2.0.0] [1.2.0] [1.1.2] [1.1.1]
+
+$ bdep sync -pi    # upgrade immediate to latest patch version
+synchronizing:
+  upgrade libhello/1.1.2
+  reconfigure hello/0.1.0-a.0.19700101000000#3
+continue? [Y/n] y
 \
 
-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.
+Notice that in case of such mass upgrades you are prompted for confirmation
+before anything is actually changed (unless you pass \c{--yes|-y}).
+
+In contrast, the following would be a fairly aggressive workflow where we
+upgrade everything to the latest available version (version constraints
+permitting; here we assume \c{^1.0.0} was used for all the dependencies):
 
 \
-$ b config.cxx=g++-5 \
-    config.import.libhello=/tmp/hello-gcc5-release
-c++ cxx{hello}
-ld exe{hello}
+$ bdep status -fr  # refresh and examine all dependencies
+hello configured 0.1.0-a.0.19700101000000#3
+  libhello configured 1.1.0 available [2.0.0] [1.2.0] [1.1.1]
+    libprint configured 1.0.0 available [2.0.0] [1.1.0] [1.0.1]
+    libformat configured 1.0.0 available [2.0.0] [1.1.0] [1.0.1]
+
+$ bdep sync -ur    # upgrade all to latest available version
+synchronizing:
+  upgrade libprint/1.1.0
+  upgrade libformat/1.1.0
+  upgrade libhello/1.2.0
+  reconfigure hello/0.1.0-a.0.19700101000000#3
+continue? [Y/n] y
 \
 
-Almost magic. Let's see what we've got:
+We can also have something in between: patch all (\c{sync\ -pr}), upgrade
+immediate (\c{sync\ -ui}), or even upgrade immediate and patch the rest
+(\c{sync\ -ui} followed by \c{sync\ -pr}).
 
-\
-$ tree -F
-.
-├── build/
-│   ├── bootstrap.build
-│   └── root.build
-├── buildfile
-├── hello*
-├── hello.d
-├── hello.cpp
-├── hello.o
-└── hello.o.d
 
-$ ./hello
-Hello, World!
-\
+\h#guide-versioning-releasing|Versioning and Release Management|
+
+Let's now discuss versioning and release management and, yes, that
+strange-looking \c{0.1.0-a.0.19700101000000} we keep seeing. While a build
+system project doesn't need a version and a \c{bpkg} package can use custom
+versioning schemes (see \l{bpkg#package-version Package Version}), a project
+managed by \c{bdep} must use \i{standard versioning}. \N{A dependency, which
+is a \c{bpkg} package, need not use standard versioning.}
+
+Standard versioning (\i{stdver}) is a \l{https://semver.org semantic
+versioning} (\i{semver}) scheme with a more precisely defined pre-release
+component and without any build metadata.
+
+\N|If you believe that \i{semver} is just \c{\i{major}.\i{minor}.\i{patch}},
+then in your worldview \i{stdver} would be the same as \i{semver}. In reality,
+\i{semver} also allows loosely defined pre-release and build metadata
+components. For example, \c{1.2.3-beta.1+build.23456} is a valid \i{semver}.|
+
+A standard version has the following form:
+
+\c{\i{major}\b{.}\i{minor}\b{.}\i{patch}[\b{-}\i{prerel}]}
+
+The \ci{major}, \ci{minor}, and \ci{patch} components have the same meaning as
+in \i{semver}. The \ci{prerel} component is used to provide \i{continuous
+versioning} of our project between releases. Specifically, during development
+of a new version we may want to publish several pre-releases, for example,
+alpha or beta. In between those we may also want to publish a number of
+snapshots, for example, for CI. With continuous versioning all these releases,
+pre-releases, and snapshots are assigned unique, properly ordered versions.
+
+\N|Continuous versioning is a cornerstone of the \c{build2} project dependency
+management. In case of snapshots, an appropriate version is assigned
+automatically in cooperation with your VCS.|
+
+The \ci{prerel} component for a pre-release has the following form:
+
+\c{(\b{a}|\b{b})\b{.}\i{num}}
 
-Let's change something in our source code and try to update:
+Here \cb{a} stands for alpha, \cb{b} stands for beta, and \ci{num} is the
+alpha/beta number. For example:
 
 \
-$ touch hello.cpp
+1.1.0        # final              release  for 1.1.0
+1.2.0-a.1    # first  alpha   pre-release  for 1.2.0
+1.2.0-a.2    # second alpha   pre-release  for 1.2.0
+1.2.0-b.1    # first  beta    pre-release  for 1.2.0
+1.2.0        # final              release  for 1.2.0
+\
 
-$ 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{./}
+The \ci{prerel} component for a snapshot has the following form:
+
+\c{(\b{a}|\b{b})\b{.}\i{num}\b{.}\i{snapsn}[\b{.}\i{snapid}]}
+
+Where \ci{snapsn} is the snapshot sequence number and \ci{snapid} is
+the snapshot id. In case of \c{git}, \ci{snapsn} is the commit timestamp
+in the \c{YYYYMMDDhhmmss} form and UTC timezone while \ci{snapid} is
+a 12-character abbreviated commit id. For example:
+
+\
+1.2.3-a.1.20180319215815.26efe301f4a7
 \
 
-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:
+Notice also that a snapshot version is ordered \i{after} the corresponding
+pre-release version. That is, \c{1.2.3-a.1\ <\ 1.2.3-a.1.1}. As a result, it
+is customary to start the development of a new version with \c{X.Y.Z-a.0.z},
+that is, a snapshot after the (non-existent) zero'th alpha release. \N{We will
+explain the meaning of \cb{z} in this version momentarily.} The following
+chronologically-ordered versions illustrate a typical release flow of a
+project that uses \c{git} as its VCS:
 
 \
-$ cd ..
-$ mkdir hello2-gcc5-release
-$ ls -1F
-hello2/
-hello2-gcc5-release/
+0.1.0-a.0.19700101000000               # snapshot (no commits yet)
+0.1.0-a.0.20180319215815.26efe301f4a7  # snapshot (first commit)
+...                                    # more commits/snapshots
+0.1.0-a.1                              # pre-release (first alpha)
+0.1.0-a.1.20180319221826.a6f0f41205b8  # snapshot
+...                                    # more commits/snapshots
+0.1.0-a.2                              # pre-release (second alpha)
+0.1.0-a.2.20180319231937.b701052316c9  # snapshot
+...                                    # more commits/snapshots
+0.1.0-b.1                              # pre-release (first beta)
+0.1.0-b.1.20180319242038.c812163417da  # snapshot
+...                                    # more commits/snapshots
+0.1.0                                  # release
+0.2.0-a.0.20180319252139.d923274528eb  # snapshot (first in 0.2.0)
+...
+\
+
+For a more detailed discussion of standard versioning and its support in
+\c{build2} refer to \l{b#module-version Version Module}.
 
-$ b config.cxx=g++-5                             \
-  config.cc.coptions=-O3                         \
-  config.import.libhello=/tmp/hello-gcc5-release \
-  'configure(hello2/@hello2-gcc5-release/)'
+Let's now see how this works in practice by publishing a couple of versions
+for our \c{hello} project. By now it should be clear what that
+\c{0.1.0-a.0.19700101000000} means \- it is the first snapshot version of our
+project. Since there are no commits yet, it has the UNIX epoch as its commit
+timestamp. As the first step, let's try to commit our project and see what
+changes:
+
+\
+$ git add .
+$ git commit -m \"Start hello project\"
 
-mkdir -p hello2-gcc5-release/build/
-save hello2-gcc5-release/build/config.build
+$ bdep status
+hello configured 0.1.0-a.0.19700101000000
+      available  0.1.0-a.0.20180507062614.ee006880fc7e
 \
 
-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...
+Just like with changes to dependency information, \c{status} has detected that
+a new (snapshot) version of our project is available for synchronization.
 
-Once the configuration is saved, we can develop our project without any
-annoyance:
+\N|Another way to view the project's version (which works even if we are
+not using \c{bdep}) is with the build system's \c{info} operation:
 
 \
-$ b hello2-gcc5-release/
-c++ hello2/cxx{hello}
-ld hello2-gcc5-release/exe{hello}
+$ b info
+project: hello
+version: 0.1.0-a.0.20180507062614.ee006880fc7e
+summary: hello executable project
+...
+\
 
-$ cd hello2-gcc5-release/
+|
 
-$ b
-info: dir{./} is up to date
+Let's synchronize with the default build configuration:
 
-$ b clean
-rm exe{hello}
-rm obje{hello}
+\
+$ bdep sync
+synchronizing:
+  upgrade hello/0.1.0-a.0.20180507062614.ee006880fc7e
 
-$ 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
+$ bdep status
+hello configured 0.1.0-a.0.20180507062614.ee006880fc7e
 \
 
-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:
+\N|Notice that we didn't have to manually change the version anywhere. All we
+had to do was commit our changes and a new snapshot version was automatically
+derived by \c{build2} from the new \c{git} commit. Without this automation
+continuous versioning would hardly be practical.|
 
+If we now make another commit, we will see a similar picture:
+
+\
+$ bdep status
+hello configured 0.1.0-a.0.20180507062614.ee006880fc7e
+      available  0.1.0-a.0.20180507062615.8fb9de05b38f
 \
-$ 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
+\N|Note that you don't need to manually run \c{sync} after every commit. As
+discussed earlier, you can simply run the build system to update your project
+and things will get automatically synchronized if necessary.|
 
-$ b /tmp/hello-gcc5-release/hello2/
-c++ hello2/cxx{hello}@/tmp/hello-gcc5-release/hello2/
-ld /tmp/hello-gcc5-release/hello2/exe{hello}
+Ok, time for our first release. Let's start with \c{0.1.0-a.1}. Unlike
+snapshots, for pre-releases as well as final releases we have to update the
+version in the \c{manifest} file manually:
+
+\
+version: 0.1.0-a.1
 \
 
-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.
+\N|The \c{manifest} file is the singular place where we specify the package
+version. The build system's \l{b#module-version \c{version} module} makes it
+available in various forms in buildfiles and even source code.|
+
+To ensure continuous versioning, this change to version must be the last commit
+for this (pre-)release which itself must be immediately followed by a second
+change to the version starting the development of the next (pre-)release. We
+also recommend that you tag the release commit with a tag name in the
+\c{\b{v}\i{X}.\i{Y}.\i{Z}} form.
+
+\N|Having regular release tag names with the \cb{v} prefix allows one to
+distinguish them from other tags, for example, with wildcard patterns.|
 
-Of course, \c{bpkg} has no idea \c{hello2} is now part of its configuration:
+Here is the release workflow for our example:
 
 \
-$ bpkg status -d /tmp/hello-gcc5-release/ hello2
-unknown
+$ git commit -a -m \"Release version 0.1.0-a.1\"
+$ git tag -a v0.1.0-a.1 -m \"Tag version 0.1.0-a.1\"
+$ git push --follow-tags
+
+# Version 0.1.0-a.1 is now public.
+
+$ edit manifest  # change 'version: 0.1.0-a.1.z'
+$ git commit -a -m \"Change version to 0.1.0-a.1.z\"
+$ git push
+
+# Master is now open for business.
 \
 
-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.
+\N|In the future release management will be automated with a
+\c{bdep-release(1)} command.|
 
-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.
+Notice also that when specifying a snapshot version in \c{manifest} we use the
+special \cb{z} snapshot value (for example, \c{0.1.0-a.1.z}) which is
+recognized and automatically replaced by \c{build2} with, in case of \c{git},
+a commit timestamp and id (refer to \l{b#module-version Version Module} for
+details).
 
-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:
+Publishing the final release is exactly the same. For completeness, here
+are the commands:
 
 \
-$ 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
+$ edit manifest  # change 'version: 0.1.0'
+$ git commit -a -m \"Release version 0.1.0\"
+$ git tag -a v0.1.0 -m \"Tag version 0.1.0\"
+$ git push --follow-tags
+
+$ edit manifest  # change 'version: 0.2.0-a.0.z'
+$ git commit -a -m \"Change version to 0.2.0-a.0.z\"
+$ git push
 \
 
-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/}:
+\N|One sticky point of continuous versioning is choosing the next version.
+For example, above should we continue with \c{0.1.1-a.0}, \c{0.2.0-a.0},
+or \c{1.0.0-a.0}? The important rule to keep in mind is that we can jump
+forward to any further version at any time and without breaking continuous
+versioning. But we can never jump backwards.
+
+For example, we can start with \c{0.2.0-a.0} but if we later realize that this
+will actually be a new major release, we can easily change it to
+\c{1.0.0-a.0}. As a result, the general recommendation is to start
+conservatively by either incrementing the patch or the minor version
+component. The recommended strategy is to increment the minor component and,
+if required, release patch versions from a separate branch (created by
+branching off from the release commit).
+
+Note also that you don't have to make any pre-releases if you don't need them.
+While during development you would still keep the version as \c{X.Y.Z-a.0}, at
+release you simply change it directly to the final \c{X.Y.Z}.|
+
+When publishing the final release you may also want to clean up now
+obsolete pre-release tags. For example:
 
 \
-$ 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/
+$ git tag -l 'v0.1.0-*' | xargs git push --delete origin
+$ git tag -l 'v0.1.0-*' | xargs git tag --delete
 \
 
-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):
+\N|While at first removing such tags may seem like a bad idea, pre-releases
+are by nature temporary and their use only makes sense until the final release
+is published.
+
+Also note that having a \c{git} repository with a large number of published
+but unused version tags may result in a significant download overhead.|
+
+Let's also briefly discuss in which situations we should increment each of the
+version components. While \i{semver} gives basic guidelines, there are several
+ways to apply them in the context of C/C++ where there is a distinction
+between binary and source compatibility. We recommend that you reserve
+\i{patch} releases for specific bug fixes and security issues that you can
+guarantee with a high level of certainty to be binary-compatible. Otherwise,
+if the changes are source-compatible, increment \i{minor}. And if they are
+breaking (that is, the user code likely will need adjustments), increment
+\i{major}. During early development, when breaking changes are frequent, it is
+customary to use the \c{0.Y.Z} versions where \c{Y} effectively becomes the
+\i{major} component. Again, refer to the \l{b#module-version Version Module}
+for a more detailed discussion of this topic.
+
+\h#guide-consume-pkg|Package Consumption|
+
+Ok, now that we have published a few releases of \c{hello}, how would the
+users of our project get them? While they could clone the repository and use
+\c{bdep} just like we did, this is more of a development rather than
+consumption workflow. For consumption it is much easier to use the package
+dependency manager, \l{bpkg(1)}, directly.
+
+First, we create a suitable build configuration with the
+\l{bpkg-cfg-create(1)} command. We can use the same place for building all our
+tools so let's call the directory \c{tools}. Seeing that we are only
+interested in using (rather than developing) such tools, let's build them
+optimized and also configure a suitable installation location:
 
 \
-$ 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
+$ bpkg create -d tools cc        \
+  config.cxx=g++                 \
+  config.cc.coptions=-O3         \
+  config.install.root=/usr/local \
+  config.install.sudo=sudo
+created new configuration in /tmp/tools/
+
+$ cd tools
 \
 
-Let's upgrade \c{libhello} and see what happens:
+\N|The \c{bdep} build configurations we were creating with \c{init\ -C} are
+actually \c{bpkg} build configurations. In fact, underneath, \l{bdep-init(1)}
+calls \l{bpkg-cfg-create(1)}.|
+
+To fetch and build packages (as well as all their dependencies) we use the
+\l{bpkg-pkg-build(1)} command. We can use either an archive-based repository
+like \l{https://cppget.org cppget.org} or build directly from \c{git}:
 
 \
-$ 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)
+$ bpkg build hello@https://git.build2.org/hello/hello.git
+fetching from https://git.build2.org/hello/hello.git
+  new libformat/1.0.0 (required by libhello)
+  new libprint/1.0.0 (required by libhello)
+  new libhello/1.1.0 (required by hello)
+  new hello/1.0.0
 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
+configured hello/1.0.0
+c++ libprint-1.0.0/libprint/cxx{print}
+c++ hello-1.0.0/hello/cxx{hello}
+c++ libhello-1.1.0/libhello/cxx{hello}
+c++ libformat-1.0.0/libformat/cxx{format}
+ld libprint-1.0.0/libprint/libs{print}
+ld libformat-1.0.0/libformat/libs{format}
+ld libhello-1.1.0/libhello/libs{hello}
+ld hello-1.0.0/hello/exe{hello}
+updated hello/1.0.0
+\
+
+\N|Passing a repository URL to the \c{build} command is a shortcut to the
+following sequence of commands:
+
 \
+$ bpkg add https://git.build2.org/hello/hello.git  # add repository
+$ bpkg fetch                             # fetch package list
+$ bpkg build hello                       # build package by name
+\
+
+|
 
-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:
+Once built, we can install the package to the location that we have specified
+with \c{config.install.root} using the \l{bpkg-pkg-install(1)} command:
 
 \
-$ 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
+$ bpkg install hello
+...
+install libformat-1.0.0/libformat/libs{format}
+install libprint-1.0.0/libprint/libs{print}
+install libhello-1.1.0/libhello/libs{hello}
+install hello-1.0.0/hello/exe{hello}
 
-$ /tmp/hello-gcc5-release/hello2-1.0.0/hello
+$ hello World
 Hello, World!
 \
 
-To finish off, let's see how hard it will be to get a Clang build going:
+\N|If on your system the installed executables don't run from \c{/usr/local}
+because of the unresolved shared libraries (or if you are installing somewhere
+else, such as \c{/opt}), then the easiest way to fix this is with \i{rpath}.
+Simply add the following configuration variable when creating the build
+configuration (or as an argument to the \c{install} command):
 
 \
-$ cd /tmp
-$ mkdir hello-clang36-release
-$ cd hello-clang36-release
+config.bin.rpath=/usr/local/lib
+\
 
-$ 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
+If we need to uninstall a previously installed package, there is the
+\l{bpkg-pkg-uninstall(1)} command:
 
-$ 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
+\
+$ bpkg uninstall hello
+uninstall hello-1.0.0/hello/exe{hello}
+uninstall libhello-1.1.0/libhello/libs{hello}
+uninstall libprint-1.0.0/libprint/libs{print}
+uninstall libformat-1.0.0/libformat/libs{format}
+...
 \
 
-Are you still there? Ok, one last example. Let's see how hard it is to
-cross-compile.
+To upgrade or downgrade packages we again use the \c{build} command. Here
+is a typical upgrade workflow:
 
 \
-$ mkdir hello-mingw64
-$ cd hello-mingw64
+$ bpkg fetch              # refresh available package list
+$ bpkg status             # see if new versions are available
 
-$ bpkg create cc config.cxx=x86_64-w64-mingw32-g++
-created new configuration in /tmp/hello-mingw64/
+$ bpkg uninstall hello    # uninstall old version
+$ bpkg build     hello    # upgrade to the latest version
+$ bpkg install   hello    # install new version
+\
 
-$ bpkg add https://build2.org/pkg/1/hello/stable
-added repository build2.org/hello/stable
+Similar to \c{bdep}, to downgrade we have to specify the desired version
+explicitly. There are also the \c{--upgrade|-u} and \c{--patch|-p} as well as
+\c{--immediate|-i} and \c{--recursive|-r} options that allow us to upgrade or
+patch packages that we have built and/or their immediate or all dependencies
+(see \l{bpkg-pkg-build(1)} for details). For example, to make sure everything
+is patched, run:
 
+\
 $ 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!
+$ bpkg build -pr
 \
 
-In fact, on a properly setup GNU/Linux machine (that automatically uses
-\c{wine} as an \c{.exe} interpreter) we can even run tests:
+If a package is no longer needed, we can remove it from the configuration with
+\l{bpkg-pkg-drop(1)}:
 
 \
-$ 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
+$ bpkg drop hello
+following dependencies were automatically built but
+will no longer be used:
+  libhello
+  libformat
+  libprint
+drop unused packages? [Y/n] y
+  drop hello
+  drop libhello
+  drop libformat
+  drop libprint
+continue? [Y/n] y
+purged hello
+purged libhello
+purged libformat
+purged libprint
 \
 "
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
+\
+"
diff --git a/doc/intro2.cli b/doc/intro2.cli
deleted file mode 100644
index bb10b1d..0000000
--- a/doc/intro2.cli
+++ /dev/null
@@ -1,1390 +0,0 @@
-// file      : doc/intro2.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
-// @@ Could we use a nicer font, seeing that we embed them?
-//
-
-// NOTES
-//
-// - Maximum <pre> line is 70 characters.
-//
-
-"
-\h1#tldr|TL;DR|
-
-\
-$ git clone ssh://example.org/hello.git
-$ tree hello
-hello/
-├── hello/
-│   ├── hello.cxx
-│   └── buildfile
-├── manifest
-└── repositories.manifest
-
-$ cd hello
-$ bdep init --config-create ../hello-gcc cc config.cxx=g++
-initializing project /tmp/hello/
-created configuration /tmp/hello-gcc/ (default, auto-synchronized)
-synchronizing:
-  new hello/0.1.0
-
-$ b
-c++ hello/cxx{hello}@../hello-gcc/hello/hello/
-ld ../hello-gcc/hello/hello/exe{hello}
-ln ../hello-gcc/hello/hello/exe{hello} -> hello/
-
-$ hello/hello World
-Hello, World!
-
-$ edit repositories.manifest   # add https://example.org/libhello.git
-$ edit manifest                # add 'depends: libhello ^1.0.0'
-$ edit hello/buildfile         # import libhello
-$ edit hello/hello.cxx         # use libhello
-
-$ b
-fetching from https://example.org/libhello.git
-synchronizing /tmp/hello-gcc/:
-  new libhello/1.0.0 (required by hello)
-  reconfigure hello/0.1.0
-c++ ../hello-gcc/libhello-1.0.0/libhello/cxx{hello}
-ld ../hello-gcc/libhello-1.0.0/libhello/libs{hello}
-c++ hello/cxx{hello}@../hello-gcc/hello/hello/
-ld ../hello-gcc/hello/hello/exe{hello}
-ln ../hello-gcc/hello/hello/exe{hello} -> hello/
-
-$ bdep fetch                   # refresh available versions
-$ bdep status -i               # review available versions
-hello configured 0.1.0
-  libhello ^1.0.0 configured 1.0.0 available [1.1.0]
-
-$ bdep sync libhello           # upgrade to latest
-synchronizing:
-  new libformat/1.0.0 (required by libhello)
-  new libprint/1.0.0 (required by libhello)
-  upgrade libhello/1.1.0
-  reconfigure hello/0.1.0
-
-$ bdep sync libhello/1.0.0     # downgrade
-synchronizing:
-  drop libprint/1.0.0 (unused)
-  drop libformat/1.0.0 (unused)
-  downgrade libhello/1.0.0
-  reconfigure hello/0.1.0
-\
-
-\h1#guide|Getting Started Guide|
-
-The aim of this guide is to get you started developing C/C++ projects with the
-\c{build2} toolchain. All the examples in this section include the relevant
-command output so if you just want to get a sense of what \c{build2} is about,
-then you don't have to install the toolchain and run the commands in order to
-follow along. If at the end you find \c{build2} appealing and would like to
-start using it or try the examples for yourself, you can jump straight to
-\l{build2-toolchain-install.xhtml The \c{build2} Toolchain Installation and
-Upgrade}.
-
-One of the primary goals of the \c{build2} toolchain is to provide a uniform
-interface across all the platforms and compilers. While the examples in this
-document assume a UNIX-like operation system, they will look pretty similar if
-you are on Windows. You just have to use appropriate paths, compilers, and
-options.
-
-The question we will try to answer in this section can be summarized as:
-
-\
-$ git clone .../hello.git && now-what?
-\
-
-That is, we clone an existing C/C++ project or would like to create a new one
-and then start hacking on it. We want to spend as little time and energy as
-possible on the initial and ongoing infrastructure maintenance: setting up
-build configurations, managing dependencies, continuous integration and
-testing, release management, etc. Or, as one C++ user aptly put it, \"\i{All I
-want to do is program.}\"
-
-\h#guide-hello|Hello, World|
-
-Let's see what programming with \c{build2} feels like by starting with a
-customary \i{\"Hello, World!\"} program (here we assume our current working
-directory is \c{/tmp}):
-
-\
-$ bdep new -t exe -l c++ hello
-created new executable project hello in /tmp/hello/
-\
-
-The \l{bdep-new(1)} command creates a \i{canonical} \c{build2} project. In
-our case it is an executable implemented in C++.
-
-\N|To create a library, pass \c{-t\ lib}. By default \c{new} also initializes
-a \c{git} repository and generates suitable \c{.gitignore} files (pass \c{-s\
-none} if you don't want that).|
-
-Let's take a look inside our new project:
-
-\
-$ tree hello
-hello/
-├── .git/
-├── .bdep/
-├── build/
-├── hello/
-│   ├── hello.cxx
-│   ├── buildfile
-│   └── testscript
-├── buildfile
-├── manifest
-└── repositories.manifest
-\
-
-\N|While the canonical project structure is strongly recommended, especially
-for new projects, \c{build2} is flexible enough to allow most commonly used
-arrangements.|
-
-Similar to version control tools, we normally run all \c{build2} tools from
-the project's source directory or one of its subdirectories, so:
-
-\
-$ cd hello
-\
-
-While the project layout is discussed in more detail in later sections, let's
-examine a couple of interesting files to get a sense of what's going on. We
-start with the source file which should look familiar:
-
-\
-$ cat hello/hello.cxx
-
-#include <iostream>
-
-using namespace std;
-
-int main (int argc, char* argv[])
-{
-  if (argc < 2)
-  {
-    cerr << \"error: missing name\" << endl;
-    return 1;
-  }
-
-  cout << \"Hello, \" << argv[1] << '!' << endl;
-}
-\
-
-\N|If you prefer the \c{.?pp} extensions over \c{.?xx} for your C++ source
-files, pass \c{-l\ c++,cpp} to the \c{new} command. See \l{bdep-new(1)} for
-details on this and other customization options.|
-
-Let's take a look at the accompanying \c{buildfile}:
-
-\
-$ cat hello/buildfile
-
-libs =
-#import libs += libhello%lib{hello}
-
-exe{hello}: {hxx ixx txx cxx}{*} $libs test{testscript}
-\
-
-As the name suggests, this file describes how to build things. While its
-content might look a bit cryptic, let's try to infer a couple of points
-without going into too much detail (the details are discussed in the following
-sections). That \c{exe{hello\}} on the left of \c{:} is a \i{target}
-(executable named \c{hello}) and what we have on the right are
-\i{prerequisites} (C++ source files, libraries, etc). This \c{buildfile} uses
-\l{b#name-patterns wildcard patterns} (that \c{*}) to automatically locate all
-the C++ source files. This means we don't have to edit our \c{buildfile} every
-time we add a source file to our project. There also appears to be some
-(commented out) infrastructure for importing and linking libraries (that
-\c{libs} variable). We will see how to use it in a moment. Finally, the
-\c{buildfile} also lists \c{testscript} as a prerequisite of \c{hello}. This
-file tests our target. Let's take a look inside:
-
-\
-$ cat hello/testscript
-
-: basics
-:
-$* 'World' >'Hello, World!'
-
-: missing-name
-:
-$* 2>>EOE != 0
-error: missing name
-EOE
-\
-
-Again, we are not going into detail here (see \l{testscript#intro Testscript
-Introduction} for a proper introduction), but to give you an idea, here we
-have two tests: the first (with id \c{basics}) verifies that our program
-prints the expected greeting while the second makes sure it handles the
-missing name error condition. Tests written in Testscript are concise,
-portable, and executed in parallel.
-
-Next up is \c{manifest}:
-
-\
-$ cat manifest
-: 1
-name: hello
-version: 0.1.0-a.0.z
-summary: hello executable project
-license: proprietary
-url: https://example.org/hello
-email: you@example.org
-#depends: libhello ^1.0.0
-\
-
-The \c{manifest} file is what makes a build system project a \i{package}. It
-contains all the metadata that a user of a package might need to know: its
-name, version, license, dependencies, etc., all in one place.
-
-\N|Refer to \l{bpkg#manifest-format Manifest Format} for the general format of
-\c{build2} manifest files and to \l{bpkg#manifest-package Package Manifest}
-for details on the package manifest values.|
-
-As you can see, \c{manifest} created by \l{bdep-new(1)} contains some dummy
-values which you would want to adjust before publishing your package. But
-let's resist the urge to adjust that strange looking \c{0.1.0-a.0.z} until we
-discuss package versioning.
-
-\N|Next to \c{manifest} you might have noticed the \c{repositories.manifest}
-file \- we will discuss its function later, when we talk about dependencies
-and where they come from.|
-
-Project in hand, let's build it. Unlike other programming languages, C++
-development usually involves juggling a handful of build configurations:
-several compilers and/or targets (\c{build2} is big on cross-compiling),
-debug/release, different sanitizers and/or static analysis tools, and so
-on. As a result, \c{build2} is optimized for multi-configuration
-usage. However, as we will see shortly, one build configuration can be
-designated as the default with additional conveniences.
-
-The \l{bdep-init(1)} command is used to initialize a project in a build
-configuration. As a shortcut, it can also create a new build configuration in
-the process, which is just what we need here. Let's start with GCC (remember
-we are in the project's root directory):
-
-\
-$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
-initializing project /tmp/hello/
-created configuration @gcc /tmp/hello-gcc/ (default, auto-synchronized)
-synchronizing:
-  new hello/0.1.0-a.0.19700101000000
-\
-
-The \cb{--create|-C} option instructs \c{init} to create a new configuration
-in the specified directory (\c{../hello-gcc} in our case). To make referring
-to configurations easier, we can give it a name, which is what we do with
-\c{@gcc}. The next argument (\c{cc}, stands for \i{C-common}) is the build
-system module we would like to configure. It implements compilation and
-linking rules for the C and C++ languages. Finally, \c{config.cxx=g++} is (one
-of) this module's configuration variables that specifies the C++ compiler we
-would like to use (the corresponding C compiler will be determined
-automatically). Let's for now also ignore that \c{synchronizing:...} bit along
-with strange-looking \c{19700101000000} in the version \- it will become clear
-what's going on here in a moment.
-
-Now the same for Clang:
-
-\
-$ bdep init -C ../hello-clang @clang cc config.cxx=clang++
-initializing project /tmp/hello/
-created configuration @clang /tmp/hello-clang/ (auto-synchronized)
-synchronizing:
-  new hello/0.1.0-a.0.19700101000000
-\
-
-If we check the parent directory, we should now see two build configurations
-next to our project:
-
-\
-$ ls ..
-hello/
-hello-gcc/
-hello-clang/
-\
-
-Things will also look pretty similar if you are on Windows instead of a
-UNIX-like operating system. For example, to initialize our project on Windows
-with Visual Studio, start the Visual Studio development command prompt and
-then run:
-
-\N|Currently we have to run \c{build2} tools from a suitable Visual Studio
-development command prompt. This requirement will likely be removed in the
-future.|
-
-\
-> bdep init -C ..\hello-debug @debug cc     ^
-  config.cxx=cl                             ^
-  \"config.cc.coptions=/MDd /Z7\"             ^
-  config.cc.loptions=/DEBUG
-
-> bdep init -C ..\hello-release @release cc ^
-  config.cxx=cl                             ^
-  config.cc.coptions=/O2
-\
-
-\N|Besides the \c{coptions} (compile options) and \c{loptions} (link options),
-other commonly used \c{cc} module configuration variables are \c{poptions}
-(preprocess options) and \c{libs} (extra libraries to link). We can also use
-their \c{config.c.*} (C compilation) and \c{config.cxx.*} (C++ compilation)
-variants if we only want them applied during the respective language
-compilation. For example:
-
-\
-$ bdep init ... cc       \
-  config.cxx=clang++     \
-  config.cc.coptions=-g  \
-  config.cxx.coptions=-stdlib=libc++
-\
-
-|
-
-One difference you might have noticed when creating the \c{gcc} and \c{clang}
-configurations above is that the first one was designated as the default. The
-default configuration is used by \c{bdep} commands if no configuration is
-specified explicitly (see \l{bdep-projects-configs(1)} for details). It is
-also the configuration that is used if we run the build system in the
-project's source directory. So, normally, you would make your every day
-development configuration the default. Let's try that:
-
-\
-$ bdep status
-hello configured 0.1.0-a.0.19700101000000
-
-$ b
-c++ hello/cxx{hello}@../hello-gcc/hello/hello/
-ld ../hello-gcc/hello/hello/exe{hello}
-ln ../hello-gcc/hello/hello/exe{hello} -> hello/
-
-$ b test
-test hello/test{testscript} ../hello-gcc/hello/hello/exe{hello}
-
-$ hello/hello World
-Hello, World!
-\
-
-In contrast, the Clang configuration has to be requested explicitly:
-
-\
-$ bdep status @clang
-hello configured 0.1.0-a.0.19700101000000
-
-$ b ../hello-clang/hello/
-c++ hello/cxx{hello}@../hello-clang/hello/hello/
-ld ../hello-clang/hello/hello/exe{hello}
-
-$ b test: ../hello-clang/hello/
-test hello/test{testscript} ../hello-clang/hello/hello/exe{hello}
-
-$ ../hello-clang/hello/hello/hello World
-Hello, World!
-\
-
-\N|To see the actual compilation command lines, run \c{b\ -v} and for even
-more details, run \c{b\ -V}. See \l{b(1)} for more information on these
-and other build system options.|
-
-While we are here, let's also check how hard it would be to cross-compile:
-
-\
-$ bdep init -C ../hello-mingw @mingw cc config.cxx=x86_64-w64-mingw32-g++
-initializing project /tmp/hello/
-created configuration @mingw /tmp/hello-mingw/ (auto-synchronized)
-synchronizing:
-  new hello/0.1.0-a.0.19700101000000
-
-$ b ../hello-mingw/hello/
-c++ hello/cxx{hello}@../hello-mingw/hello/hello/
-ld ../hello-mingw/hello/hello/exe{hello}
-\
-
-As you can see, cross-compiling in \c{build2} is nothing special. In our case,
-on a properly setup GNU/Linux machine (that automatically uses \c{wine} as an
-\c{.exe} interpreter) we can even run tests (in \c{build2} this is called
-\i{cross-testing}):
-
-\
-$ b test: ../hello-mingw/hello/
-test hello/test{testscript} ../hello-mingw/hello/hello/exe{hello}
-
-$ ../hello-mingw/hello/hello/hello.exe Windows
-Hello, Windows!
-\
-
-Let's review what it takes to initialize a project's infrastructure and
-perform the first build. For an existing project:
-
-\
-$ git clone .../hello.git
-$ cd hello
-$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
-$ b
-\
-
-For a new project:
-
-\
-$ bdep new -t exe -l c++ hello
-$ cd hello
-$ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
-$ b
-\
-
-If you prefer, the \c{new} and \c{init} steps can be combined into a single
-command:
-
-\
-$ bdep new -t exe -l c++ hello -C hello-gcc @gcc cc config.cxx=g++
-\
-
-Now is also a good time to get an overview of the \c{build2} toolchain. After
-all, we have already used two of its tools (\c{bdep} and \c{b}) without a
-clear understanding of what they actually are.
-
-Unlike most other programming languages that encapsulate the build system,
-package dependency manager, and project dependency manager into a single tool
-(such as Rust's \c{cargo} or Go's \c{go}), \c{build2} is a hierarchy of
-several tools that you will be using directly and which together with your
-version control system (VCS) will constitute the core of your project
-management toolset.
-
-\N|While \c{build2} can work without a VCS, this will result in reduced
-functionality.|
-
-At the bottom of the hierarchy is the build system, \l{b(1)}. Next comes the
-package dependency manager, \l{bpkg(1)}. It is primarily used for \i{package
-consumption} and depends on the build system. The top of the hierarchy is the
-project dependency manager, \l{bdep(1)}. It is used for \i{project
-development} and relies on \c{bpkg} for building project packages and their
-dependencies.
-
-\N|The main reason for this separation is modularity and the resulting
-flexibility: there are situations where we only need the build system (for
-example, when building a package for a system package manager where all the
-dependencies should be satisfied from the system repository), or only the
-build system and package manager (for example, when a build bot is building a
-package for testing).
-
-Note also that strictly speaking \c{build2} is not C/C++-specific; its build
-model is general enough to handle any DAG-based operations and its
-package/project dependency management can be used for any compiled language.|
-
-\N|As we will see in a moment, \c{build2} also integrates with your VCS in
-order to automate project versioning. Note that currently only \c{git(1)} is
-supported.|
-
-Let's now move on to the reason why there is \i{dep} in the \c{bdep} name:
-dependency management.
-
-
-\h#guide-repositories|Package Repositories|
-
-Say we have realized that writing \i{\"Hello, World!\"} programs is a fairly
-common task and that someone must have written a library to help with that. So
-let's see if we can find something suitable to use in our project.
-
-Where should we look? That's a good question. But before we can try to answer
-it, we need to understand where \c{build2} can source dependencies. In
-\c{build2} packages come from \i{package repositories}. Two commonly used
-repository types are \i{version control} and \i{archive}-based (see
-\l{bpkg-repository-types(1)} for details).
-
-As the name suggests, a version control-based repository uses a VCS as its
-distribution mechanism. \N{Currently, only \c{git} is supported.} Such a
-repository normally contains multiple versions of a single package or,
-perhaps, of a few related packages.
-
-An archive-based repository contains multiple, potentially unrelated
-packages/versions as archives along with some meta information (package list,
-prerequisite/complement repositories, signatures, etc) that are all accessible
-via HTTP(S).
-
-Version control and archive-based repositories have different
-trade-offs. Version control-based repositories are great for package
-developers: With services like GitHub they are trivial to setup. In fact, your
-project's (already existing) VCS repository will normally be the \c{build2}
-package repository \- you might need to add a few files, but that's about it.
-
-However, version control-based repositories are not without drawbacks: It will
-be hard for your users to discover your packages (try searching for \"hello
-library\" on GitHub \- most of the results are not even in C++ let alone
-packaged for \c{build2}). There is also the issue of continuous availability:
-users can delete their repositories, services may change their policies or go
-out of business, and so on. Version control-based repositories also lack
-repository authentication and package signing. Finally, obtaining the
-available package list for such repositories can be slow.
-
-A central, archive-based repository would address all these drawbacks: It
-would be a single place to search for packages. Published packages will never
-disappear and can be easily mirrored. Packages are signed and the repository
-is authenticated (see \l{bpkg-repository-signing(1)} for details). And, last,
-but not least, archive-based repositories are fast.
-
-\l{https://cppget.org cppget.org} is the \c{build2} community's central
-package repository (which we hope one day will become \i{the C++ package
-repository}). As an added benefit, packages on \l{https://cppget.org
-cppget.org} are continuously \l{https://cppget.org/?builds built and tested} on
-all the major platform/compiler combinations with the results available as
-part of the package description.
-
-\N|The main drawback of archive-based repositories is the setup cost. Getting
-a basic repository going is relatively easy \- all you need is an HTTP(S)
-server. Adding a repository web interface like that on \l{https://cppget.org
-cppget.org} will require running \l{https://cppget.org/brep \c{brep}}. And
-adding CI will require running a bunch of build bots
-(\l{https://cppget.org/bbot \c{bbot}}).|
-
-\N|CI support for version control-based repositories is a work in progress.|
-
-To summarize, version control-based repositories are great for package
-developers while a central, archive-based repository is convenient for package
-consumers. A reasonable strategy is then for package developers to publish
-their releases to a central repository. Package consumers can then decide
-which repository to use based on their needs. For example, one could use
-\l{https://cppget.org cppget.org} as a (fast, reliable, and secure) source of
-stable versions but also add, say, \c{git} repositories for select packages
-(perhaps with the \c{#HEAD} fragment filter to improve download speed) for
-testing development snapshots. In this model the two repository types
-complement each other.
-
-\N|Support for automated publishing of tagged releases to an archive-based
-repository is a work in progress.|
-
-Let's see how all this works in practice. Go over to \l{https://cppget.org
-cppget.org} and type \"hello library\" in the search box. At the top of the
-search result you should see the \l{https://cppget.org/libhello \c{libhello}}
-package and if you follow the link you will see the package description page
-along with a list of available versions. Pick a version that you like and you
-will see the package version description page with quite a bit of information,
-including the list of platform/compiler combinations that this version has
-been successfully (or unsuccessfully) tested with. If you like what you see,
-copy the \c{location} value \- this is the repository location where this
-package version can be sourced from.
-
-\N|The \l{https://cppget.org cppget.org} repository is split into several
-sections: \c{stable}, \c{testing}, \c{beta}, \c{alpha} and \c{legacy}, with
-each section having its own repository location (see the repository's
-\l{https://cppget.org/?about about} page for details on each section's
-policies). Note also that \c{testing} is complemented by \c{stable}, \c{beta}
-by \c{testing}, and so on, so you only need to choose the lowest stability
-level and you will automatically \"see\" packages from the more stable
-sections.|
-
-\N|The \l{https://cppget.org cppget.org} \c{stable} sections will always
-contain the \c{libhello} library version \c{1.0.X} that was generated using
-the following \l{bdep-new(1)} command line:
-
-\
-$ bdep new -t lib -l c++ libhello
-\
-
-It can be used as a predictable test dependency when setting up new projects.|
-
-Let's say we've visited the \c{libhello} project's
-\l{https://git.build2.org/cgit/hello/libhello/ home page} (for example by
-following a link from the package details page) and noticed that it is being
-developed in a \c{git} repository. How can we see what's available there? If
-the releases are tagged, then we can infer the available released versions
-from the tags. But that doesn't tell us anything about what's happening on the
-\c{HEAD} or in the branches. For that we can use the package manager's
-\l{bpkg-rep-info(1)} command:
-
-\
-$ bpkg rep-info https://git.build2.org/hello/libhello.git
-libhello/1.0.0
-libhello/1.1.0
-\
-
-As you can see, besides \c{1.0.0} that we have seen on \c{cppget.org/stable},
-there is also \c{1.1.0} (which is perhaps being tested in
-\c{cppget.org/testing}). We can also check what might be available on the
-\c{HEAD} (see \l{bpkg-repository-types(1)} for details on the \c{git}
-repository URL format):
-
-\
-$ bpkg rep-info https://git.build2.org/hello/libhello.git#HEAD
-libhello/1.1.1-a.0.20180504111511.2e82f7378519
-\
-
-\N|We can also use the \c{rep-info} command on archive-based repositories,
-however, if available, the web interface is usually more convenient and
-provides more information.|
-
-To summarize, we found two repositories for the \c{libhello} package: the
-archive-based \l{https://cppget.org cppget.org} that contains the released
-versions as well as its development \c{git} repository where we can get the
-bleeding edge stuff. Let's now see how we can add \c{libhello} to our
-project.
-
-
-\h#guide-add-remove-deps|Adding and Removing Dependencies|
-
-So we found \c{libhello} that we would like to use in our \c{hello}
-project. First, we edit the \c{repositories.manifest} file found in the root
-directory of our project and add one of the \c{libhello} repositories as a
-prerequisite. Let's start with \l{https://cppget.org cppget.org}:
-
-\
-role: prerequisite
-location: https://pkg.cppget.org/1/stable
-\
-
-\N|Refer to \l{bpkg#manifest-repository Repository Manifest} for details on
-the repository manifest values.|
-
-Next, we edit the \c{manifest} file (again, found in the root of our project)
-and specify the dependency on \c{libhello} with optional version constraint.
-For example:
-
-\
-depends: libhello ^1.0.0
-\
-
-Let's briefly discuss version constraints (for details see the
-\l{bpkg#manifest-package-depends \c{depends}} value documentation). A version
-constraint can be expressed with a comparison operator (\c{==}, \c{>},
-\c{<}, \c{>=}, \c{<=}), a range shortcut operator (\c{~} and \c{^}), or a
-range. Here are a few examples:
-
-\
-depends: libhello == 1.2.3
-depends: libhello >= 1.2.3
-
-depends: libhello ~1.2.3
-depends: libhello ^1.2.3
-
-depends: libhello [1.2.3 1.2.9)
-\
-
-You may already be familiar with the tilde (\c{~}) and caret (\c{^})
-constraints from dependency managers for other languages. To recap, tilde
-allows upgrades to any further patch versions while caret also allows upgrades
-to further minor versions. They are equivalent to the following ranges:
-
-\
-~X.Y.Z  [X.Y.Z  X.Y+1.0)
-
-^X.Y.Z  [X.Y.Z  X+1.0.0)  if X >  0
-^0.Y.Z  [0.Y.Z  0.Y+1.0)  if X == 0
-\
-
-\N|Zero major version component is customarily used during early development
-where the minor version effectively becomes major. As a result, the tilde
-constraint has a special treatment of this case.|
-
-Unless you have good reasons not to (for example, a dependency does not use
-semantic versioning), we suggest that you use the \c{^} constraint which
-provides a good balance between compatibility and upgradability with \c{~}
-being a more conservative option.
-
-Ok, we've specified where our package comes from (\c{repositories.manifest})
-and which versions we find acceptable (\c{manifest}). The next step is to edit
-\c{hello/buildfile} and import the \c{libhello} library into our build:
-
-\
-import libs += libhello%lib{hello}
-\
-
-Finally, we modify our source code to use the library:
-
-\
-#include <libhello/hello.hxx>
-...
-
-int main (int argc, char* argv[])
-{
-  ...
-  hello::say_hello (cout, argv[1]);
-}
-\
-
-\N|You are probably wondering why we have to specify this repeating
-information in so many places. Let's start with the source code: we can't
-specify the version constraint or location there because it will have to be
-repeated in every source file that uses the dependency.
-
-Moving up, \c{buildfile} is also not a good place to specify this information
-for the same reason (a library can be imported in multiple buildfiles) plus
-the build system doesn't really know anything about version constraints or
-repositories which is the purview of the dependency management tools.
-
-Finally, we have to separate the version constraint and the location because
-the same package can be present in multiple repositories with different
-policies. For example, when a package from a version control-based repository
-is published in an archive-based repository, its \c{repositories.manifest}
-file is ignored and all its dependencies should be available from the
-archive-based repository itself (or its fixed set of prerequisite
-repositories). In other words, \c{manifest} belongs to a package while
-\c{repositories.manifest} \- to a repository.
-
-Also note that this is unlikely to become burdensome since adding new
-dependencies is not something that happens often. There are also plans to
-automate this with a \c{bdep-add(1)} command in the future.|
-
-To summarize, these are the files we had to modify to add a dependency
-to our project:
-
-\
-repositories.manifest   # add https://pkg.cppget.org/1/stable
-manifest                # add 'depends: libhello ^1.0.0'
-buildfile               # import libhello
-hello.cxx               # use libhello
-\
-
-With a new dependency added, let's check the status of our project:
-
-\
-$ bdep status
-fetching pkg:cppget.org/stable (prerequisite of dir:/tmp/hello)
-warning: authenticity of the certificate for pkg:cppget.org/stable
-         cannot be established
-certificate is for cppget.org, \"Code Synthesis\" <admin@cppget.org>
-certificate SHA256 fingerprint:
-86:BA:D4:DE:2C:87:1A:EE:38:<...>:5A:EA:F4:F7:8C:1D:63:30:C6
-trust this certificate? [y/n] y
-
-hello configured 0.1.0-a.0.19700101000000
-      available  0.1.0-a.0.19700101000000#1
-\
-
-The \l{bdep-status(1)} command has detected that the dependency information
-has changed and tells us that a new \i{iteration} of our project (that \c{#1})
-is now available for \i{synchronization} with the build configuration.
-
-We've also been prompted to authenticate the prerequisite repository. This
-will have to happen once for every build configuration we initialize our
-project in and can quickly become tedious. To overcome this, we can mention
-the certificate fingerprint that we wish to automatically trust in the
-\c{repositories.manifest} file (replace it with the actual fingerprint from
-the repository's about page):
-
-\
-role: prerequisite
-location: https://pkg.cppget.org/1/stable
-trust: 86:BA:D4:DE:2C:87:1A:EE:38:<...>:5A:EA:F4:F7:8C:1D:63:30:C6
-\
-
-To synchronize a project with one or more build configurations we use the
-\l{bdep-sync(1)} command:
-
-\
-$ bdep sync
-synchronizing:
-  new libhello/1.0.0 (required by hello)
-  upgrade hello/0.1.0-a.0.19700101000000#1
-\
-
-Or we could just build the project without an explicit \c{sync} \- if
-necessary, it will be automatically synchronized:
-
-\
-$ b
-synchronizing:
-  new libhello/1.0.0 (required by hello)
-  upgrade hello/0.1.0-a.0.19700101000000#1
-c++ ../hello-gcc/libhello-1.0.0/libhello/cxx{hello}
-ld ../hello-gcc/libhello-1.0.0/libhello/libs{hello}
-c++ hello/cxx{hello}@../hello-gcc/hello/hello/
-ld ../hello-gcc/hello/hello/exe{hello}
-ln ../hello-gcc/hello/hello/exe{hello} -> hello/
-\
-
-The synchronization as performed by the \c{sync} command is two-way:
-dependency packages are first added, removed, upgraded, or downgraded in build
-configurations according to the project's version constraints and user
-input. Then the actual versions of the dependencies present in the build
-configurations are recorded in the project's \c{lockfile} so that if desired,
-the build can be reproduced exactly. \N{The \c{lockfile} functionality is not
-yet implemented.} For a new dependency the latest available version that
-satisfies the version constraint is used.
-
-\N|Synchronization is also the last step in the \l{bdep-init(1)} command's
-logic.|
-
-Let's now examine the status in all (\c{--all|-a}) the build configurations
-and include the immediate dependencies (\c{--immediate|-i}):
-
-\
-$ bdep status -ai
-in configuration @gcc:
-hello configured 0.1.0-a.0.19700101000000#1
-  libhello ^1.0.0 configured 1.0.0
-
-in configuration @clang:
-hello configured 0.1.0-a.0.19700101000000
-      available 0.1.0-a.0.19700101000000#1
-\
-
-Since we didn't specify a configuration explicitly, only the default (\c{gcc})
-was synchronized. Normally, you would try a new dependency in one
-configuration, make sure everything looks good, then synchronize the rest with
-\c{--all|-a} (or, again, just build what you need directly). Here are a few
-examples (see \l{bdep-projects-configs(1)} for details):
-
-\
-$ bdep sync -a
-$ bdep sync @gcc @clang
-$ bdep sync -c ../hello-mingw
-\
-
-To get rid of a dependency, we simply remove it from the \c{manifest} file
-and synchronize the project. For example, assuming \c{libhello} is no longer
-mentioned as a dependency in our \c{manifests}:
-
-\
-$ bdep status
-hello configured 0.1.0-a.0.19700101000000#1
-      available  0.1.0-a.0.19700101000000#2
-
-$ bdep sync
-synchronizing:
-  drop libhello/1.0.0 (unused)
-  upgrade hello/0.1.0-a.0.19700101000000#2
-\
-
-
-\h#guide-upgrade-downgrade-deps|Upgrading and Downgrading Dependencies|
-
-Let's say we would like to try that \c{1.1.0} version we have seen in
-the \c{libhello} \c{git} repository. First, we need to add the
-repository to the \c{repositories.manifest} file:
-
-\
-role: prerequisite
-location: https://git.build2.org/hello/libhello.git
-\
-
-\N|Note that we don't need the \c{trust} value since \c{git} repositories
-are not authenticated.|
-
-To refresh the list of available dependency versions we use the
-\l{bdep-fetch(1)} command (or the \c{--fetch|-f} option to \c{status}):
-
-\
-$ bdep fetch
-$ bdep status libhello
-libhello configured 1.0.0 available [1.1.0]
-\
-
-To upgrade (or downgrade) dependencies we again use the \l{bdep-sync(1)}
-command. We can upgrade one or more specific dependencies by listing them
-as arguments to \c{sync}:
-
-\
-$ bdep sync libhello
-synchronizing:
-  new libformat/1.0.0 (required by libhello)
-  new libprint/1.0.0 (required by libhello)
-  upgrade libhello/1.1.0
-  upgrade hello/0.1.0-a.0.19700101000000#3
-\
-
-Without an explicit version or the \c{--patch|-p} option, \c{sync} will
-upgrade the specified dependencies to the latest available versions. For
-example, if we don't like version \c{1.1.0}, we can downgrade it back to
-\c{1.0.0} by specifying the version explicitly (we pass \c{--old-available|-o}
-to \c{status} to see the old versions):
-
-\
-$ bdep status -o libhello
-libhello configured 1.1.0 available (1.1.0) [1.0.0]
-
-$ bdep sync libhello/1.0.0
-synchronizing:
-  drop libprint/1.0.0 (unused)
-  drop libformat/1.0.0 (unused)
-  downgrade libhello/1.0.0
-  reconfigure hello/0.1.0-a.0.19700101000000#3
-\
-
-\N|The available versions are listed in the descending order with \c{[]}
-indicating that the version is only available as a dependency and \c{()}
-marking the current version.|
-
-Instead of specific dependencies we can also upgrade (\c{--upgrade|-u}) or
-patch (\c{--patch|-p}) immediate (\c{--immediate|-i}) or all
-(\c{--recursive|-r}) dependencies of our project.
-
-As a more realistic example, version \c{1.1.0} of \c{libhello} depends on two
-other libraries: \c{libformat} and \c{libprint}. Here is our project's
-dependency tree while we were still using that version:
-
-\
-$ bdep status -r
-hello configured 0.1.0-a.0.19700101000000#3
-  libhello ^1.0.0 configured 1.1.0
-    libformat ^1.0.0 configured 1.0.0
-    libprint ^1.0.0 configured 1.0.0
-\
-
-A typical conservative dependency management workflow would look like this:
-
-\
-$ bdep status -fi  # refresh and examine immediate dependencies
-hello configured 0.1.0-a.0.19700101000000#3
-  libhello configured 1.1.0 available [2.0.0] [1.2.0] [1.1.2] [1.1.1]
-
-$ bdep sync -pi    # upgrade immediate to latest patch version
-synchronizing:
-  upgrade libhello/1.1.2
-  reconfigure hello/0.1.0-a.0.19700101000000#3
-continue? [Y/n] y
-\
-
-Notice that in case of such mass upgrades you are prompted for confirmation
-before anything is actually changed (unless you pass \c{--yes|-y}).
-
-In contrast, the following would be a fairly aggressive workflow where we
-upgrade everything to the latest available version (version constraints
-permitting; here we assume \c{^1.0.0} was used for all the dependencies):
-
-\
-$ bdep status -fr  # refresh and examine all dependencies
-hello configured 0.1.0-a.0.19700101000000#3
-  libhello configured 1.1.0 available [2.0.0] [1.2.0] [1.1.1]
-    libprint configured 1.0.0 available [2.0.0] [1.1.0] [1.0.1]
-    libformat configured 1.0.0 available [2.0.0] [1.1.0] [1.0.1]
-
-$ bdep sync -ur    # upgrade all to latest available version
-synchronizing:
-  upgrade libprint/1.1.0
-  upgrade libformat/1.1.0
-  upgrade libhello/1.2.0
-  reconfigure hello/0.1.0-a.0.19700101000000#3
-continue? [Y/n] y
-\
-
-We can also have something in between: patch all (\c{sync\ -pr}), upgrade
-immediate (\c{sync\ -ui}), or even upgrade immediate and patch the rest
-(\c{sync\ -ui} followed by \c{sync\ -pr}).
-
-
-\h#guide-versioning-releasing|Versioning and Release Management|
-
-Let's now discuss versioning and release management and, yes, that
-strange-looking \c{0.1.0-a.0.19700101000000} we keep seeing. While a build
-system project doesn't need a version and a \c{bpkg} package can use custom
-versioning schemes (see \l{bpkg#package-version Package Version}), a project
-managed by \c{bdep} must use \i{standard versioning}. \N{A dependency, which
-is a \c{bpkg} package, need not use standard versioning.}
-
-Standard versioning (\i{stdver}) is a \l{https://semver.org semantic
-versioning} (\i{semver}) scheme with a more precisely defined pre-release
-component and without any build metadata.
-
-\N|If you believe that \i{semver} is just \c{\i{major}.\i{minor}.\i{patch}},
-then in your worldview \i{stdver} would be the same as \i{semver}. In reality,
-\i{semver} also allows loosely defined pre-release and build metadata
-components. For example, \c{1.2.3-beta.1+build.23456} is a valid \i{semver}.|
-
-A standard version has the following form:
-
-\c{\i{major}\b{.}\i{minor}\b{.}\i{patch}[\b{-}\i{prerel}]}
-
-The \ci{major}, \ci{minor}, and \ci{patch} components have the same meaning as
-in \i{semver}. The \ci{prerel} component is used to provide \i{continuous
-versioning} of our project between releases. Specifically, during development
-of a new version we may want to publish several pre-releases, for example,
-alpha or beta. In between those we may also want to publish a number of
-snapshots, for example, for CI. With continuous versioning all these releases,
-pre-releases, and snapshots are assigned unique, properly ordered versions.
-
-\N|Continuous versioning is a cornerstone of the \c{build2} project dependency
-management. In case of snapshots, an appropriate version is assigned
-automatically in cooperation with your VCS.|
-
-The \ci{prerel} component for a pre-release has the following form:
-
-\c{(\b{a}|\b{b})\b{.}\i{num}}
-
-Here \cb{a} stands for alpha, \cb{b} stands for beta, and \ci{num} is the
-alpha/beta number. For example:
-
-\
-1.1.0        # final              release  for 1.1.0
-1.2.0-a.1    # first  alpha   pre-release  for 1.2.0
-1.2.0-a.2    # second alpha   pre-release  for 1.2.0
-1.2.0-b.1    # first  beta    pre-release  for 1.2.0
-1.2.0        # final              release  for 1.2.0
-\
-
-The \ci{prerel} component for a snapshot has the following form:
-
-\c{(\b{a}|\b{b})\b{.}\i{num}\b{.}\i{snapsn}[\b{.}\i{snapid}]}
-
-Where \ci{snapsn} is the snapshot sequence number and \ci{snapid} is
-the snapshot id. In case of \c{git}, \ci{snapsn} is the commit timestamp
-in the \c{YYYYMMDDhhmmss} form and UTC timezone while \ci{snapid} is
-a 12-character abbreviated commit id. For example:
-
-\
-1.2.3-a.1.20180319215815.26efe301f4a7
-\
-
-Notice also that a snapshot version is ordered \i{after} the corresponding
-pre-release version. That is, \c{1.2.3-a.1\ <\ 1.2.3-a.1.1}. As a result, it
-is customary to start the development of a new version with \c{X.Y.Z-a.0.z},
-that is, a snapshot after the (non-existent) zero'th alpha release. \N{We will
-explain the meaning of \cb{z} in this version momentarily.} The following
-chronologically-ordered versions illustrate a typical release flow of a
-project that uses \c{git} as its VCS:
-
-\
-0.1.0-a.0.19700101000000               # snapshot (no commits yet)
-0.1.0-a.0.20180319215815.26efe301f4a7  # snapshot (first commit)
-...                                    # more commits/snapshots
-0.1.0-a.1                              # pre-release (first alpha)
-0.1.0-a.1.20180319221826.a6f0f41205b8  # snapshot
-...                                    # more commits/snapshots
-0.1.0-a.2                              # pre-release (second alpha)
-0.1.0-a.2.20180319231937.b701052316c9  # snapshot
-...                                    # more commits/snapshots
-0.1.0-b.1                              # pre-release (first beta)
-0.1.0-b.1.20180319242038.c812163417da  # snapshot
-...                                    # more commits/snapshots
-0.1.0                                  # release
-0.2.0-a.0.20180319252139.d923274528eb  # snapshot (first in 0.2.0)
-...
-\
-
-For a more detailed discussion of standard versioning and its support in
-\c{build2} refer to \l{b#module-version Version Module}.
-
-Let's now see how this works in practice by publishing a couple of versions
-for our \c{hello} project. By now it should be clear what that
-\c{0.1.0-a.0.19700101000000} means \- it is the first snapshot version of our
-project. Since there are no commits yet, it has the UNIX epoch as its commit
-timestamp. As the first step, let's try to commit our project and see what
-changes:
-
-\
-$ git add .
-$ git commit -m \"Start hello project\"
-
-$ bdep status
-hello configured 0.1.0-a.0.19700101000000
-      available  0.1.0-a.0.20180507062614.ee006880fc7e
-\
-
-Just like with changes to dependency information, \c{status} has detected that
-a new (snapshot) version of our project is available for synchronization.
-
-\N|Another way to view the project's version (which works even if we are
-not using \c{bdep}) is with the build system's \c{info} operation:
-
-\
-$ b info
-project: hello
-version: 0.1.0-a.0.20180507062614.ee006880fc7e
-summary: hello executable project
-...
-\
-
-|
-
-Let's synchronize with the default build configuration:
-
-\
-$ bdep sync
-synchronizing:
-  upgrade hello/0.1.0-a.0.20180507062614.ee006880fc7e
-
-$ bdep status
-hello configured 0.1.0-a.0.20180507062614.ee006880fc7e
-\
-
-\N|Notice that we didn't have to manually change the version anywhere. All we
-had to do was commit our changes and a new snapshot version was automatically
-derived by \c{build2} from the new \c{git} commit. Without this automation
-continuous versioning would hardly be practical.|
-
-If we now make another commit, we will see a similar picture:
-
-\
-$ bdep status
-hello configured 0.1.0-a.0.20180507062614.ee006880fc7e
-      available  0.1.0-a.0.20180507062615.8fb9de05b38f
-\
-
-\N|Note that you don't need to manually run \c{sync} after every commit. As
-discussed earlier, you can simply run the build system to update your project
-and things will get automatically synchronized if necessary.|
-
-Ok, time for our first release. Let's start with \c{0.1.0-a.1}. Unlike
-snapshots, for pre-releases as well as final releases we have to update the
-version in the \c{manifest} file manually:
-
-\
-version: 0.1.0-a.1
-\
-
-\N|The \c{manifest} file is the singular place where we specify the package
-version. The build system's \l{b#module-version \c{version} module} makes it
-available in various forms in buildfiles and even source code.|
-
-To ensure continuous versioning, this change to version must be the last commit
-for this (pre-)release which itself must be immediately followed by a second
-change to the version starting the development of the next (pre-)release. We
-also recommend that you tag the release commit with a tag name in the
-\c{\b{v}\i{X}.\i{Y}.\i{Z}} form.
-
-\N|Having regular release tag names with the \cb{v} prefix allows one to
-distinguish them from other tags, for example, with wildcard patterns.|
-
-Here is the release workflow for our example:
-
-\
-$ git commit -a -m \"Release version 0.1.0-a.1\"
-$ git tag -a v0.1.0-a.1 -m \"Tag version 0.1.0-a.1\"
-$ git push --follow-tags
-
-# Version 0.1.0-a.1 is now public.
-
-$ edit manifest  # change 'version: 0.1.0-a.1.z'
-$ git commit -a -m \"Change version to 0.1.0-a.1.z\"
-$ git push
-
-# Master is now open for business.
-\
-
-\N|In the future release management will be automated with a
-\c{bdep-release(1)} command.|
-
-Notice also that when specifying a snapshot version in \c{manifest} we use the
-special \cb{z} snapshot value (for example, \c{0.1.0-a.1.z}) which is
-recognized and automatically replaced by \c{build2} with, in case of \c{git},
-a commit timestamp and id (refer to \l{b#module-version Version Module} for
-details).
-
-Publishing the final release is exactly the same. For completeness, here
-are the commands:
-
-\
-$ edit manifest  # change 'version: 0.1.0'
-$ git commit -a -m \"Release version 0.1.0\"
-$ git tag -a v0.1.0 -m \"Tag version 0.1.0\"
-$ git push --follow-tags
-
-$ edit manifest  # change 'version: 0.2.0-a.0.z'
-$ git commit -a -m \"Change version to 0.2.0-a.0.z\"
-$ git push
-\
-
-\N|One sticky point of continuous versioning is choosing the next version.
-For example, above should we continue with \c{0.1.1-a.0}, \c{0.2.0-a.0},
-or \c{1.0.0-a.0}? The important rule to keep in mind is that we can jump
-forward to any further version at any time and without breaking continuous
-versioning. But we can never jump backwards.
-
-For example, we can start with \c{0.2.0-a.0} but if we later realize that this
-will actually be a new major release, we can easily change it to
-\c{1.0.0-a.0}. As a result, the general recommendation is to start
-conservatively by either incrementing the patch or the minor version
-component. The recommended strategy is to increment the minor component and,
-if required, release patch versions from a separate branch (created by
-branching off from the release commit).
-
-Note also that you don't have to make any pre-releases if you don't need them.
-While during development you would still keep the version as \c{X.Y.Z-a.0}, at
-release you simply change it directly to the final \c{X.Y.Z}.|
-
-When publishing the final release you may also want to clean up now
-obsolete pre-release tags. For example:
-
-\
-$ git tag -l 'v0.1.0-*' | xargs git push --delete origin
-$ git tag -l 'v0.1.0-*' | xargs git tag --delete
-\
-
-\N|While at first removing such tags may seem like a bad idea, pre-releases
-are by nature temporary and their use only makes sense until the final release
-is published.
-
-Also note that having a \c{git} repository with a large number of published
-but unused version tags may result in a significant download overhead.|
-
-Let's also briefly discuss in which situations we should increment each of the
-version components. While \i{semver} gives basic guidelines, there are several
-ways to apply them in the context of C/C++ where there is a distinction
-between binary and source compatibility. We recommend that you reserve
-\i{patch} releases for specific bug fixes and security issues that you can
-guarantee with a high level of certainty to be binary-compatible. Otherwise,
-if the changes are source-compatible, increment \i{minor}. And if they are
-breaking (that is, the user code likely will need adjustments), increment
-\i{major}. During early development, when breaking changes are frequent, it is
-customary to use the \c{0.Y.Z} versions where \c{Y} effectively becomes the
-\i{major} component. Again, refer to the \l{b#module-version Version Module}
-for a more detailed discussion of this topic.
-
-\h#guide-consume-pkg|Package Consumption|
-
-Ok, now that we have published a few releases of \c{hello}, how would the
-users of our project get them? While they could clone the repository and use
-\c{bdep} just like we did, this is more of a development rather than
-consumption workflow. For consumption it is much easier to use the package
-dependency manager, \l{bpkg(1)}, directly.
-
-First, we create a suitable build configuration with the
-\l{bpkg-cfg-create(1)} command. We can use the same place for building all our
-tools so let's call the directory \c{tools}. Seeing that we are only
-interested in using (rather than developing) such tools, let's build them
-optimized and also configure a suitable installation location:
-
-\
-$ bpkg create -d tools cc        \
-  config.cxx=g++                 \
-  config.cc.coptions=-O3         \
-  config.install.root=/usr/local \
-  config.install.sudo=sudo
-created new configuration in /tmp/tools/
-
-$ cd tools
-\
-
-\N|The \c{bdep} build configurations we were creating with \c{init\ -C} are
-actually \c{bpkg} build configurations. In fact, underneath, \l{bdep-init(1)}
-calls \l{bpkg-cfg-create(1)}.|
-
-To fetch and build packages (as well as all their dependencies) we use the
-\l{bpkg-pkg-build(1)} command. We can use either an archive-based repository
-like \l{https://cppget.org cppget.org} or build directly from \c{git}:
-
-\
-$ bpkg build hello@https://git.build2.org/hello/hello.git
-fetching from https://git.build2.org/hello/hello.git
-  new libformat/1.0.0 (required by libhello)
-  new libprint/1.0.0 (required by libhello)
-  new libhello/1.1.0 (required by hello)
-  new hello/1.0.0
-continue? [Y/n] y
-configured libformat/1.0.0
-configured libprint/1.0.0
-configured libhello/1.1.0
-configured hello/1.0.0
-c++ libprint-1.0.0/libprint/cxx{print}
-c++ hello-1.0.0/hello/cxx{hello}
-c++ libhello-1.1.0/libhello/cxx{hello}
-c++ libformat-1.0.0/libformat/cxx{format}
-ld libprint-1.0.0/libprint/libs{print}
-ld libformat-1.0.0/libformat/libs{format}
-ld libhello-1.1.0/libhello/libs{hello}
-ld hello-1.0.0/hello/exe{hello}
-updated hello/1.0.0
-\
-
-\N|Passing a repository URL to the \c{build} command is a shortcut to the
-following sequence of commands:
-
-\
-$ bpkg add https://git.build2.org/hello/hello.git  # add repository
-$ bpkg fetch                             # fetch package list
-$ bpkg build hello                       # build package by name
-\
-
-|
-
-Once built, we can install the package to the location that we have specified
-with \c{config.install.root} using the \l{bpkg-pkg-install(1)} command:
-
-\
-$ bpkg install hello
-...
-install libformat-1.0.0/libformat/libs{format}
-install libprint-1.0.0/libprint/libs{print}
-install libhello-1.1.0/libhello/libs{hello}
-install hello-1.0.0/hello/exe{hello}
-
-$ hello World
-Hello, World!
-\
-
-\N|If on your system the installed executables don't run from \c{/usr/local}
-because of the unresolved shared libraries (or if you are installing somewhere
-else, such as \c{/opt}), then the easiest way to fix this is with \i{rpath}.
-Simply add the following configuration variable when creating the build
-configuration (or as an argument to the \c{install} command):
-
-\
-config.bin.rpath=/usr/local/lib
-\
-
-|
-
-If we need to uninstall a previously installed package, there is the
-\l{bpkg-pkg-uninstall(1)} command:
-
-\
-$ bpkg uninstall hello
-uninstall hello-1.0.0/hello/exe{hello}
-uninstall libhello-1.1.0/libhello/libs{hello}
-uninstall libprint-1.0.0/libprint/libs{print}
-uninstall libformat-1.0.0/libformat/libs{format}
-...
-\
-
-To upgrade or downgrade packages we again use the \c{build} command. Here
-is a typical upgrade workflow:
-
-\
-$ bpkg fetch              # refresh available package list
-$ bpkg status             # see if new versions are available
-
-$ bpkg uninstall hello    # uninstall old version
-$ bpkg build     hello    # upgrade to the latest version
-$ bpkg install   hello    # install new version
-\
-
-Similar to \c{bdep}, to downgrade we have to specify the desired version
-explicitly. There are also the \c{--upgrade|-u} and \c{--patch|-p} as well as
-\c{--immediate|-i} and \c{--recursive|-r} options that allow us to upgrade or
-patch packages that we have built and/or their immediate or all dependencies
-(see \l{bpkg-pkg-build(1)} for details). For example, to make sure everything
-is patched, run:
-
-\
-$ bpkg fetch
-$ bpkg build -pr
-\
-
-If a package is no longer needed, we can remove it from the configuration with
-\l{bpkg-pkg-drop(1)}:
-
-\
-$ bpkg drop hello
-following dependencies were automatically built but
-will no longer be used:
-  libhello
-  libformat
-  libprint
-drop unused packages? [Y/n] y
-  drop hello
-  drop libhello
-  drop libformat
-  drop libprint
-continue? [Y/n] y
-purged hello
-purged libhello
-purged libformat
-purged libprint
-\
-"