Boost C++ Libraries



This section describes various ways to install built target and arbitrary files.

Basic install

For installing a built target you should use the install rule, which follows the common syntax. For example:

install dist : hello helpers ;

will cause the targets hello and helpers to be moved to the dist directory, relative to the Jamfile's directory. The directory can be changed using the location property:

install dist : hello helpers : <location>/usr/bin ;

While you can achieve the same effect by changing the target name to /usr/bin, using the location property is better as it allows you to use a mnemonic target name.

The location property is especially handy when the location is not fixed, but depends on the build variant or environment variables:

install dist : hello helpers :
    <variant>debug:<location>dist/debug ;
install dist2 : hello helpers : <location>$(DIST) ;

See also conditional properties and environment variables

Installing with all dependencies

Specifying the names of all libraries to install can be boring. The install allows you to specify only the top-level executable targets to install, and automatically install all dependencies:

install dist : hello
           : <install-dependencies>on <install-type>EXE

will find all targets that hello depends on, and install all of those which are either executables or libraries. More specifically, for each target, other targets that were specified as sources or as dependency properties, will be recursively found. One exception is that targets referred with the use feature are not considered, as that feature is typically used to refer to header-only libraries. If the set of target types is specified, only targets of that type will be installed, otherwise, all found target will be installed.

Preserving Directory Hierarchy

By default, the install rule will strip paths from its sources. So, if sources include a/b/c.hpp, the a/b part will be ignored. To make the install rule preserve the directory hierarchy you need to use the <install-source-root> feature to specify the root of the hierarchy you are installing. Relative paths from that root will be preserved. For example, if you write:

install headers
    : a/b/c.h
    : <location>/tmp <install-source-root>a

the a file named /tmp/b/c.h will be created.

The glob-tree rule can be used to find all files below a given directory, making it easy to install an entire directory tree.

Installing into Several Directories

The alias rule can be used when targets need to be installed into several directories:

alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;

Because the install rule just copies targets, most free features [3] have no effect when used in requirements of the install rule. The only two that matter are dependency and, on Unix, dll-path .


(Unix specific) On Unix, executables built using Boost.Build typically contain the list of paths to all used shared libraries. For installing, this is not desired, so Boost.Build relinks the executable with an empty list of paths. You can also specify additional paths for installed executables using the dll-path feature.

[3] see the definition of "free" in the section called “Feature Attributes”.