## Installing

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 Jamfile's directory. The directory can be changed with 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, because it allows you to use a mnemonic target name.

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

    install dist : hello helpers : <variant>release:<location>dist/release
                                 <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
                 <install-type>LIB
               ;

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, because 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` rules will stip paths from it's 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.

### Installing into Several Directories

The `alias` rule can be used when targets must 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 [5] have no effect when used in requirements of the `install` rule. The only two which matter are `dependency` and, on Unix, `dll-path`.

| Note
(Unix specific). On Unix, executables built with Boost.Build typically contain the list of paths to all used dynamic 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 with the `dll-path` feature.

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