diff options
Diffstat (limited to 'doc')
| -rwxr-xr-x | doc/cli.sh | 2 | ||||
| -rw-r--r-- | doc/intro.cli | 55 | ||||
| -rw-r--r-- | doc/packaging.cli | 73 |
3 files changed, 91 insertions, 39 deletions
@@ -1,6 +1,6 @@ #! /usr/bin/env bash -version=0.17.0-a.0.z +version=0.18.0-a.0.z trap 'exit 1' ERR set -o errtrace # Trap in functions. diff --git a/doc/intro.cli b/doc/intro.cli index 6671cbd..6ec3d04 100644 --- a/doc/intro.cli +++ b/doc/intro.cli @@ -2436,40 +2436,14 @@ 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 +│ └── hello ├── 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.pc -│ ├── libhello.pc -│ └── libprint.pc +│ ├── libformat-1.0.so +│ ├── libhello-1.1.so +│ └── libprint-1.0.so └── share/ └── doc/ - ├── libformat/ - │ ├── manifest - │ └── README.md - ├── libhello/ - │ ├── manifest - │ └── README.md - └── libprint/ + └── hello/ ├── manifest └── README.md \ @@ -2503,6 +2477,25 @@ uninstall libformat-1.0.0/libformat/libs{format} <- /usr/local/lib/ ... \ +\N|From the above listing we can gather that only the shared library binaries +were installed. In particular, neither static library binaries nor headers and +other development-related files (such as non-versioned shared library +symlinks, \c{pkg-config} \c{.pc} files, etc) were installed. + +The reason for this behavior is that by default the \l{bpkg-pkg-install(1)} +command only instructs the build system to install packages that were +specified on the command line (\c{hello} in out case) while the build system +in turn installs from dependency packages only what's necessary for the +packages it was instructed to install. In our case, installing the \c{hello} +also requires installing the shared library binaries that it uses but none of +the development-related files (we don't need library headers in order to run +an executable). + +However, this default behavior of \l{bpkg-pkg-install(1)} (and +\l{bpkg-pkg-uninstall(1)}) can be changed with the \c{--recursive} option, +which instructs \c{bpkg} to additionally fully install/uninstall dependency +packages.| + Rather than installing the package locally we could instead generate a \i{binary distribution package} for it using the \l{bpkg-pkg-bindist(1)} command. Such a binary package can then be installed on a different diff --git a/doc/packaging.cli b/doc/packaging.cli index d861457..004e27e 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -526,7 +526,7 @@ name differs from upstream, then there is likely a good reason for that and it is worth trying to understand what it is. \N|Tip: when trying to find the corresponding Debian package, search for the -executable file name in the package contents if you cannot fine the package by +executable file name in the package contents if you cannot find the package by its upstream name. Also consider searching in the \c{unstable} distribution in addition to \c{stable} for newer packages.| @@ -635,7 +635,7 @@ however, that we often deviate from Debian's splits, especially when it comes to libraries. Such differences are usually due to Debian focusing on binary packages while in \c{build2} we are focusing on source packages. -To give a few example, \c{libevent} shown in the above table provides several +To give a few examples, \c{libevent} shown in the above table provides several libraries (\c{libevent-core}, \c{libevent-extra}, etc) and in Debian it is actually split into several binary packages along these lines. In \c{build2}, however, there is a single source package that provides all these libraries @@ -1160,7 +1160,7 @@ $ b clean \N|One relatively common case where the installation location may not match upstream are libraries that include their headers without the subdirectory prefix (for example, \c{<foo_util.h>} instead of \c{<foo/util.h>}). In such -cases, in the \c{bdep-new} command, you want to use \i{prefix} rather that +cases, in the \c{bdep-new} command, you may want to use \i{prefix} rather than \i{source subdirectory} (with the latter being the default). For example: \ @@ -1824,7 +1824,7 @@ need to tweak it are not uncommon and include: \N|One type of configuration that you should normally not expose when packaging for \c{build2} is support for both header-only and compiled - modes. See \l{b#dont-header-only Don't make library header-only if it + modes. See \l{#dont-header-only Don't make library header-only if it can be compiled} for details.||| Also, in C++ projects, if you don't have any inline or template files, then @@ -2105,7 +2105,7 @@ If you only have private auto-generated headers, then only remove the expansion from \c{cxx.export.poptions}.| If you don't have any dependencies, then remove all the assignments and -expansions of the \c{intf_libs} and \c{intf_libs} variables. That is, +expansions of the \c{intf_libs} and \c{impl_libs} variables. That is, the following lines in the original \c{buildfile}: \ @@ -2198,7 +2198,7 @@ import impl_libs += libsqlite3%lib{sqlite3} \ \N|If you don't have any implementation or interface dependencies, you can -remove the assignment and all the expansion of the corresponding \c{*_libs} +remove the assignment and all the expansions of the corresponding \c{*_libs} variable.| Note also that system libraries like \c{-lm}, \c{-ldl} on UNIX or @@ -3702,7 +3702,7 @@ Note also that while you may be tempted to adjust the \c{version} value, resist this temptation since this will be done automatically by \l{bdep-release(1)} later. -You may also want to add the following value in certain cases: +You may also want to add the following values in certain cases: \dl| @@ -4316,6 +4316,7 @@ commit, run the following commands: \ $ cd upstream/ +$ git fetch $ git checkout v2.2.0 $ cd ../ @@ -5315,6 +5316,64 @@ libfoo ^1.2.3 \ +\h#howto-test-timeout|How do I deal with tests that don't terminate?| + +If upstream tests don't terminate in a reasonable time (or at all), then your +CI jobs will be failing with timeouts. + +\N|Naturally, we cannot afford tests to run indefinitely or unreasonably long +on our CI infrastructure and, as a result, we impose a timeout on tests +execution. Currently it is 25 minutes.| + +If you find yourself in this situation, the first step is to examine such +tests for a mechanism, typically a command line option, that allows you to set +a limit on test execution, such as a time limit, number of test iterations, +etc. + +If there is an option, then we can pass it with \c{test.options} (see +\l{b#intro-operations-test Testing} for background): + +\ +exe{driver}: test.options = --iterations 100 +\ + +If, however, there is no mechanism for limiting upstream test execution, then +the last resort is to set a test execution timeout that is treated as success. +For details on how to achieve this see +\l{https://github.com/build2/HOWTO/blob/master/entries/sanitize-test-execution.md +How do I sanitize the execution of my tests?} + + +\h#howto-out-of-ram|How do I deal with compiler/linker running out of RAM?| + +If a third-party project contains very large/complex translation units or is +linking a large number of object files, then the compiler or linker may run +out of memory, especially if compilation/linking is performed in parallel with +other compilation/linking jobs. For compilation, this is normally triggered +when compiling with optimization enabled. For example, on Linux with GCC this +could manifest in an error like this: + +\ +Out of memory: Killed process 1857 (cc1plus) ... pgtables:13572kB ... +\ + +The recommended way to deal with such issues is to serialize the compilation +or linking of the targets in question. Specifically, both the C/C++ compile +and link rules recognize the \c{cc.serialize} boolean variable which instructs +them to compile/link serially (as opposed to in parallel) with regards to any +other recipe. For example: + +\ +obj{memory-hog}: cc.serialize = true +exe{very-large}: cc.serialize = true +\ + +To identify which source files require a large amount of RAM, build serially +(\c{-s}) with optimization enabled while watching the amount of RAM used by +the compiler. Similarly, for linking binaries, watch the amount of RAM +used by the linker. + + \h1#faq|Packaging FAQ| \h#faq-publish|Publishing FAQ| |