aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2020-07-02 10:00:48 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2020-07-02 10:00:48 +0200
commit7d715bb43457fc760ec57ab757f3fd37e1655fae (patch)
tree6ec088f8f3de15cc0563d300aa9e0e2780bc6edb
parent45c9008b9679aeed32487f065e3e594f320c8b9f (diff)
Document private installation subdirectory mechanism
A private installation subdirectory can be used to hide the implementation details of a project. This is primarily useful when installing an executable that depends on a bunch of libraries into a shared location, such as /usr/local/.
-rw-r--r--doc/manual.cli81
1 files changed, 76 insertions, 5 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index bb4f57b..4a3a3c4 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1827,9 +1827,9 @@ however, can be customized with the \c{backlink} target-specific variable.|
\h2#intro-operations-test|Testing|
-The next module we load in \c{bootstrap.build} is \c{test} which defines the
-\c{test} operation. As the name suggests, this module provides support for
-running tests.
+The next module we load in \c{bootstrap.build} is \l{#module-test \c{test}}
+which defines the \c{test} operation. As the name suggests, this module
+provides support for running tests.
There are two types of tests that we can run with the \c{test} module: simple
and scripted.
@@ -2106,8 +2106,9 @@ Implementing Unit Testing}.|
\h2#intro-operations-install|Installing|
-The \c{install} module defines the \c{install} and \c{uninstall} operations.
-As the name suggests, this module provides support for project installation.
+The \l{#module-install \c{install}} module defines the \c{install} and
+\c{uninstall} operations. As the name suggests, this module provides support
+for project installation.
\N|Installation in \c{build2} is modeled after UNIX-like operation systems
though the installation directory layout is highly customizable. While
@@ -5433,6 +5434,76 @@ treated specially. It enables all the tests at and under its directory. This
special treatment can be inhibited by specifying the target type explicitly
(for example, \c{dir{foo/\}}).
+\h1#module-install|\c{install} Module|
+
+\N{This chapter is a work in progress and is incomplete.}
+
+The \c{install} module provides support for installing and uninstalling
+projects.
+
+As briefly discussed in the \l{#intro-operations-install Installing} section
+of the Introduction, the \c{install} module defines the following standard
+installation locations:
+
+\
+name default config.* override
+---- ------- -----------------
+root install.root
+
+data_root root/ install.data_root
+exec_root root/ install.exec_root
+
+bin exec_root/bin/ install.bin
+sbin exec_root/sbin/ install.sbin
+lib exec_root/lib/<private>/ install.lib
+libexec exec_root/libexec/<private>/<project>/ install.libexec
+pkgconfig lib/pkgconfig/ install.pkgconfig
+
+include data_root/include/<private>/ install.include
+share data_root/share/ install.share
+data share/<private>/<project>/ install.data
+
+doc share/doc/<private>/<project>/ install.doc
+legal doc/ install.legal
+man share/man/ install.man
+man<N> man/man<N>/ install.man<N>
+\
+
+The \c{<project>} and \c{<private>} substitutions in these
+\c{config.install.*} values are replaced with the project name and private
+subdirectory, respectively. If either is empty, that the corresponding
+directory component is ignored.
+
+The optional private installation subdirectory (\c{<private>}) mechanism can
+be used to hide the implementation details of a project. This is primarily
+useful when installing an executable that depends on a bunch of libraries into
+a shared location, such as \c{/usr/local/}. By hiding the libraries in the
+private subdirectory we can make sure that they will not interfere with
+anything that is already installed into such a shared location by the user
+and that any further such installations won't interfere with our executable.
+
+The private installation subdirectory is specified with the
+\c{config.install.private} variable. Its value must be a relative
+directory and may include multiple components. For example:
+
+\
+$ b install config.install.root=/usr/local/ config.install.private=hello/
+\
+
+\N|If you are relying on your system's dynamic linker defaults to
+automatically find shared libraries that are installed with your executable,
+then adding the private installation subdirectory will most definitely
+cause this to stop working. The recommended way to resolve this problem is
+to use \i{rpath}, for example:
+
+\
+$ b install \
+ config.install.root=/usr/local/ \
+ config.install.private=hello/ \
+ config.bin.rpath=/usr/local/lib/hello/
+\
+
+|
\h1#module-version|\c{version} Module|