[BBv2 docs editorial] tutorial/prebuilt

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

[Doug G., see the end of the message please]

> Prebuilt targets
> 
> To link to libraries whose build instructions aren't given in a
"already"---^
> Jamfile, you need to create lib targets with an appropriate file
> property. Target alternatives can be used to associate multiple
> library files with a single conceptual target. 

As a Windows programmer the first question I ask here is "what about
import libraries?"

> For example:
> 
> # util/lib2/Jamfile
> lib lib2
> : 
> : <file>lib2_release.a <variant>release
> ;
> 
> lib lib2
> : 
> : <file>lib2_debug.a <variant>debug
> ;
> 
> This example defines two alternatives for lib2, and for each one
> names a prebuilt file. Naturally, there are no sources. Instead,
> the <file> feature is used to specify the file name.
> 
> Once a prebuilt target has been declared, it can be used just like
> any other target:
> 
> exe app : app.cpp ../util/lib2//lib2 ;
> 
> As with any target, the alternative selected depends on the
> properties propagated from lib2's dependents. 
^^^^^^^^^^^^^^^

Would "of" be appropriate here? I don't think the reader knows what
"propagated" means.

> If we build the the
^^^
strike this
> release and debug versions of app will be linked with
^
", they"
> lib2_release.a and lib2_debug.a, respectively.
> 
> System libraries—those that are automatically found by the toolset
> by searching through some set of predetermined paths—should be
> declared almost like regular ones:
> 
> lib pythonlib : : <name>python22 ;
> 
> We again don't specify any sources, but give a name that should be
^^^^^^^^ ^
"Again, we" "instead"
> passed to the compiler. If the gcc toolset were used to link an
> executable target to pythonlib, -lpython22 would appear in the
> command line (other compilers may use different options).
> 
> We can also specify where the toolset should look for the library:
> 
> lib pythonlib : : <name>python22 <search>/opt/lib ;

Say something like: "Note that the above adds a search path in which
to look for the library. If you know where the library is, use the
<file> feature instead."

> And, of course, target alternatives can be used in the usual way:
> 
> lib pythonlib : : <name>python22 <variant>release ;
> lib pythonlib : : <name>python22_d <variant>debug ;
> 
> A more advanced use of prebuilt targets is described in the section
> called “Targets in site-config.jam”.

We really need to get the BoostBook formatting stuff to put in proper
section references here, e.g. "described in Section X.Y, “Targets in
site-config.jam”."

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com