Boost logo

Boost-Build :

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-20 14:38:26

> Static and shared libaries
> Libraries can be either static, which means they are included in
> executable files that use them, or shared (a.k.a. dynamic), which
> are only referred to from executables, and must be available at run
italicize this
> time. Boost.Build can create and use both kinds.
> The kind of library produced from a lib target is determined by the
> value of the link feature.

We've already established that one feature can have different values
in different contexts in a single build. Maybe,

"determined by its value for the link feature."

?? I'm not sure that's perfect, but I think it's better.

> Default value is shared, and to build static library, the value
^^^^^^^ ^^^^^^^^ ^
"The default" ". To" "a"

> should be static. You can either requiest static build on the
^^^^^^^^^^^^^^^^ ^
"request a" "either"
> command line:
> bjam link=static
> or in the library's requirements:
> lib l : l.cpp : <link>static ;
> We can also use the <link> property to express linking requirements
> on a per-target basis. For example, if a particular executable can
an executable, important,

> be correctly built only with the static version of a library, we can
> qualify the executable's target reference to the library as follows:
> exe important : main.cpp helpers/<link>static ;


"A target reference followed by a sequence of properties,
separated by slashes, is known as a <firstterm>qualified target

[Personally I have a problem with this syntax. Slashes are just too
overloaded in the world of target references]

> No matter what arguments are specified on the bjam command-line,
> important will only be linked with the static version of helpers.
> Specifying properties in target references is especially useful if
> you use a library defined in some other project (one you can't
> change) but you still want static (or dynamic) linking to that
> library in all cases. If that library is used by many targets, you
> could use target references everywhere:
> exe e1 : e1.cpp /other_project//bar/<link>static ;
> exe e10 : e10.cpp /other_project//bar/<link>static ;
> but that's far from being convenient.
strike this

> A better approach is to introduce a level of indirection. Create a
It's cleaner to use

> local alias target that refers to the static (or dynamic) version of
> foo:
> alias foo : /other_project//bar/<link>static ;
> exe e1 : e1.cpp foo ;
> exe e10 : e10.cpp foo ;
> The alias rule is specifically used to rename a reference to a
What does this add? Strike it.
> target and possibly change the properties.

I suggest a rewrite of that sentence:

"The alias rule establishes a new name equivalent to some (possibly
qualified) target reference. The new name can thereafter be used
wherever a target name is expected."

> Tip
> When one library uses another, you put the second library is the
strike this
> source list of the first. For example:
> lib utils : utils.cpp /boost/filesystem//fs ;

use another name here, to avoid establishing a false requirement in
the reader's mind of a relationship between the library name and the
source file name.

> lib core : core.cpp utils ;

> exe app : app.cpp core ;

> This works no matter what kind of linking is used. When core is
"“just works”"
> built as a shared library, it is linked directly into utils. Static
"(on Windows it is linked to the utils import library)"
> libraries can't link to other libraries, so when core is built as a
> static library, its dependency on utils is passed along to core's
> dependents, causing app to be linked with both core and utils."
> Note
> (Note for non-UNIX system). Typically, shared libraries must be
??? the following applies to all platforms.

> installed to a directory in the dynamic linker's search path.
> Otherwise, applications that use shared libraries can't be started.
> On Windows, the dynamic linker's search path is given by the PATH
> environment variable. This restriction is lifted when you use
> Boost.Build testing facilities—the PATH variable will be
> automatically adjusted before running executable.

Likewise, on Linux, LD_LIBRARY_PATH will be automatically adjusted.
We need to say something to that effect.

Dave Abrahams
Boost Consulting

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at