[Bbv2 doc editorial] tutorial/linkage

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
^
"helpers,"
> qualify the executable's target reference to the library as follows:
> 
> exe important : main.cpp helpers/<link>static ;

Add:

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

[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 ;
^^^^
ditto

> exe app : app.cpp core ;
^^^
ditto

> 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
www.boost-consulting.com