From ac16b8eb56e5022356717cd4044dcbbdb9587771 Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Fri, 31 Jan 2003 07:48:34 +0000 Subject: [PATCH] Document static/shared libs, searched libs and mention project-root. [SVN r17102] --- boost_build_v2.html | 128 +++++++++++++++++++++++++++++++++++++++-- v2/boost_build_v2.html | 128 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 244 insertions(+), 12 deletions(-) diff --git a/boost_build_v2.html b/boost_build_v2.html index cd78867cf..a88bcbc0c 100644 --- a/boost_build_v2.html +++ b/boost_build_v2.html @@ -24,9 +24,9 @@ + - build request, build request expansion and directly requested targets + - conditional properties + -->

Using libraries +

Static and shared libraries
+
Prebuilt targets
@@ -340,6 +342,81 @@ boost-build /path/to/boost.build ; library is moved somewhere, only a single line in the top-level Jamfile should be changed. +

Static and shared libaries

+ While the previous section explained how to create and use libraries, it + omitted one important detail. Libraries can be either static, + which means they are included in executable files which use them, or + shared (a.k.a. dynamic), which are only referred to + from executables, and must be available at run time. Boost.Build can work + with both types. By default, all libraries are shared. This is much more + efficient in build time and space. But the need to install all libraries + to some location is not always convenient, especially for debug builds. + Also, if the installed shared library changes, all application which use + it might start to behave differently. + +

Static libraries do not suffer from these problems, but considerably + increase the size of application. Before describing static libraries, + it's reasonable to give another, quite simple approach. If your project + is built with <hardcode-dll-paths>true property, then the + application will include the full paths for all shared libraries, + eliminating the above problems. Unfortunately, you no longer can move + shared library to a different location, which makes this option suitable + only for debug builds. Further, only gcc compiler supports this + option.

+ +

Building a library statically is easy. You'd need to change the value + of <link> feature from it's deafault value shared, to + static. So, to build everything as static libraries, you'd + say

+
+    bjam link=static
+
+ on the command line. The linking mode can be fine-tuned on per-target + basis. + +
    +
  1. + Suppose your library can be only build statically. This is easily + achieved using requirements: +
    +    lib l : l.cpp : <link>static ;
+   
+
    +
    2. + +
  2. + What if library can be both static and shared, but when using it in + specific executable, you want it static? Target references are here to help: +
    +    exe important : main.cpp helpers/<link>static ;
+   
+
    +
    3. + +
  3. + What if the library is defined in some other project, which you + cannot change. But still, you want static linking to that library in + all cases. You can use target references everywhere: +
    +    exe e1 : e1.cpp @/other_project/lib1/<link>static ;
+    exe e10 : e10.cpp @/other_project/lib1/<link>static ;
+   
+
    + but that's far from being convenient. Another way is to introduce a + level of indirection: create a local target, which will refer to + static version of lib1. Here's the solution: +
    +    alias lib1 : @/other_project/lib1/<link>static ;
+    exe e1 : e1.cpp lib1 ;
+    exe e10 : e10.cpp lib1 ;
+   
+
    + (Note, that the "alias" target type is not yet implemented, but it's + quite simple to do. I bet it's waiting for you to do it ;-)) +
    4. +
+

Prebuilt targets

We've just learned how to use libraries which are created by Boost.Build. But some libraries are not. At the same time, those libraries can have @@ -352,7 +429,7 @@ boost-build /path/to/boost.build ; : <file>lib2_release.a <variant>release ; - prebuilt LIB lib2 + lib lib2 : : <file>lib2_debug.a <variant>debug ; @@ -366,7 +443,28 @@ boost-build /path/to/boost.build ; exe app : app.cpp @/lib/lib1/lib2 ../lib/lib2/lib2 ; If we build release version of "app", then it will be linked with - "lib2_release.a", and debug version will use "lib2_debug.a". + "lib2_release.a", and debug version will use "lib2_debug.a". Another + important kind of prebuilt targets are system libraries — more + specifically, libraries which are automatically found by the compiler. + E.g. gcc uses "-l" switch for that. Such libraries should be declared + almost like regular ones: +
+    lib zlib : : <name>z ;
+
+ We again don't specify any sources, but give a name which should be + passed to the compiler. In this example, and for gcc compiler, the "-lz" + option will be added. Paths where library should be searched can also be + specified: +
+    lib zlib : : <name>z <search>/opt/lib ;
+
+ And, of course, two variants can be used: +
+    lib zlib : : <name>z <variant>release ;
+    lib zlib : : <name>z_d <variant>debug ;
+
+ Of course, you'll probably never in your life need debug version of zlib, + but for other libraries this is quite reasonable.

Reference

This section will document mostly high-level view of Boost.Build, @@ -927,7 +1025,25 @@ borland/runtime-link=static,dynamic

Boost.Build considers every software it build as organized into projects, each of which corresponds to a single Jamfile. Projects are organized in a hierarchical structure, so each project may have a single - parent project and a number of subprojects. (TODO: project root).

+ parent project and a number of subprojects.

+ +

Each project is also associated with project root. That's a + root for a tree of projects, which specifies some global properties.

+ +

Project root

+ Project root for a projects is the nearest parent directory which + contains a file called project-root.jam. That file defines + certain properties which apply to all projects under project root. It + can: + +

Project attributes

diff --git a/v2/boost_build_v2.html b/v2/boost_build_v2.html index cd78867cf..a88bcbc0c 100644 --- a/v2/boost_build_v2.html +++ b/v2/boost_build_v2.html @@ -24,9 +24,9 @@ + - build request, build request expansion and directly requested targets + - conditional properties + -->

Using libraries +

Static and shared libraries
+
Prebuilt targets
@@ -340,6 +342,81 @@ boost-build /path/to/boost.build ; library is moved somewhere, only a single line in the top-level Jamfile should be changed. +

Static and shared libaries

+ While the previous section explained how to create and use libraries, it + omitted one important detail. Libraries can be either static, + which means they are included in executable files which use them, or + shared (a.k.a. dynamic), which are only referred to + from executables, and must be available at run time. Boost.Build can work + with both types. By default, all libraries are shared. This is much more + efficient in build time and space. But the need to install all libraries + to some location is not always convenient, especially for debug builds. + Also, if the installed shared library changes, all application which use + it might start to behave differently. + +

Static libraries do not suffer from these problems, but considerably + increase the size of application. Before describing static libraries, + it's reasonable to give another, quite simple approach. If your project + is built with <hardcode-dll-paths>true property, then the + application will include the full paths for all shared libraries, + eliminating the above problems. Unfortunately, you no longer can move + shared library to a different location, which makes this option suitable + only for debug builds. Further, only gcc compiler supports this + option.

+ +

Building a library statically is easy. You'd need to change the value + of <link> feature from it's deafault value shared, to + static. So, to build everything as static libraries, you'd + say

+
+    bjam link=static
+
+ on the command line. The linking mode can be fine-tuned on per-target + basis. + +
    +
  1. + Suppose your library can be only build statically. This is easily + achieved using requirements: +
    +    lib l : l.cpp : <link>static ;
+   
+
    +
    2. + +
  2. + What if library can be both static and shared, but when using it in + specific executable, you want it static? Target references are here to help: +
    +    exe important : main.cpp helpers/<link>static ;
+   
+
    +
    3. + +
  3. + What if the library is defined in some other project, which you + cannot change. But still, you want static linking to that library in + all cases. You can use target references everywhere: +
    +    exe e1 : e1.cpp @/other_project/lib1/<link>static ;
+    exe e10 : e10.cpp @/other_project/lib1/<link>static ;
+   
+
    + but that's far from being convenient. Another way is to introduce a + level of indirection: create a local target, which will refer to + static version of lib1. Here's the solution: +
    +    alias lib1 : @/other_project/lib1/<link>static ;
+    exe e1 : e1.cpp lib1 ;
+    exe e10 : e10.cpp lib1 ;
+   
+
    + (Note, that the "alias" target type is not yet implemented, but it's + quite simple to do. I bet it's waiting for you to do it ;-)) +
    4. +
+

Prebuilt targets

We've just learned how to use libraries which are created by Boost.Build. But some libraries are not. At the same time, those libraries can have @@ -352,7 +429,7 @@ boost-build /path/to/boost.build ; : <file>lib2_release.a <variant>release ; - prebuilt LIB lib2 + lib lib2 : : <file>lib2_debug.a <variant>debug ; @@ -366,7 +443,28 @@ boost-build /path/to/boost.build ; exe app : app.cpp @/lib/lib1/lib2 ../lib/lib2/lib2 ; If we build release version of "app", then it will be linked with - "lib2_release.a", and debug version will use "lib2_debug.a". + "lib2_release.a", and debug version will use "lib2_debug.a". Another + important kind of prebuilt targets are system libraries — more + specifically, libraries which are automatically found by the compiler. + E.g. gcc uses "-l" switch for that. Such libraries should be declared + almost like regular ones: +
+    lib zlib : : <name>z ;
+
+ We again don't specify any sources, but give a name which should be + passed to the compiler. In this example, and for gcc compiler, the "-lz" + option will be added. Paths where library should be searched can also be + specified: +
+    lib zlib : : <name>z <search>/opt/lib ;
+
+ And, of course, two variants can be used: +
+    lib zlib : : <name>z <variant>release ;
+    lib zlib : : <name>z_d <variant>debug ;
+
+ Of course, you'll probably never in your life need debug version of zlib, + but for other libraries this is quite reasonable.

Reference

This section will document mostly high-level view of Boost.Build, @@ -927,7 +1025,25 @@ borland/runtime-link=static,dynamic

Boost.Build considers every software it build as organized into projects, each of which corresponds to a single Jamfile. Projects are organized in a hierarchical structure, so each project may have a single - parent project and a number of subprojects. (TODO: project root).

+ parent project and a number of subprojects.

+ +

Each project is also associated with project root. That's a + root for a tree of projects, which specifies some global properties.

+ +

Project root

+ Project root for a projects is the nearest parent directory which + contains a file called project-root.jam. That file defines + certain properties which apply to all projects under project root. It + can: + +

Project attributes