[BBv2 doc editorial] tutorial/libs

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-20 12:42:25

> Dependent Targets
> 
> Targets that are “needed” by other targets are called dependencies
^^^^^^^^^^^
remove quotes and replace with "needed in order to build"

> of those other targets. The targets that need the other targets are
> called dependent targets.
> 
> To get a feeling of target dependencies, let's continue the above
^^^^^
Above? Remember that these things get divided into separate (web)
pages. Replace with "previous."

> example and see how top/app/Jamfile can use libraries 
> from top/util/foo. If top/util/foo/Jamfile contains
^^^^^^^^^^^^^^^^^
"defined in top/util/foo/Jamfile"
> 
> lib bar : bar.cpp ;
> 
> then to use this library in top/app/Jamfile, we can write:
> 
> exe app : app.cpp ../util/foo//bar ;
> 
> While app.cpp refers to a regular source file, ../util/foo//bar is a
> reference to another target: a library bar declared in the Jamfile at
> ../util/foo.

You need to explain a little more, with something like, "in general, 
path1//path2/name indicates a reference to the target called "name" in
the Jamfile of the subproject path2 of the project in the relative
directory location path1." I still don't understand the rules for
target references, so I have no idea if this explanation is correct.
Obviously, you need the correct explanation.

> Tip
> 
> Some other build system have special syntax for listing dependent
^
"s"
> libraries, for example LIBS variable. In Boost.Build, you just add
^^^ ^^^^^
". F" ", some use the LIBS environment"

> the library to the list of sources.
> 
> Suppose we build app with:
> 
> bjam app optimization=full define=USE_ASM
> 
> Which properties will be used to build foo? The answer is that some
^^^^^

Should be "what", since you haven't already shown a list of all
possible properties. However, you should fix the voice. Beginning
with a question is overly wordy and ultimately not helpful to the
novice. I suggest, 

app will be built with full optimization and the preprocessor symbol
USE_ASM #defined. app's dependency foo will also be built with full
optimization, but without USE_ASM #defined. This difference is due
to the fact that the optimization feature has the propagated
attribute while define does not. Boost.Build attempts to ensure
that propagated features of a target are applied to all of its
dependents.

> features are propagated—Boost.Build attempts to use dependencies
> with the same value of propagated features. The <optimization>
> feature is propagated, so both app and foo will be compiled with
> full optimization. But <define> is not propagated: its value will be
> added as-is to the compiler flags for a.cpp, but won't affect foo.
> 
> Let's improve this project further. The library probably has some
> headers that must be used when compiling app.cpp. We could manually
> add the necessary #include paths to app's requirements as values of
> the <include> feature, but then this work will be repeated for all
> programs that use foo. A better solution is to modify util/foo/
> Jamfile in this way:
> 
> project 
> : usage-requirements <include>.
> ;
> 
> lib foo : foo.cpp ;
> 
> Usage requirements are applied not to the target being declared but
> to its dependents. In this case, <include>. will be applied to all
> targets that directly depend on foo.

This example is a bit roundabout. Let's put the usage requirement on
the lib target before we show it as an attribute of the entire
subproject.

> Another improvement is using symbolic identifiers to refer to the
> library, as opposed to Jamfile location. 

"We can improve the project again by referring to the library by
a symbolic identifier rather than by its Jamfile location."

> In a large project, a library can be used by many targets, and if
> they all use Jamfile location, a change in directory organization
^^^^^^^ 
"are all referred to by" 

> entails much work. The solution is to use project ids—symbolic names
> not tied to directory layout. First, we need to assign a project id
^^^^^^^
strike that.

to what? You have to say. You don't just assign one thing; there are
always two sides to an assignment, a subject and an object.

> by adding this code to Jamroot:
> 
> use-project /library-example/foo : util/foo ;
> 
> Second, we modify app/Jamfile to use the project id:
> 
> exe app : app.cpp /library-example/foo//bar ;
> 
> The /library-example/foo//bar syntax is used to refer to the target
^ ^^^^^^^^^^^^^^^^^^^^^^^
"target reference" "refers"

> bar in the project with id /library-example/foo. We've achieved our
> goal—if the library is moved to a different directory, only Jamroot
^---"the"
> must be modified. Note that project ids are global—two Jamfiles are
^^^^---"need"
> not allowed to assign the same project id to different directories.

[Note: we really have to fix that --- it's a little embarassing]

> Tip
> 
> If you want all applications in some project to link to a certain
> library, you can avoid having to specify it directly the sources of
> every target by using the <source> property. 

replace after the comma with:

"you can use the <source> property as a project requirement to
avoid having to explicitly add the library to every target that
depends on it."

> For example, if /boost/
> filesystem//fs should be linked to all applications in your project,
> you can add <source>/boost/filesystem//fs to the project's
> requirements, like this:
> 
> project 
> : requirements <source>/boost/filesystem//fs
> ; 
> 
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com