From ae9de91669cfe9fa5bb2d3b9126c3da704b57421 Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Wed, 29 Oct 2003 09:46:34 +0000 Subject: [PATCH] More docs. [SVN r20536] --- v2/boost_build_v2.html | 277 ++++++++++++++++++++++++++++++----------- 1 file changed, 204 insertions(+), 73 deletions(-) diff --git a/v2/boost_build_v2.html b/v2/boost_build_v2.html index 35f1dbe5e..9aaf1e441 100644 --- a/v2/boost_build_v2.html +++ b/v2/boost_build_v2.html @@ -22,12 +22,12 @@ div.alert { color: red } table { align: center; border: thin; } - + + - build request, build request expansion and directly requested targets + - conditional properties + -->

Overview
+
Your first project and + roadmap
+
Main targets
Projects
@@ -153,6 +156,25 @@
+

How to use this document

+ +

If you've just found out about Boost.Build V2 and want to know if it + will work for you, start with tutorial. You + can continue with the reference. When you're + ready to try Boost.Build in practice, go to installation.

+ +

If you are about to use Boost.Build on your project, or already using + it and have a problem, look at the reference.

+ +

If you're trying to build a project which uses Boost.Build, look at installation and then read about command line.

+ +

Finally, if nothing applies to you, write to our mailing list, telling + what information you'd like to know.

+

Installation

Assuming you're installing Boost.Build from released source distribution, the following steps are needed. All paths are given relatively to @@ -186,12 +208,12 @@ bjam there. A simple application will be built. You can also play with other projects in examples-v2. + it somewhere. + +

It is slighly better way is to copy new/user-config.jam + into one of the locations where it can be found (given in this table). This prevent you from + accidentally overwriting your config when updating.

--> @@ -635,74 +657,84 @@ boost-build /path/to/boost.build ; organization: related targets placed in one project, can then be built together, or share some definitions.

-

Main targets and projects are described mostly in declarative fashion. - (TODO: what "declarative fashion" means to a user?) - - To make some use of them, user issues build - request, which specifies what targets user wants to build, and what - properties are desirable. Build request is not necessary explicit. - Invoking the build system without parameters will build the project in - current directory with default properties.

+

Main targets and projects are created as the result of reading one or + several Jamfiles. Each Jamfile is a file written in Boost.Jam interpreted + language, and typically contains calls to functions provided by + Boost.Build, which create main targets of needed type, declare project + attributes and access other projects. The full list of functions provided + by Boost.Build is described below. Of course, user + can create his own functions, or it can directly access Boost.Build + internals from Jamfile, if builtin facilities are not sufficient.

-

The properties describe various aspects of constructed - objects. For portability, they are specified in a normalized form, for - example

+

Each main target, or project can be built in a number of ways, say + with optimization or without. We'll call such entities "metatargets". To + make Boost.Build produce any real targets, user issues build request, which specifies metatargets to be + built, and properties to be used.

+ +

The properties are just (name,value) pairs that describe + various aspects of constructed objects, for example:

 <optimization>full <inlining>off
- Depending on the compiler used, this will be translated into appropriate - flags. -

Construction of each main target begins with finding properties for - this main target. They are found by processing both build - request, and target requirements, which give properties needed - for the target to build. For example, a given main target might require - certian defines, or will not work unless compiled in multithreaded mode. - The process of finding properties for main target is described in property refinement.

+

Given the built request, Boost.Build figures out the targets needed + for requested metatargets with requested properties, how they can be + created, and whether exising files can be reused. It finally issues + command to create needed files, automatically converting properties into + appropricate command line options.

-

After that, dependencies (i.e. other main targets) are build - recursively. Build request for dependencies is not always equal to those - of dependent — certain properties are dropped and user can - explicitly specify desired properties for dependencies. See propagated features and target reference for details.

+

Your first project and roadmap

-

When dependencies are constructed, the dependency graph for this main - target and for this property set is created, which describes which files - need to be created, on which other files they depend and what actions are - needed to construct those files. There's more that one method, and user - can define new ones, but usually, this involves generators and - target types.

+

Creating your first project requires three steps:

-

Target type is just a way to classify targets. For example, there are - builtin types EXE, OBJ and CPP. Generators are objects that know how to convert between - different target type. When a target of a given type must be created, all - generators for that type, which can handle needed properties, are found. - Each is passed the list of sources, and either fails, or returns a - dependency graph. If a generator cannot produce desired type from given - sources, it may try to recursively construct types that it can handle - from the types is was passed. This allows to try all possible - transformations. When all generators are tried, a dependency graph is - selected.

+
    +
  1. Create an empty file called "Jamfile"
    2. -

    Finally, the dependency graph is passed to underlying Boost.Jam - program, which runs all actions needed to bring all main targets up-to - date. At this step, implicit dependencies are also scanned and accounted - for, as described here.

    +
  2. Create an empty file called "project-root.jam"
    3. + +
  3. + Either set your BOOST_BUILD_PATH environment variant to + Boost.Build root, or create a "boost-build.jam" file with the + following content: +
    +boost-build /path/to/boost.build ;
+
    +
    4. +
+ +

After that, you can run the "bjam" command in the directory where + you've created the files. Surely, it won't do anything, but it will run + without error, at least. Your next steps might be:

+ +
    +
  1. Adding new main targets to the "Jamfile" file. The basic syntax for + declaring a main target is described below, + and all builtin functions for declaring main targets are listed.
    2. + +
  2. Creating subprojects. Create a directory, put new Jamfile there, + and move some main targets to that Jamfile, or declare new ones. The projects reference will help with this part.
    3. + +
  3. Customizing Boost.Build for your needs. You might have additional + tools you want to run, or just want different extension for some file. + The extender manual is waiting for + you.
    4. +

Main targets

Main target is a user-defined named entity which can be build, for example a named executable file. Declaring a main target is usually done using one of main - target rules. The user can also declare custom main target rules.

+ target functions. The user can also declare custom main target + function.

Most main targets rules in Boost.Build use similiar syntax:

-    rule-name main-target-name 
+    function-name main-target-name 
         : sources 
         : requirements 
         : default-build 
@@ -1036,17 +1068,17 @@ boost-build /path/to/boost.build ;
 
       
  • It allows to have main target names with slashes. 
       
+                                                                        That makes good rationale for why main target must contain names.
+                                                                         -->
       
    • 
     
 
@@ -1072,12 +1104,25 @@ boost-build /path/to/boost.build ;
     
    
       
    exe
    
 
-      
    Creates a regular executable file.
    
+      
    Creates a regular executable file. Sources must be either object
+      files or libraries, and sources of different types will be converted to
+      accepted types automatically.
    
 
       
    lib
    
 
-      
    Creates a library file. Depending on the value of <link>
-      feature the library will be either static or shared.
    
+      
    
+        
    Creates a library file. Depending on the value of <link>
+        feature the library will be either static or shared. Like with "exe",
+        sources will be converted either to objects or libraries.
    
+
+        
    The handling of libraries in sources depends on whether linking is
+        static or shared. For shared linking, libraries will be linked in.
+        For static linking the library sources will not be linked in, since
+        it's not possible, and will be passed on. Other main target which
+        depend on this one will see those libraries and link to it.
+        Therefore, putting library in sources of other library works in all
+        cases.
    
+      
    
 
       
    alias
    
 
@@ -1132,6 +1177,53 @@ boost-build /path/to/boost.build ;
         expectations of people used various IDEs. It's assumed other folks
         don't have any specific expectation in this point.
    
       
+
+      
    link
    
+
+      
    
+        Feature which controls how libraries are built. 
+
+        
    Allowed values: shared, static
    
+      
    
+
+      
    library
    
+
+      
    For exe and lib main targets, the <library>X feature is
+      equvivalent to putting X in the list of sources. The feature is
+      sometimes more convenient: you can put <library>X in the
+      requirements for a project and it will be linked to all
+      executables.
    
+
+      
    use
    
+
+      
    Causes the target referenced by the value of this feature to be
+      constructed and adds it's usage requirements to build properties. The
+      constructed targets are not used in any other way. The primary use case
+      is when you use some library and want it's usage requirements (such as
+      include paths) to be applied, but don't want to link to the
+      library.
    
+
+      
    dll-path
    
+
+      
    Specify a path where dynamic libraries should be found at where
+      executable or shared library is run. This feature directly affects
+      binaries with the gcc compiler, allowing them to pick specific
+      libraries, and ignoring all environment settings. On other toolsets,
+      the binary still requires proper environment settings to be run.
+      However, Boost.Build tools which run executables will notice dll-path
+      settings and create this environment automatically.
    
+
+      
    hardcode-dll-paths
    
+
+      
    
+        Controls automatic generation of dll-path properties. 
+
+        
    Allowed values: off, on When this
+        property is on, usage requirements for each library will include
+        additional dll-path propertry, with the path the the generated
+        library file. This allows to run executables without placing all the
+        dependent libraries to a single location.
    
+      
    
     
    
 
     
    Detailed reference
    
@@ -1629,6 +1721,45 @@ borland/runtime-link=static,dynamic
 
     
    Build process
    
 
+    
    Construction of each main target begins with finding properties for
+    this main target. They are found by processing both build
+    request, and target requirements, which give properties needed
+    for the target to build. For example, a given main target might require
+    certian defines, or will not work unless compiled in multithreaded mode.
+    The process of finding properties for main target is described in property refinement.
    
+
+    
    After that, dependencies (i.e. other main targets) are build
+    recursively. Build request for dependencies is not always equal to those
+    of dependent — certain properties are dropped and user can
+    explicitly specify desired properties for dependencies. See propagated features and target reference for details.
    
+
+    
    When dependencies are constructed, the dependency graph for this main
+    target and for this property set is created, which describes which files
+    need to be created, on which other files they depend and what actions are
+    needed to construct those files. There's more that one method, and user
+    can define new ones, but usually, this involves generators and
+    target types.
    
+
+    
    Target type is just a way to classify targets. For example, there are
+    builtin types EXE, OBJ and CPP. Generators are objects that know how to convert between
+    different target type. When a target of a given type must be created, all
+    generators for that type, which can handle needed properties, are found.
+    Each is passed the list of sources, and either fails, or returns a
+    dependency graph. If a generator cannot produce desired type from given
+    sources, it may try to recursively construct types that it can handle
+    from the types is was passed. This allows to try all possible
+    transformations. When all generators are tried, a dependency graph is
+    selected.
    
+
+    
    Finally, the dependency graph is passed to underlying Boost.Jam
+    program, which runs all actions needed to bring all main targets up-to
+    date. At this step, implicit dependencies are also scanned and accounted
+    for, as described here.
    
+
     
    Given a list of targets ids and a build request, building goes this
     way. First, for each id we obtain the abstract targets corresponding to
     it. This also loads all necessary projects. If no target id is given,