From 3bb774d828e196ca0e36913b38e96191fc0c5073 Mon Sep 17 00:00:00 2001 From: Steven Watanabe Date: Sat, 31 Mar 2012 19:26:01 +0000 Subject: [PATCH] Redo the documentation of lib to sound less awkward. [SVN r77670] --- v2/doc/src/tasks.xml | 106 +++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 49 deletions(-) diff --git a/v2/doc/src/tasks.xml b/v2/doc/src/tasks.xml index fb163bf2e..9803afa4f 100644 --- a/v2/doc/src/tasks.xml +++ b/v2/doc/src/tasks.xml @@ -54,6 +54,11 @@ exe hello : hello.cpp some_library.lib /some_project//library
Libraries + + library + target + + Library targets are created using the lib rule, which follows the common syntax @@ -63,66 +68,71 @@ lib helpers : helpers.cpp ; This will define a library target named helpers built from the helpers.cpp source file. + It can be either a static library or a shared library, + depending on the value of the <link> feature. - Depending on the given <link> feature value the library will be - either static or shared. - - - Library targets may be used to represent: + Library targets can represent: - Built libraries that get built from specified sources, - as is the one in the example above. + Libraries that should be built from source, + as in the example above. - Prebuilt libraries which already exist on the system - and are just supposed to be used by the build system. Such - libraries may be searched for by the tools using them (typically - linkers referencing the library using the - option) or their path may be known in advance by the build system. - + Prebuilt libraries which already exist on the system. + Such libraries can be searched for by the tools using them (typically + with the linker's option) or their paths can be + known in advance by the build system. - The syntax for these case is given below: + The syntax for prebuilt libraries is given below: lib z : : <name>z <search>/home/ghost ; lib compress : : <file>/opt/libs/compress.a ; - The name property specifies the name that should be passed to - the option, and the file property - specifies the file location. The search feature - specifies paths in which to search for the library. That feature can be - specified several times or it can be omitted, in which case only the - default compiler paths will be searched. + The name property specifies the name of the library + without the standard prefixes and suffixes. For example, depending + on the system, z could refer to a file called + z.so, libz.a, or z.lib, etc. The search feature + specifies paths in which to search for the library in addition + to the default compiler paths. search can be specified + several times or it can be omitted, in which case only the default + compiler paths will be searched. The file property + specifies the file location. - The difference between using the file feature as - opposed to the name feature together with the - search feature is that file is more precise. - A specific file will be used as opposed to the search - feature only adding a library path, or the name feature - giving only the basic name of the library. The search rules are specific - to the linker used. For example, given these definition: + The difference between using the file feature and + using a combination of the name and search + features is that file is more precise. + + + + The value of the search feature is just added to the + linker search path. When linking to multiple libraries, + the paths specified by search are combined without + regard to which lib target each path came from. + Thus, given -lib a : : <variant>release <file>/pool/release/a.so ; -lib a : : <variant>debug <file>/pool/debug/a.so ; -lib b : : <variant>release <file>/pool/release/b.so ; -lib b : : <variant>debug <file>/pool/debug/b.so ; +lib a : : <name>a <search>/pool/release ; +lib b : : <name>b <search>/pool/debug ; - It is possible to use a release version of a and debug - version of b. Had we used the name and - search features, the linker would have always picked - either the release or the debug versions. - + If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so, + and /pool/release/b.so all exist, the linker will probably + take both a and b from the same + directory, instead of finding a in /pool/release + and b in /pool/debug. If you need to distinguish + between multiple libraries with the same name, it's safer + to use file. + + @@ -154,18 +164,18 @@ lib png : z : <name>png ; - When a library has a shared library defined as its source, or a static - library has another static library defined as its source then any target + When a library has a shared library as a source, or a static + library has another static library as a source then any target linking to the first library with automatically link to its source library as well. - On the other hand, when a shared library has a static library defined as - its source then the first library will be built so that it completely + On the other hand, when a shared library has a static library as + a source then the first library will be built so that it completely includes the second one. - If you do not want shared libraries to include all libraries specified + If you do not want a shared library to include all the libraries specified in its sources (especially statically linked ones), you would need to use the following: @@ -173,18 +183,16 @@ lib b : a.cpp ; lib a : a.cpp : <use>b : : <library>b ; This specifies that library a uses library b, - and causes all executables that link to a also link to - b. In this case, even for shared linking, the - a library will not even refer to b. + and causes all executables that link to a to link to + b also. In this case, even for shared linking, the + a library will not refer to b. - One Boost.Build feature that is often very useful for defining library - targets are usage requirements. For example, imagine that + + Usage requirements are often + very useful for defining library targets. For example, imagine that you want you build a helpers library and its interface is described in its helpers.hpp header file located in the same directory as the helpers.cpp source file. Then you could add