diff options
Diffstat (limited to 'doc/html/bbv2/tutorial/linkage.html')
| -rw-r--r-- | doc/html/bbv2/tutorial/linkage.html | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/doc/html/bbv2/tutorial/linkage.html b/doc/html/bbv2/tutorial/linkage.html new file mode 100644 index 0000000000..12b70850c7 --- /dev/null +++ b/doc/html/bbv2/tutorial/linkage.html @@ -0,0 +1,149 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Static and shared libaries</title> +<link rel="stylesheet" href="../../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> +<style type="text/css"> +body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png'); + background-repeat: no-repeat; + background-position: top left; + /* The following properties make the watermark "fixed" on the page. */ + /* I think that's just a bit too distracting for the reader... */ + /* background-attachment: fixed; */ + /* background-position: center center; */ + }</style> +<link rel="start" href="../../index.html" title="The Boost C++ Libraries"> +<link rel="up" href="../tutorial.html" title="Chapter 23. Tutorial"> +<link rel="prev" href="libs.html" title="Dependent Targets"> +<link rel="next" href="conditions.html" title="Conditions and alternatives"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"> +<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../../boost.png"></td> +<td align="center"><a href="../../../../index.htm">Home</a></td> +<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="../../../../people/people.htm">People</a></td> +<td align="center"><a href="../../../../more/faq.htm">FAQ</a></td> +<td align="center"><a href="../../../../more/index.htm">More</a></td> +</table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="libs.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="conditions.html"><img src="../../images/next.png" alt="Next"></a> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bbv2.tutorial.linkage"></a>Static and shared libaries</h2></div></div></div> +<p>Libraries can be either + <span class="emphasis"><em>static</em></span>, which means they are included in executable + files that use them, or <span class="emphasis"><em>shared</em></span> (a.k.a. + <span class="emphasis"><em>dynamic</em></span>), which are only referred to from executables, + and must be available at run time. Boost.Build can create and use both kinds. + </p> +<p>The kind of library produced from a <code class="computeroutput">lib</code> target is + determined by the value of the <code class="varname">link</code> feature. Default + value is <code class="literal">shared</code>, and to build static library, the value + should be <code class="literal">static</code>. You can either requiest static build + on the command line: + </p> +<pre class="screen"> +bjam link=static + </pre> +<p> + or in the library's requirements: + </p> +<pre class="programlisting"> +lib l : l.cpp : <link>static ; + </pre> +<p> + We can also use the <code class="varname"><link></code> property + to express linking requirements on a per-target basis. + For example, if a particular executable can be correctly built + only with the static version of a library, we can qualify the + executable's <a href="../reference/definitions.html#bbv2.reference.targets.references">target + reference</a> to the library as follows: + +</p> +<pre class="programlisting"> +exe important : main.cpp helpers/<link>static ;</pre> +<p> + + No matter what arguments are specified on the <span><strong class="command">bjam</strong></span> + command-line, <code class="filename">important</code> will only be linked with + the static version of <code class="filename">helpers</code>. + </p> +<p> + 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 <span class="emphasis"><em>could</em></span> use target references + everywhere: + + </p> +<pre class="programlisting"> +exe e1 : e1.cpp /other_project//bar/<link>static ; +exe e10 : e10.cpp /other_project//bar/<link>static ;</pre> +<p> + + but that's far from being convenient. A better approach is + to introduce a level of indirection. Create a local + <span class="type">alias</span> target that refers to the static (or + dynamic) version of <code class="filename">foo</code>: + + </p> +<pre class="programlisting"> +alias foo : /other_project//bar/<link>static ; +exe e1 : e1.cpp foo ; +exe e10 : e10.cpp foo ;</pre> +<p> + + The <a href="../advanced/builtins/targets.html#bbv2.builtins.alias" title="Alias"><code class="computeroutput">alias</code></a> + rule is specifically used to rename a reference to a target and possibly + change the properties. + + </p> +<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> +<p> + When one library uses another, you put the second library is + the source list of the first. For example: + </p> +<pre class="programlisting"> +lib utils : utils.cpp /boost/filesystem//fs ; +lib core : core.cpp utils ; +exe app : app.cpp core ;</pre> +<p> + This works no matter what kind of linking is used. When + <code class="filename">core</code> is built as a shared library, it is linked + directly into <code class="filename">utils</code>. Static libraries can't + link to other libraries, so when <code class="filename">core</code> is built + as a static library, its dependency on <code class="filename">utils</code> is passed along to + <code class="filename">core</code>'s dependents, causing + <code class="filename">app</code> to be linked with both + <code class="filename">core</code> and <code class="filename">utils</code>." + </p> +</div> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> +<p>(Note for non-UNIX system). Typically, shared libraries must be + 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 + <code class="envar">PATH</code> environment variable. This restriction is lifted + when you use Boost.Build testing facilities—the + <code class="envar">PATH</code> variable will be automatically adjusted before + running executable. + </p> +</div> +</div> +<table width="100%"><tr> +<td align="left"></td> +<td align="right"><small></small></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="libs.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="conditions.html"><img src="../../images/next.png" alt="Next"></a> +</div> +</body> +</html> |