diff options
Diffstat (limited to 'doc/intro.cli')
| -rw-r--r-- | doc/intro.cli | 128 |
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: |