aboutsummaryrefslogtreecommitdiff
path: root/doc/intro.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-05-29 09:23:03 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2018-05-29 09:23:03 +0200
commit5eaf9793f9b4b441b9d82f9be70f071f570e6d0c (patch)
tree48b0d10c2600ccecb1399128bbc8923797c11372 /doc/intro.cli
parent485ae1742a3918225aac39ba66a3f21cd9a4b891 (diff)
Update new intro with few parts from old version
Diffstat (limited to 'doc/intro.cli')
-rw-r--r--doc/intro.cli128
1 files changed, 114 insertions, 14 deletions
diff --git a/doc/intro.cli b/doc/intro.cli
index f46082c..3a538b5 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -27,6 +27,17 @@
//
"
+\h0#preface|Preface|
+
+This document is an overall introduction to the \c{build2} toolchain that
+shows how the main components, namely the build system, the package dependency
+manager, and the project dependency manager are used together to handle the
+entire C++ project development lifecycle: creation, development, testing, and
+delivery. For additional information, including documentation for individual
+toolchain components, man pages, etc., refer to the \c{build2} project
+\l{https://build2.org/doc.xhtml Documentation} page.
+
+
\h1#tldr|TL;DR|
\
@@ -96,15 +107,15 @@ 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
-the \l{https://build2.org/install.xhtml Install} page.
+follow along. Or, alternatively, you can take a short detour to the
+\l{https://build2.org/install.xhtml Installation Instructions} and then try
+the examples for yourself.
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.
+interface across all the platforms and compilers. While most of 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:
@@ -553,6 +564,39 @@ package/project dependency management can be used for any compiled language.|
order to automate project versioning. Note that currently only \c{git(1)} is
supported.|
+Now that we understand the tooling, let's also revisit the notion of \i{build
+configuration} (those \c{hello-gcc} and \c{hello-clang} directories). A
+\c{bdep} build configuration is actually a \c{bpkg} build configuration which,
+in the build system terms, is an \i{amalgamation} \- a project that contains
+\i{subprojects}. In our case, the subprojects in these amalgamations will be
+the projects we have initialized with \c{init} and, as we will see later,
+packages that they depend on. For example, here is what our \c{hello-gcc}
+contains:
+
+\
+$ tree hello-gcc
+hello-gcc/
+├── .bpkg/
+├── build/
+│   └── config.build
+└── hello/
+ ├── build/
+ │   └── config.build
+ └── hello/
+ ├── hello
+ └── hello.o
+\
+
+\N|Underneath \l{bdep-init(1)} with the \c{--config-create|-C} option calls
+\l{bpkg-cfg-create(1)} which, in turn, performs the build system \c{create}
+meta-operation (see \l{b(1)} for details).
+
+The important point here is that the \c{bdep} build configuration is not a
+black box that you should never look inside of. On the contrary, it is a
+normal and predictable concept of the package manager and the build system and
+as long as you understand what you are doing, you should feel free to interact
+with it directly.|
+
Let's now move on to the reason why there is \i{dep} in the \c{bdep} name:
dependency management.
@@ -600,9 +644,11 @@ 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 (but
-easy to mirror) package repository. As an added benefit, packages on
-\l{https://cppget.org cppget.org} are continuously
+\l{https://cppget.org cppget.org} is the \c{build2} community's central
+package repository. While centralized, it is also easy to mirror since its
+contents are accessible via plain HTTPS (you can browse
+\l{https://pkg.cppget.org pkg.cppget.org} to get an idea). 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.
@@ -1585,10 +1631,6 @@ $ bpkg create -d tools cc ^
config.install.root= C:\install
\
-\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}:
@@ -1656,6 +1698,64 @@ Note to Windows users: this is not an issue on this platform since executables
and shared (DLL) libraries are installed into the same subdirectory (\c{bin})
of the installation directory.|
+The installation contents and layout under \c{config.install.root} would be
+along these lines:
+
+\
+/usr/local/
+├── bin/
+│   └── hello
+├── include/
+│   ├── libformat/
+│   │   ├── export.hxx
+│   │   ├── format.hxx
+│   │   └── version.hxx
+│   ├── libhello/
+│   │   ├── export.hxx
+│   │   ├── hello.hxx
+│   │   └── version.hxx
+│   └── libprint/
+│   ├── export.hxx
+│   ├── print.hxx
+│   └── version.hxx
+├── lib/
+│   ├── libformat-1.0.so
+│   ├── libformat.so -> libformat-1.0.so
+│   ├── libhello-1.1.so
+│   ├── libhello.so -> libhello-1.1.so
+│   ├── libprint-1.0.so
+│   ├── libprint.so -> libprint-1.0.so
+│   └── pkgconfig
+│   ├── libformat.shared.pc
+│   ├── libhello.shared.pc
+│   └── libprint.shared.pc
+└── share/
+ └── doc/
+ ├── libformat/
+ │   └── manifest
+ ├── libhello/
+ │   └── manifest
+ └── libprint/
+ └── manifest
+\
+
+\N|The installation locations of various types of files (executables,
+libraries, headers, documentation, etc.) can be customized using a number of
+the \c{config.install.*} variables with the most commonly used ones and their
+defaults (relative to \c{config.install.root}) listed below (see the
+\c{install} build system module documentation for the complete list).
+
+\
+config.install.bin = root/bin/
+config.install.lib = root/lib/
+config.install.doc = root/share/doc/
+config.install.man = root/share/man/
+config.install.include = root/include/
+\
+
+|
+
+
If we need to uninstall a previously installed package, there is the
\l{bpkg-pkg-uninstall(1)} command: