Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r57186 - in branches/release/tools/build/v2: . build doc/src kernel test test/qt4 tools tools/types util
From: ghost_at_[hidden]
Date: 2009-10-28 03:47:56

Next message: anthony_at_[hidden]: "[Boost-commit] svn:boost r57187 - trunk/status"
Previous message: steven_at_[hidden]: "[Boost-commit] svn:boost r57185 - in sandbox/tools/profile_templates: . src"

Author: vladimir_prus
Date: 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
New Revision: 57186
URL: http://svn.boost.org/trac/boost/changeset/57186

Log:
Merge Boost.Build from trunk.

Note that since regression tests are using trunk Boost.Build,
this is already tested.

Added:
   branches/release/tools/build/v2/build/__init__.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/__init__.py
   branches/release/tools/build/v2/build/alias.py
      - copied, changed from r55219, /trunk/tools/build/v2/build/alias.py
   branches/release/tools/build/v2/build/build_request.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/build_request.py
   branches/release/tools/build/v2/build/engine.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/engine.py
   branches/release/tools/build/v2/build/errors.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/errors.py
   branches/release/tools/build/v2/build/feature.py
      - copied, changed from r55219, /trunk/tools/build/v2/build/feature.py
   branches/release/tools/build/v2/build/generators.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/generators.py
   branches/release/tools/build/v2/build/project.ann.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/project.ann.py
   branches/release/tools/build/v2/build/project.py
      - copied, changed from r55219, /trunk/tools/build/v2/build/project.py
   branches/release/tools/build/v2/build/property.py
      - copied, changed from r55219, /trunk/tools/build/v2/build/property.py
   branches/release/tools/build/v2/build/property_set.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/property_set.py
   branches/release/tools/build/v2/build/scanner.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/scanner.py
   branches/release/tools/build/v2/build/targets.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/targets.py
   branches/release/tools/build/v2/build/toolset.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/toolset.py
   branches/release/tools/build/v2/build/type.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/type.py
   branches/release/tools/build/v2/build/virtual_target.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build/virtual_target.py
   branches/release/tools/build/v2/build_system.py
      - copied unchanged from r55219, /trunk/tools/build/v2/build_system.py
   branches/release/tools/build/v2/doc/src/overview.xml
      - copied unchanged from r55716, /trunk/tools/build/v2/doc/src/overview.xml
   branches/release/tools/build/v2/exceptions.py
      - copied unchanged from r55219, /trunk/tools/build/v2/exceptions.py
   branches/release/tools/build/v2/kernel/bootstrap.py
      - copied unchanged from r55219, /trunk/tools/build/v2/kernel/bootstrap.py
   branches/release/tools/build/v2/manager.py
      - copied unchanged from r55219, /trunk/tools/build/v2/manager.py
   branches/release/tools/build/v2/test/qt4/qtmultimedia.cpp
      - copied unchanged from r56139, /trunk/tools/build/v2/test/qt4/qtmultimedia.cpp
   branches/release/tools/build/v2/to_merge.sh
      - copied unchanged from r56076, /trunk/tools/build/v2/to_merge.sh
   branches/release/tools/build/v2/tools/__init__.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/__init__.py
   branches/release/tools/build/v2/tools/builtin.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/builtin.py
   branches/release/tools/build/v2/tools/common.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/common.py
   branches/release/tools/build/v2/tools/darwin.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/darwin.py
   branches/release/tools/build/v2/tools/gcc.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/gcc.py
   branches/release/tools/build/v2/tools/make.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/make.py
   branches/release/tools/build/v2/tools/pch.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/pch.py
   branches/release/tools/build/v2/tools/rc.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/rc.py
   branches/release/tools/build/v2/tools/types/__init__.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/__init__.py
   branches/release/tools/build/v2/tools/types/asm.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/asm.py
   branches/release/tools/build/v2/tools/types/cpp.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/cpp.py
   branches/release/tools/build/v2/tools/types/exe.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/exe.py
   branches/release/tools/build/v2/tools/types/html.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/html.py
   branches/release/tools/build/v2/tools/types/lib.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/lib.py
   branches/release/tools/build/v2/tools/types/obj.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/obj.py
   branches/release/tools/build/v2/tools/types/rsp.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/types/rsp.py
   branches/release/tools/build/v2/tools/unix.py
      - copied unchanged from r55219, /trunk/tools/build/v2/tools/unix.py
   branches/release/tools/build/v2/util/__init__.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/__init__.py
   branches/release/tools/build/v2/util/logger.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/logger.py
   branches/release/tools/build/v2/util/order.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/order.py
   branches/release/tools/build/v2/util/path.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/path.py
   branches/release/tools/build/v2/util/regex.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/regex.py
   branches/release/tools/build/v2/util/sequence.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/sequence.py
   branches/release/tools/build/v2/util/set.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/set.py
   branches/release/tools/build/v2/util/utility.py
      - copied unchanged from r55219, /trunk/tools/build/v2/util/utility.py
Removed:
   branches/release/tools/build/v2/doc/src/advanced.xml
Properties modified:
   branches/release/tools/build/v2/ (props changed)
Text files modified:
   branches/release/tools/build/v2/build-system.jam | 10
   branches/release/tools/build/v2/build/alias.py | 2
   branches/release/tools/build/v2/build/feature.py | 15 +
   branches/release/tools/build/v2/build/generators.jam | 15 +
   branches/release/tools/build/v2/build/project.jam | 16 +
   branches/release/tools/build/v2/build/project.py | 42 ++-
   branches/release/tools/build/v2/build/property.py | 4
   branches/release/tools/build/v2/build/targets.jam | 5
   branches/release/tools/build/v2/build/virtual-target.jam | 15 +
   branches/release/tools/build/v2/doc/src/extending.xml | 445 +++++++++++++++++++++++++++++++++++----
   branches/release/tools/build/v2/doc/src/faq.xml | 2
   branches/release/tools/build/v2/doc/src/howto.xml | 6
   branches/release/tools/build/v2/doc/src/reference.xml | 186 ----------------
   branches/release/tools/build/v2/doc/src/standalone.xml | 2
   branches/release/tools/build/v2/doc/src/tasks.xml | 6
   branches/release/tools/build/v2/doc/src/tutorial.xml | 2
   branches/release/tools/build/v2/doc/src/userman.xml | 2
   branches/release/tools/build/v2/doc/src/v1_vs_v2.xml | 14
   branches/release/tools/build/v2/index.html | 8
   branches/release/tools/build/v2/kernel/bootstrap.jam | 113 +++++++++
   branches/release/tools/build/v2/test/library_chain.py | 2
   branches/release/tools/build/v2/test/library_order.py | 2
   branches/release/tools/build/v2/test/qt4/jamroot.jam | 1
   branches/release/tools/build/v2/test/qt4/phonon.cpp | 2
   branches/release/tools/build/v2/test/searched_lib.py | 2
   branches/release/tools/build/v2/tools/builtin.jam | 4
   branches/release/tools/build/v2/tools/gcc.jam | 8
   branches/release/tools/build/v2/tools/intel-linux.jam | 4
   branches/release/tools/build/v2/tools/intel-win.jam | 3
   branches/release/tools/build/v2/tools/notfile.jam | 3
   branches/release/tools/build/v2/tools/python.jam | 57 ++++
   branches/release/tools/build/v2/tools/qt4.jam | 3
   branches/release/tools/build/v2/tools/rc.jam | 1
   33 files changed, 700 insertions(+), 302 deletions(-)

Modified: branches/release/tools/build/v2/build-system.jam
==============================================================================
--- branches/release/tools/build/v2/build-system.jam (original)
+++ branches/release/tools/build/v2/build-system.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -25,7 +25,7 @@
import utility ;
import version ;
import virtual-target ;
-
+import generators ;

################################################################################
#
@@ -686,8 +686,12 @@
     {
         targets += [ project.target [ project.module-name "." ] ] ;
     }
-
-
+
+ if [ option.get dump-generators : : true ]
+ {
+ generators.dump ;
+ }
+
     # Now that we have a set of targets to build and a set of property sets to
     # build the targets with, we can start the main build process by using each
     # property set to generate virtual targets from all of our listed targets

Copied: branches/release/tools/build/v2/build/alias.py (from r55219, /trunk/tools/build/v2/build/alias.py)
==============================================================================
--- /trunk/tools/build/v2/build/alias.py (original)
+++ branches/release/tools/build/v2/build/alias.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -3,7 +3,7 @@
# (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

# Status: ported (danielw)
-# Base revision: 40480
+# Base revision: 56043

# This module defines the 'alias' rule and associated class.
#

Copied: branches/release/tools/build/v2/build/feature.py (from r55219, /trunk/tools/build/v2/build/feature.py)
==============================================================================
--- /trunk/tools/build/v2/build/feature.py (original)
+++ branches/release/tools/build/v2/build/feature.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -1,6 +1,6 @@
# Status: mostly ported.
# TODO: carry over tests.
-# Base revision: 40480
+# Base revision: 56043
#
# Copyright 2001, 2002, 2003 Dave Abrahams
# Copyright 2002, 2006 Rene Rivera
@@ -128,7 +128,17 @@

     feature = add_grist (feature)
     f = __all_features [feature]
+ attributes = f['attributes']
+ bad_attribute = None

+ if "free" in attributes:
+ bad_attribute = "free"
+ elif "optional" in attributes:
+ bad_attribute = "optional"
+
+ if bad_attribute:
+ raise InvalidValue ("%s property %s cannot have a default" % (bad_attribute, feature))
+
     if isinstance(value, list):
         value = value[0]

@@ -370,7 +380,8 @@
     values = [value_string]

     if f['subfeatures']:
- values = value_string.split('-')
+ if not value_string in f['subfeatures']:
+ values = value_string.split('-')

     # An empty value is allowed for optional features
     if not values[0] in f['values'] and \

Modified: branches/release/tools/build/v2/build/generators.jam
==============================================================================
--- branches/release/tools/build/v2/build/generators.jam (original)
+++ branches/release/tools/build/v2/build/generators.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -722,6 +722,8 @@
#
rule register ( g )
{
+ .all-generators += $(g) ;
+
     # A generator can produce several targets of the same type. We want unique
     # occurrence of that generator in .generators.$(t) in that case, otherwise,
     # it will be tried twice and we will get a false ambiguity.
@@ -950,8 +952,10 @@
     else
     {
         local result ;
- for local s in $(source-types)
+ while $(source-types)
         {
+ local s = $(source-types[1]) ;
+ source-types = $(source-types[2-]) ;
             local viable-sources = [ generators.viable-source-types $(s) ] ;
             if $(viable-sources) = *
             {
@@ -1393,3 +1397,12 @@
         }
     }
}
+
+rule dump ( )
+{
+ for local g in $(.all-generators)
+ {
+ ECHO [ $(g).id ] ":" [ $(g).source-types ] -> [ $(g).target-types ] ;
+ }
+}
+

Modified: branches/release/tools/build/v2/build/project.jam
==============================================================================
--- branches/release/tools/build/v2/build/project.jam (original)
+++ branches/release/tools/build/v2/build/project.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -412,9 +412,18 @@
     {
         $(attributes).set source-location : [ path.make $(location) ] : exact ;
     }
- else
+ else if ! $(module-name) in test-config site-config user-config project-config
     {
- $(attributes).set source-location : "" : exact ;
+ # This is a standalone project with known location. Set source location
+ # so that it can declare targets. This is intended so that you can put
+ # a .jam file in your sources and use it via 'using'. Standard modules
+ # (in 'tools' subdir) may not assume source dir is set.
+ local s = [ modules.binding $(module-name) ] ;
+ if ! $(s)
+ {
+ errors.error "Could not determine project location $(module-name)" ;
+ }
+ $(attributes).set source-location : $(s:D) : exact ;
     }

     $(attributes).set requirements : [ property-set.empty ] : exact ;
@@ -762,7 +771,8 @@
             $(project-module) )
         {
             errors.user-error Attempt to redeclare already existing project id
- '$(id)' ;
+ '$(id)'
+ location '$(location)' ;
         }
         $(id).jamfile-module = $(project-module) ;
     }

Copied: branches/release/tools/build/v2/build/project.py (from r55219, /trunk/tools/build/v2/build/project.py)
==============================================================================
--- /trunk/tools/build/v2/build/project.py (original)
+++ branches/release/tools/build/v2/build/project.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -1,5 +1,5 @@
# Status: being ported by Vladimir Prus
-# Base revision: 40480
+# Base revision: 42507

# Copyright 2002, 2003 Dave Abrahams
# Copyright 2002, 2005, 2006 Rene Rivera
@@ -255,7 +255,7 @@
                 self.dir2jamfile[dir] = jamfile
             jamfile_glob = jamfile

- if len(jamfile_glob):
+ if len(jamfile_glob) > 1:
             # Multiple Jamfiles found in the same place. Warn about this.
             # And ensure we use only one of them.
             # As a temporary convenience measure, if there's Jamfile.v2 amount
@@ -266,8 +266,10 @@
             if len(v2_jamfiles) == 1:
                 jamfile_glob = v2_jamfiles
             else:
- print """warning: Found multiple Jamfiles at '%s'!
-Loading the first one: '%s'.""" % (dir, jamfile_glob[0])
+ print """warning: Found multiple Jamfiles at '%s'!""" % (dir)
+ for j in jamfile_glob:
+ print " -", j
+ print "Loading the first one"

         # Could not find it, error.
         if not no_errors and not jamfile_glob:
@@ -390,7 +392,7 @@
         self.module2attributes[module_name] = attributes

         if location:
- attributes.set("source-location", location, exact=1)
+ attributes.set("source-location", [location], exact=1)
         else:
             attributes.set("source-location", "", exact=1)

@@ -510,12 +512,22 @@
         """Returns the value of the specified attribute in the
         specified jamfile module."""
         return self.module2attributes[project].get(attribute)
+ try:
+ return self.module2attributes[project].get(attribute)
+ except:
+ print "Sucks", project, attribute
+ raise "Sucks"
+
+ def attributeDefault(self, project, attribute, default):
+ """Returns the value of the specified attribute in the
+ specified jamfile module."""
+ return self.module2attributes[project].getDefault(attribute, default)

     def target(self, project_module):
         """Returns the project target corresponding to the 'project-module'."""
- if not self.module2target[project_module]:
+ if not self.module2target.has_key(project_module):
             self.module2target[project_module] = \
- ProjectTarget(project_module, project_module,
+ b2.build.targets.ProjectTarget(project_module, project_module,
                               self.attribute(project_module, "requirements"))

         return self.module2target[project_module]
@@ -524,12 +536,12 @@
         # Use/load a project.
         saved_project = self.current_project
         project_module = self.load(location)
- declared_id = self.attribute(project_module, "id")
+ declared_id = self.attributeDefault(project_module, "id", "")

         if not declared_id or declared_id != id:
             # The project at 'location' either have no id or
             # that id is not equal to the 'id' parameter.
- if self.id2module[id] and self.id2module[id] != project_module:
+ if self.id2module.has_key(id) and self.id2module[id] != project_module:
                 self.manager.errors()(
"""Attempt to redeclare already existing project id '%s'""" % id)
             self.id2module[id] = project_module
@@ -743,6 +755,9 @@
     def get(self, attribute):
         return self.__dict__[attribute]

+ def getDefault(self, attribute, default):
+ return self.__dict__.get(attribute, default)
+
     def dump(self):
         """Prints the project attributes."""
         id = self.get("id")
@@ -884,7 +899,7 @@
                     attributes.set("build-dir", p, exact=1)
             elif explicit_build_dir:
                 self.registry.manager.errors()(
-"""When --build-dir is specified, the 'build-project'
+"""When --build-dir is specified, the 'build-dir'
attribute is allowed only for top-level 'project' invocations""")

     def constant(self, name, value):
@@ -905,7 +920,7 @@
         # See comment in 'load' for explanation why we record the
         # parameters as opposed to loading the project now.
         m = self.registry.current().project_module();
- self.registry.used_projects[m].append((id, where))
+ self.registry.used_projects[m].append((id[0], where[0]))

     def build_project(self, dir):
         assert(isinstance(dir, list))
@@ -993,4 +1008,7 @@
         """

         c = string.join(condition, ",")
- return [c + ":" + r for r in requirements]
+ if c.find(":") != -1:
+ return [c + r for r in requirements]
+ else:
+ return [c + ":" + r for r in requirements]

Copied: branches/release/tools/build/v2/build/property.py (from r55219, /trunk/tools/build/v2/build/property.py)
==============================================================================
--- /trunk/tools/build/v2/build/property.py (original)
+++ branches/release/tools/build/v2/build/property.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -158,11 +158,11 @@
             p = split [1]

         if get_grist (p) and 'path' in feature.attributes (get_grist (p)):
- values = __re_two_ampersands.split (forward_slashes (get_grist (p)))
+ values = __re_two_ampersands.split (forward_slashes (replace_grist (p, "")))

             t = [os.path.join(path, v) for v in values]
             t = '&&'.join (t)
- tp = backslashes_to_slashes (replace_grist (t, get_grist (p)))
+ tp = replace_grist (t, get_grist (p)).replace("\\", "/")
             result.append (condition + tp)

         else:

Modified: branches/release/tools/build/v2/build/targets.jam
==============================================================================
--- branches/release/tools/build/v2/build/targets.jam (original)
+++ branches/release/tools/build/v2/build/targets.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -1245,7 +1245,10 @@
                 source-targets += $(extra:G=) ;
                 # We might get duplicate sources, for example if we link to two
                 # libraries having the same <library> usage requirement.
- source-targets = [ sequence.unique $(source-targets) ] ;
+ # Use stable sort, since for some targets the order is
+ # important. E.g. RUN_PY target need python source to come
+ # first.
+ source-targets = [ sequence.unique $(source-targets) : stable ] ;

                 local result = [ construct $(self.name) : $(source-targets) :
                     $(rproperties) ] ;

Modified: branches/release/tools/build/v2/build/virtual-target.jam
==============================================================================
--- branches/release/tools/build/v2/build/virtual-target.jam (original)
+++ branches/release/tools/build/v2/build/virtual-target.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -113,7 +113,12 @@
     {
         return $(self.dependencies) ;
     }
-
+
+ rule always ( )
+ {
+ .always = 1 ;
+ }
+
     # Generates all the actual targets and sets up build actions for this
     # target.
     #
@@ -128,7 +133,12 @@
     rule actualize ( scanner ? )
     {
         local actual-name = [ actualize-no-scanner ] ;
-
+
+ if $(.always)
+ {
+ ALWAYS $(actual-name) ;
+ }
+
         if ! $(scanner)
         {
             return $(actual-name) ;

Deleted: branches/release/tools/build/v2/doc/src/advanced.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/advanced.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
+++ (empty file)
@@ -1,1551 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
- "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
-
- <chapter id="bbv2.advanced">
- <title>Overview</title>
-
- <para>
- This section will provide the information necessary to create your own
- projects using Boost.Build. The information provided here is relatively
- high-level, and <xref linkend="bbv2.reference"/> as well as the on-line
- help system must be used to obtain low-level documentation (see <xref
- linkend="bbv2.reference.init.options.help"/>).
- </para>
-
- <para>
- Boost.Build actually consists of two parts - Boost.Jam, a build engine
- with its own interpreted language, and Boost.Build itself, implemented in
- Boost.Jam's language. The chain of events when you type
- <command>bjam</command> on the command line is as follows:
- <orderedlist>
- <listitem>
- <para>
- Boost.Jam tries to find Boost.Build and loads the top-level module.
- The exact process is described in <xref linkend=
- "bbv2.reference.init"/>
- </para>
- </listitem>
- <listitem>
- <para>
- The top-level module loads user-defined configuration files,
- <filename>user-config.jam</filename> and <filename>site-config.jam
- </filename>, which define available toolsets.
- </para>
- </listitem>
- <listitem>
- <para>
- The Jamfile in the current directory is read. That in turn might
- cause reading of further Jamfiles. As a result, a tree of projects
- is created, with targets inside projects.
- </para>
- </listitem>
- <listitem>
- <para>
- Finally, using the build request specified on the command line,
- Boost.Build decides which targets should be built and how. That
- information is passed back to Boost.Jam, which takes care of
- actually running the scheduled build action commands.
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>
- So, to be able to successfully use Boost.Build, you need to know only four
- things:
- <itemizedlist>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.configuration">How to configure
- Boost.Build</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.targets">How to declare targets in
- Jamfiles</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.build_process">How the build process
- works</link>
- </para>
- </listitem>
- <listitem>
- <para>
- Some Basics about the Boost.Jam language. See <xref linkend=
- "bbv2.advanced.jam_language"/>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <section id="bbv2.advanced.jam_language">
- <title>Boost.Jam Language</title>
-
- <para>
- This section will describe the basics of the Boost.Jam language—
- just enough for writing Jamfiles. For more information, please see the
- <link linkend="bbv2.jam">Boost.Jam</link> documentation.
- </para>
-
- <para>
- <link linkend="bbv2.jam">Boost.Jam</link> has an interpreted, procedural
- language. On the lowest level, a <link linkend="bbv2.jam">Boost.Jam
- </link> program consists of variables and <indexterm><primary>rule
- </primary></indexterm> <firstterm>rules</firstterm> (Jam term for
- function). They are grouped into modules—there is one global
- module and a number of named modules. Besides that, a <link linkend=
- "bbv2.jam">Boost.Jam</link> program contains classes and class
- instances.
- </para>
-
- <para>
- Syntantically, a <link linkend="bbv2.jam">Boost.Jam</link> program
- consists of two kind of elements—keywords (which have a special
- meaning to <link linkend="bbv2.jam">Boost.Jam</link>) and literals.
- Consider this code:
-<programlisting>
-a = b ;
-</programlisting>
- which assigns the value <literal>b</literal> to the variable <literal>a
- </literal>. Here, <literal>=</literal> and <literal>;</literal> are
- keywords, while <literal>a</literal> and <literal>b</literal> are
- literals.
- <warning>
- <para>
- All syntax elements, even keywords, must be separated by spaces. For
- example, omitting the space character before <literal>;</literal>
- will lead to a syntax error.
- </para>
- </warning>
- If you want to use a literal value that is the same as some keyword, the
- value can be quoted:
-<programlisting>
-a = "=" ;
-</programlisting>
- </para>
-
- <para>
- All variables in <link linkend="bbv2.jam">Boost.Jam</link> have the same
- type—list of strings. To define a variable one assigns a value to
- it, like in the previous example. An undefined variable is the same as a
- variable with an empty value. Variables can be accessed using the
- <code>$(<replaceable>variable</replaceable>)</code> syntax. For example:
-<programlisting>
-a = $(b) $(c) ;
-</programlisting>
- </para>
-
- <para>
- Rules are defined by specifying the rule name, the parameter names, and
- the allowed value list size for each parameter.
-<programlisting>
-rule <replaceable>example</replaceable>
- (
- <replaceable>parameter1</replaceable> :
- <replaceable>parameter2 ?</replaceable> :
- <replaceable>parameter3 +</replaceable> :
- <replaceable>parameter4 *</replaceable>
- )
- {
- # rule body
- }
- </programlisting>
- When this rule is called, the list passed as the first argument must
- have exactly one value. The list passed as the second argument can
- either have one value of be empty. The two remaining arguments can be
- arbitrarily long, but the third argument may not be empty.
- </para>
-
- <para>
- The overview of <link linkend="bbv2.jam">Boost.Jam</link> language
- statements is given below:
-<programlisting>
-helper 1 : 2 : 3 ;
-x = [ helper 1 : 2 : 3 ] ;
-</programlisting>
- This code calls the named rule with the specified arguments. When the
- result of the call must be used inside some expression, you need to add
- brackets around the call, like shown on the second line.
-<programlisting>
-if cond { statements } [ else { statements } ]
-</programlisting>
- This is a regular if-statement. The condition is composed of:
- <itemizedlist>
- <listitem>
- <para>
- Literals (true if at least one string is not empty)
- </para>
- </listitem>
- <listitem>
- <para>
- Comparisons: <code>a <replaceable>operator</replaceable> b</code>
- where <replaceable>operator</replaceable> is one of
- <code>=</code>, <code>!=</code>, <code><</code>,
- <code>></code>, <code><=</code> or <code>>=</code>. The
- comparison is done pairwise between each string in the left and
- the right arguments.
- </para>
- </listitem>
- <listitem>
- <para>
- Logical operations: <code>! a</code>, <code>a && b</code>,
- <code>a || b</code>
- </para>
- </listitem>
- <listitem>
- <para>
- Grouping: <code>( cond )</code>
- </para>
- </listitem>
- </itemizedlist>
-<programlisting>
-for var in list { statements }
-</programlisting>
- Executes statements for each element in list, setting the variable
- <varname>var</varname> to the element value.
-<programlisting>
-while cond { statements }
-</programlisting>
- Repeatedly execute statements while cond remains true upon entry.
-<programlisting>
-return values ;
-</programlisting>
- This statement should be used only inside a rule and assigns
- <code>values</code> to the return value of the rule.
- <warning>
- <para>
- The <code>return</code> statement does not exit the rule. For
- example:
-<programlisting>
-rule test ( )
-{
- if 1 = 1
- {
- return "reasonable" ;
- }
- return "strange" ;
-}
-</programlisting>
- will return <literal>strange</literal>, not
- <literal>reasonable</literal>.
- </para>
- </warning>
-<programlisting>
-import <replaceable>module</replaceable> ;
-import <replaceable>module</replaceable> : <replaceable>rule</replaceable> ;
-</programlisting>
- The first form imports the specified bjam module. All rules from that
- module are made available using the qualified name: <code><replaceable>
- module</replaceable>.<replaceable>rule</replaceable></code>. The second
- form imports the specified rules only, and they can be called using
- unqualified names.
- </para>
-
- <para id="bbv2.advanced.jam_language.actions">
- Sometimes, you'd need to specify the actual command lines to be used
- when creating targets. In jam language, you use named actions to do
- this. For example:
-<programlisting>
-actions create-file-from-another
-{
- create-file-from-another $(<) $(>)
-}
-</programlisting>
- This specifies a named action called <literal>
- create-file-from-another</literal>. The text inside braces is the
- command to invoke. The <literal>$(<)</literal> variable will be
- expanded to a list of generated files, and the <literal>$(>)
- </literal> variable will be expanded to a list of source files.
- </para>
-
- <para>
- To flexibly adjust the command line, you can define a rule with the same
- name as the action and taking three parameters -- targets, sources and
- properties. For example:
-<programlisting>
-rule create-file-from-another ( targets * : sources * : properties * )
-{
- if <variant>debug in $(properties)
- {
- OPTIONS on $(targets) = --debug ;
- }
-}
-actions create-file-from-another
-{
- create-file-from-another $(OPTIONS) $(<) $(>)
-}
-</programlisting>
- In this example, the rule checks if certain build property is specified.
- If so, it sets variable <varname>OPIONS</varname> that is then used
- inside the action. Note that the variables set "on a target" will be
- visible only inside actions building that target, not globally. Were
- they set globally, using variable named <varname>OPTIONS</varname> in
- two unrelated actions would be impossible.
- </para>
-
- <para>
- More details can be found in Jam reference, <xref
- linkend="jam.language.rules"/>.
- </para>
- </section>
-
- <section id="bbv2.advanced.configuration">
- <title>Configuration</title>
-
- <para>
- On startup, Boost.Build searches and reads two configuration files:
- <filename>site-config.jam</filename> and <filename>user-config.jam</filename>.
- The first one is usually installed and maintained by system administrator, and
- the second is for user to modify. You can edit the one in the top-level
- directory of Boost.Build installation or create a copy in your home
- directory and edit the copy. The following table explains where both files
- are searched.
- </para>
-
- <table id="bbv2.reference.init.config">
- <title>Search paths for configuration files</title>
-
- <tgroup cols="3">
- <thead>
-
- <row>
- <entry></entry>
-
- <entry>site-config.jam</entry>
-
- <entry>user-config.jam</entry>
- </row>
-
- </thead>
- <tbody>
-
- <row>
- <entry>Linux</entry>
-
- <entry>
- <simpara><code>/etc</code></simpara>
- <simpara><code>$HOME</code></simpara>
- <simpara><code>$BOOST_BUILD_PATH</code></simpara>
- </entry>
-
- <entry>
- <simpara><code>$HOME</code></simpara>
- <simpara><code>$BOOST_BUILD_PATH</code></simpara>
- </entry>
- </row>
-
- <row>
- <entry>Windows</entry>
-
- <entry>
- <simpara><code>%SystemRoot%</code></simpara>
- <simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
- <simpara><code>%HOME%</code></simpara>
- <simpara><code>%BOOST_BUILD_PATH%</code></simpara>
- </entry>
-
- <entry>
- <simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
- <simpara><code>%HOME%</code></simpara>
- <simpara><code>%BOOST_BUILD_PATH%</code></simpara>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <tip>
- <para>
- You can use the <command>--debug-configuration</command> option to
- find which configuration files are actually loaded.
- </para>
- </tip>
-
- <para>
- Usually, <filename>user-config.jam</filename> just defines available compilers
- and other tools (see <xref linkend="bbv2.recipies.site-config"/> for more advanced
- usage). A tool is configured using the following syntax:
- </para>
-
-<programlisting>
-using <replaceable>tool-name</replaceable> : ... ;
-</programlisting>
-<para>
- The <functionname>using</functionname> rule is given a name of tool, and
- will make that tool available to Boost.Build. For example,
-<programlisting>
-using gcc ;
-</programlisting> will make the <ulink url="http://gcc.gnu.org">GCC</ulink> compiler available.
- </para>
-
- <para>
- All the supported tools are documented in <xref linkend="bbv2.reference.tools"/>,
- including the specific options they take. Some general notes that apply to most
- C++ compilers are below.
- </para>
-
- <para>
- For all the C++ compiler toolsets Boost.Build supports
- out-of-the-box, the list of parameters to
- <functionname>using</functionname> is the same: <parameter
- class="function">toolset-name</parameter>, <parameter
- class="function">version</parameter>, <parameter
- class="function">invocation-command</parameter>, and <parameter
- class="function">options</parameter>.
- </para>
-
- <para>If you have a single compiler, and the compiler executable
- <itemizedlist>
- <listitem><para>has its “usual name” and is in the
- <envar>PATH</envar>, or</para></listitem>
- <listitem><para>was installed in a standard “installation
- directory”, or</para></listitem>
- <listitem><para>can be found using a global system like the Windows
- registry.</para></listitem>
- </itemizedlist>
- it can be configured by simply:</para>
-<programlisting>
-using <replaceable>tool-name</replaceable> ;
-</programlisting>
- 
-
- <para>If the compiler is installed in a custom directory, you should provide the
- command that invokes the compiler, for example:</para>
-<programlisting>
-using gcc : : g++-3.2 ;
-using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
-</programlisting>
- <para>
- Some Boost.Build toolsets will use that path to take additional actions
- required before invoking the compiler, such as calling vendor-supplied
- scripts to set up its required environment variables. When compiler
- executables for C and C++ are different, path to the C++ compiler
- executable must be specified. The command can
- be any command allowed by the operating system. For example:
-<programlisting>
-using msvc : : echo Compiling && foo/bar/baz/cl ;
-</programlisting>
- will work.
- </para>
-
- <para>
- To configure several versions of a toolset, simply invoke the
- <functionname>using</functionname> rule multiple times:
-<programlisting>
-using gcc : 3.3 ;
-using gcc : 3.4 : g++-3.4 ;
-using gcc : 3.2 : g++-3.2 ;
-</programlisting>
- Note that in the first call to <functionname>using</functionname>, the
- compiler found in the <envar>PATH</envar> will be used, and there is no
- need to explicitly specify the command.
- </para>
-
-
-
- <para>
- Many of toolsets have an <parameter class="function">options</parameter>
- parameter to fine-tune the configuration. All of
- Boost.Build's standard compiler toolsets accept four options
- <varname>cflags</varname>, <varname>cxxflags</varname>,
- <varname>compileflags</varname> and <varname>linkflags</varname> as <parameter
- class="function">options</parameter> specifying flags that will be
- always passed to the corresponding tools. Values of the
- <varname>cflags</varname> feature are passed directly to the C
- compiler, values of the <varname>cxxflags</varname> feature are
- passed directly to the C++ compiler, and values of the
- <varname>compileflags</varname> feature are passed to both. For
- example, to configure a <command>gcc</command> toolset so that it
- always generates 64-bit code you could write:
-<programlisting>
- using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
-</programlisting>
- </para>
-
- <warning>
- <para>
- Although the syntax used to specify toolset options is very similar
- to syntax used to specify requirements in Jamfiles, the toolset options
- are not the same as features. Don't try to specify a feature value
- in toolset initialization.
- </para>
- </warning>
-
- </section>
-
- <section id="bbv2.advanced.invocation">
- <title>Invocation</title>
-
- <para>To invoke Boost.Build, type <command>bjam</command> on the command line. Three kinds
- of command-line tokens are accepted, in any order:</para>
- <variablelist>
- <varlistentry>
- <term>options</term>
-
- <listitem><para>Options start with either dash, or two dashes. The standard options
- are listed below, and each project may add additional options</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>properties</term>
-
- <listitem><para>Properties specify details of what you want to build (e.g. debug
- or release variant). Syntactically, all command line tokens with equal sign in them
- are considered to specify properties. In the simplest form, property looks like
- <command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>target</term>
-
- <listitem><para>All tokens that are neither options nor properties specify
- what targets to build. The available targets entirely depend on the project
- you are building.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <section id="bbv2.advanced.invocation.examples">
- <title>Examples</title>
-
- <para>To build all targets defined in Jamfile in the current directory with default properties, run:
-<screen>
-bjam
-</screen>
- </para>
-
- <para>To build specific targets, specify them on the command line:
-<screen>
-bjam lib1 subproject//lib2
-</screen>
- </para>
-
- <para>To request a certain value for some property, add <literal>
- <replaceable>property</replaceable>=<replaceable>value</replaceable></literal> to the command line:
-<screen>
-bjam toolset=gcc variant=debug optimization=space
-</screen>
- </para>
- </section>
-
- <section id="bbv2.advanced.invocation.options">
- <title>Options</title>
-
- <para>Boost.Build recognizes the following command line options.</para>
-
- <variablelist>
-
- <varlistentry id="bbv2.reference.init.options.help">
- <term><option>--help</option></term>
- <listitem>
- <para>Invokes the online help system. This prints general
- information on how to use the help system with additional
- --help* options.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--clean</option></term>
- <listitem>
- <para>Cleans all targets in the current directory and
- in any subprojects. Note that unlike the <literal>clean</literal>
- target in make, you can use <literal>--clean</literal>
- together with target names to clean specific targets.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--clean-all</option></term>
- <listitem>
- <para>Cleans all targets,
- no matter where they are defined. In particular, it will clean targets
- in parent Jamfiles, and targets defined under other project roots.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--build-dir</option></term>
- <listitem>
- <para>Changes build directories for all project roots being built. When
- this option is specified, all Jamroot files should declare project name.
- The build directory for the project root will be computed by concatanating
- the value of the <option>--build-dir</option> option, the project name
- specified in Jamroot, and the build dir specified in Jamroot
- (or <literal>bin</literal>, if none is specified).
- </para>
-
- <para>The option is primarily useful when building from read-only
- media, when you can't modify Jamroot.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--version</option></term>
- <listitem>
- <para>Prints information on Boost.Build and Boost.Jam
- versions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-a</option></term>
- <listitem>
- <para>Causes all files to be rebuilt.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-n</option></term>
- <listitem>
- <para>Do no execute the commands, only print them.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-d+2</option></term>
- <listitem>
- <para>Show commands as they are executed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-d0</option></term>
- <listitem>
- <para>Supress all informational messages.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-q</option></term>
- <listitem>
- <para>Stop at first error, as opposed to continuing to build targets
- that don't depend on the failed ones.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-j <replaceable>N</replaceable></option></term>
- <listitem>
- <para>Run up to <replaceable>N</replaceable> commands in parallel.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-configuration</option></term>
- <listitem>
- <para>Produces debug information about loading of Boost.Build
- and toolset files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-building</option></term>
- <listitem>
- <para>Prints what targets are being built and with what properties.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-generators</option></term>
- <listitem>
- <para>Produces debug output from generator search process.
- Useful for debugging custom generators.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--ignore-config</option></term>
- <listitem>
- <para>Do not load <literal>site-config.jam</literal> and
- <literal>user-config.jam</literal> configuration files.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="bbv2.advanced.invocation.properties">
- <title>Properties</title>
-
- <para>In the simplest case, the build is performed with a single set of properties,
- that you specify on the command line with elements in the form
- <command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>.
- The complete list of features can be found in <xref linkend="bbv2.advanced.builtins.features"/>.
- The most common features are summarized below.</para>
-
- <table>
- <tgroup cols="3">
- <thead>
-
- <row>
- <entry>Feature</entry>
-
- <entry>Allowed values</entry>
-
- <entry>Notes</entry>
- </row>
-
- </thead>
- <tbody>
-
- <row>
- <entry>variant</entry>
-
- <entry>debug,release</entry>
-
- <entry></entry>
- </row>
-
- <row>
- <entry>link</entry>
-
- <entry>shared,static</entry>
-
- <entry>Determines if Boost.Build creates shared or static libraries</entry>
- </row>
-
- <row>
- <entry>threading</entry>
-
- <entry>single,multi</entry>
-
- <entry>Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.</entry>
- </row>
-
- <row>
- <entry>address-model</entry>
-
- <entry>32,64</entry>
-
- <entry>Explicitly request either 32-bit or 64-bit code generation. This typically
- requires that your compiler is appropriately configured. Please refer to
- <xref linkend="bbv2.reference.tools.compilers"/> and your compiler documentation
- in case of problems.</entry>
- </row>
-
- <row>
- <entry>toolset</entry>
-
- <entry>(Depends on configuration)</entry>
-
- <entry>The C++ compiler to use. See <xref linkend="bbv2.reference.tools.compilers"/> for a detailed list.</entry>
- </row>
-
- <row>
- <entry>include</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Additional include paths for C and C++ compilers.</entry>
- </row>
-
- <row>
- <entry>define</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Additional macro definitions for C and C++ compilers.</entry>
- </row>
-
- <row>
- <entry>cxxflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C++ compiler.</entry>
- </row>
-
- <row>
- <entry>cflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C compiler.</entry>
- </row>
-
- <row>
- <entry>linkflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C++ linker.</entry>
- </row>
-
- <row>
- <entry>runtime-link</entry>
-
- <entry>shared,static</entry>
-
- <entry>Determines if shared or static version of C and C++ runtimes should be used.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- If you have more than one version of a given C++ toolset (e.g. configured in
- <filename>user-config.jam</filename>, or autodetected, as happens with msvc), you can
- request the specific version by passing
- <code><replaceable>toolset</replaceable>-<replaceable>version</replaceable></code> as
- the value of the <code>toolset</code> feature, for example <code>toolset=msvc-8.0</code>.
-
-
- <para>
- If a feature has a fixed set of values it can be specified more than
- once on the command line. 
- In which case, everything will be built several times --
- once for each specified value of a feature. For example, if you use
- </para>
-<screen>
-bjam link=static link=shared threading=single threading=multi
-</screen>
- <para>
- Then a total of 4 builds will be performed. For convenience,
- instead of specifying all requested values of a feature in separate command line elements,
- you can separate the values with commands, for example:
- </para>
-<screen>
-bjam link=static,shared threading=single,multi
-</screen>
- <para>
- The comma has special meaning only if the feature has a fixed set of values, so
- </para>
-<screen>
-bjam include=static,shared
-</screen>
- <para>is not treated specially.</para>
-
- </section>
-
- <section id="bbv2.advanced.invocation.targets">
- <title>Targets</title>
-
- <para>All command line elements that are neither options nor properties are the names of the
- targets to build. See <xref linkend="bbv2.reference.ids"/>. If no target is specified,
- the project in the current directory is built.</para>
- </section>
-
- </section>
-
- <section id="bbv2.advanced.targets">
- <title>Declaring Targets</title>
-
- <para id="bbv2.advanced.targets.main">
- A <firstterm>Main target</firstterm> is a user-defined named
- entity that can be built, for example an executable file.
- Declaring a main target is usually done using one of the main
- target rules described in <xref linkend=
- "bbv2.reference.rules"/>. The user can also declare
- custom main target rules as shown in <xref
- linkend="bbv2.extending.rules"/>.
- </para>
-
- <indexterm><primary>main target</primary><secondary>declaration
- syntax</secondary></indexterm>
- <para>Most main target rules in Boost.Build have the same common
- signature:</para>
-
- 
-
-<indexterm><primary>common signature</primary></indexterm>
-<anchor id="bbv2.main-target-rule-syntax"/>
-<programlisting>
-rule <replaceable>rule-name</replaceable> (
- main-target-name :
- sources + :
- requirements * :
- default-build * :
- usage-requirements * )
-</programlisting>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <parameter>main-target-name</parameter> is the name used
- to request the target on command line and to use it from
- other main targets. A main target name may contain
- alphanumeric characters, dashes
- (‘<code>-</code>’), and underscores
- (‘<code>_</code>’).
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>sources</parameter> is the list of source files and other main
- targets that must be combined.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>requirements</parameter> is the list of properties that must always
- be present when this main target is built.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>default-build</parameter> is the list of properties that will be used
- unless some other value of the same feature is already
- specified, e.g. on the command line or by propagation from a dependent target.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>usage-requirements</parameter> is the list of properties that will be
- propagated to all main targets that use this one, i.e. to all its
- dependents.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para>
- Some main target rules have a different list of parameters as explicitly
- stated in their documentation.
- </para>
-
- <para>The actual requirements for a target are obtained by refining
- requirements of the project where a target is declared with the
- explicitly specified requirements. The same is true for
- usage-requirements. More details can be found in
- <xref linkend="bbv2.reference.variants.proprefine"/>
- </para>
-
- <section>
- <title>Name</title>
-
- 
- <para>The name of main target has two purposes. First, it's used to refer to this target from
- other targets and from command line. Second, it's used to compute the names of the generated files.
- Typically, filenames are obtained from main target name by appending system-dependent suffixes and
- prefixes.
- </para>
-
- <para>The name of a main target can contain alphanumeric characters,
- dashes, undescores and dots. The entire
- name is significant when resolving references from other targets. For determining filenames, only the
- part before the first dot is taken. For example:</para>
-<programlisting>
-obj test.release : test.cpp : <variant>release ;
-obj test.debug : test.cpp : <variant>debug ;
-</programlisting>
- <para>will generate two files named <filename>test.obj</filename> (in two different directories), not
- two files named <filename>test.release.obj</filename> and <filename>test.debug.obj</filename>.
- </para>
-
- </section>
-
- <section>
- <title>Sources</title>
-
- <para>The list of sources specifies what should be processed to
- get the resulting targets. Most of the time, it's just a list of
- files. Sometimes, you'll want to automatically construct the
- list of source files rather than having to spell it out
- manually, in which case you can use the
- <functionname>glob</functionname> rule. Here are two examples:</para>
-<programlisting>
-exe a : a.cpp ; # a.cpp is the only source file
-exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources
-</programlisting>
- <para>
- Unless you specify a file with an absolute path, the name is
- considered relative to the source directory — which is typically
- the directory where the Jamfile is located, but can be changed as
- described in <xref linkend=
- "bbv2.advanced.projects.attributes.projectrule"/>.
- </para>
-
- <para>
- 
- The list of sources can also refer to other main targets. Targets in
- the same project can be referred to by name, while targets in other
- projects must be qualified with a directory or a symbolic project
- name. The directory/project name is separated from the target name by
- a double forward slash. There is no special syntax to distinguish the
- directory name from the project name—the part before the double
- slash is first looked up as project name, and then as directory name.
- For example:
- </para>
-<programlisting>
-lib helper : helper.cpp ;
-exe a : a.cpp helper ;
-# Since all project ids start with slash, ".." is a directory name.
-exe b : b.cpp ..//utils ;
-exe c : c.cpp /boost/program_options//program_options ;
-</programlisting>
- <para>
- The first exe uses the library defined in the same project. The second
- one uses some target (most likely a library) defined by a Jamfile one
- level higher. Finally, the third target uses a <ulink url=
- "http://boost.org">C++ Boost</ulink> library, referring to it using
- its absolute symbolic name. More information about target references
- can be found in <xref linkend="bbv2.tutorial.libs"/> and <xref
- linkend="bbv2.reference.ids"/>.
- </para>
- </section>
-
- <section id="bbv2.advanced.targets.requirements">
- <title>Requirements</title>
- <para>Requirements are the properties that should always be present when
- building a target. Typically, they are includes and defines:
-<programlisting>
-exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
-</programlisting>
- There is a number of other features, listed in
- <xref linkend="bbv2.advanced.builtins.features"/>. For example if
- a library can only be built statically, or a file can't be compiled
- with optimization due to a compiler bug, one can use
-<programlisting>
-lib util : util.cpp : <link>static ;
-obj main : main.cpp : <optimization>off ;
-</programlisting>
- </para>
-
- <para id="bbv2.advanced.targets.requirements.conditional">Sometimes, particular relationships need to be maintained
- among a target's build properties. This can be achieved with
- <firstterm>conditional
- requirements</firstterm>. For example, you might want to set
- specific <code>#defines</code> when a library is built as shared,
- or when a target's <code>release</code> variant is built in
- release mode.
-<programlisting>
-lib network : network.cpp
- : <emphasis role="bold"><link>shared:<define>NEWORK_LIB_SHARED</emphasis>
- <variant>release:<define>EXTRA_FAST
- ;
-</programlisting>
-
- In the example above, whenever <filename>network</filename> is
- built with <code><link>shared</code>,
- <code><define>NEWORK_LIB_SHARED</code> will be in its
- properties, too.
- </para>
-
- <para>You can use several properties in the condition, for example:
-<programlisting>
-lib network : network.cpp
- : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
- ;
-</programlisting>
- </para>
-
- <para id="bbv2.advanced.targets.requirements.indirect">
- A more powerful variant of conditional requirements
- is <firstterm>indirect conditional requirements</firstterm>.
- You can provide a rule that will be called with the current build properties and can compute additional properties
- to be added. For example:
-<programlisting>
-lib network : network.cpp
- : <conditional>@my-rule
- ;
-rule my-rule ( properties * )
-{
- local result ;
- if <toolset>gcc <optimization>speed in $(properties)
- {
- result += <define>USE_INLINE_ASSEMBLER ;
- }
- return $(result) ;
-}
-</programlisting>
- This example is equivalent to the previous one, but for complex cases, indirect conditional
- requirements can be easier to write and understand.
- </para>
-
- <para>Requirements explicitly specified for a target are usually
- combined with the requirements specified for the containing project. You
- can cause a target to completely ignore specific project's requirement
- using the syntax by adding a minus sign before a property, for example:
-<programlisting>
-exe main : main.cpp : <emphasis role="bold">-<define>UNNECESSARY_DEFINE</emphasis> ;
-</programlisting>
- This syntax is the only way to ignore free properties from a parent,
- such as defines. It can be also useful for ordinary properties. Consider
- this example:
-<programlisting>
-project test : requirements <threading>multi ;
-exe test1 : test1.cpp ;
-exe test2 : test2.cpp : <threading>single ;
-exe test3 : test3.cpp : -<threading>multi ;
-</programlisting>
- Here, <code>test1</code> inherits project requirements and will always
- be built in multi-threaded mode. The <code>test2</code> target
- <emphasis>overrides</emphasis> project's requirements and will
- always be built in single-threaded mode. In contrast, the
- <code>test3</code> target <emphasis>removes</emphasis> a property
- from project requirements and will be built either in single-threaded or
- multi-threaded mode depending on which variant is requested by the
- user.</para>
-
- <para>Note that the removal of requirements is completely textual:
- you need to specify exactly the same property to remove it.</para>
-
- </section>
-
- <section>
- <title>Default Build</title>
-
- <para>The <varname>default-build</varname> parameter
- is a set of properties to be used if the build request does
- not otherwise specify a value for features in the set. For example:
-<programlisting>
-exe hello : hello.cpp : : <threading>multi ;
-</programlisting>
- would build a multi-threaded target unless the user
- explicitly requests a single-threaded version. The difference between
- requirements and default-build is that requirements cannot be
- overridden in any way.
- </para>
- </section>
-
- <section>
- <title>Additional Information</title>
-
- <para>
- The ways a target is built can be so different that
- describing them using conditional requirements would be
- hard. For example, imagine that a library actually uses
- different source files depending on the toolset used to build
- it. We can express this situation using <firstterm>target
- alternatives</firstterm>:
-<programlisting>
-lib demangler : dummy_demangler.cpp ; # alternative 1
-lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
-lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
-</programlisting>
- In the example above, when built with <literal>gcc</literal>
- or <literal>msvc</literal>, <filename>demangler</filename>
- will use a source file specific to the toolset. Otherwise, it
- will use a generic source file,
- <filename>dummy_demangler.cpp</filename>.
- </para>
-
- <para>It is possible to declare a target inline, i.e. the "sources"
- parameter may include calls to other main rules. For example:</para>
-
-<programlisting>
-exe hello : hello.cpp
- [ obj helpers : helpers.cpp : <optimization>off ] ;</programlisting>
-
- <para>
- Will cause "helpers.cpp" to be always compiled without
- optimization. When referring to an inline main target, its declared
- name must be prefixed by its parent target's name and two dots. In
- the example above, to build only helpers, one should run
- <code>bjam hello..helpers</code>.
- </para>
-
- <para>When no target is requested on the command line, all targets in the
- current project will be built. If a target should be built only by
- explicit request, this can be expressed by the
- <functionname>explicit</functionname> rule:
- <programlisting>
-explicit install_programs ;</programlisting>
- </para>
-
- </section>
- </section>
-
- <section id="bbv2.advanced.projects">
- <title>Projects</title>
-
- <para>As mentioned before, targets are grouped into projects,
- and each Jamfile is a separate project. Projects are useful
- because they allow us to group related targets together, define
- properties common to all those targets, and assign a symbolic
- name to the project that can be used in referring to its
- targets.
- </para>
-
- <para>Projects are named using the
- <functionname>project</functionname> rule, which has the
- following syntax:
-<programlisting>
-project <replaceable>id</replaceable> : <replaceable>attributes</replaceable> ;
-</programlisting>
- Here, <replaceable>attributes</replaceable> is a sequence of
- rule arguments, each of which begins with an attribute-name
- and is followed by any number of build properties. The list
- of attribute names along with its handling is also shown in
- the table below. For example, it is possible to write:
-<programlisting>
-project tennis
- : requirements <threading>multi
- : default-build release
- ;
-</programlisting>
- </para>
-
- <para>The possible attributes are listed below.</para>
-
- <para><emphasis>Project id</emphasis> is a short way to denote a project, as
- opposed to the Jamfile's pathname. It is a hierarchical path,
- unrelated to filesystem, such as "boost/thread". <link linkend=
- "bbv2.reference.ids">Target references</link> make use of project ids to
- specify a target.</para>
- 
-
- <para><emphasis>Source location</emphasis> specifies the directory where sources
- for the project are located.</para>
-
- <para><emphasis>Project requirements</emphasis> are requirements that apply to
- all the targets in the projects as well as all subprojects.</para>
-
- <para><emphasis>Default build</emphasis> is the build request that should be
- used when no build request is specified explicitly.</para>
- 
-
- <para id="bbv2.advanced.projects.attributes.projectrule">
- The default values for those attributes are
- given in the table below.
-
- <table>
- <title/>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Attribute</entry>
-
- <entry>Name</entry>
-
- <entry>Default value</entry>
-
- <entry>Handling by the <functionname>project</functionname>
- rule</entry>
-
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>Project id</entry>
-
- <entry>none</entry>
-
- <entry>none</entry>
-
- <entry>Assigned from the first parameter of the 'project' rule.
- It is assumed to denote absolute project id.</entry>
- </row>
-
- <row>
- <entry>Source location</entry>
-
- <entry><literal>source-location</literal></entry>
-
- <entry>The location of jamfile for the project</entry>
-
- <entry>Sets to the passed value</entry>
- </row>
-
- <row>
- <entry>Requirements</entry>
-
- <entry><literal>requirements</literal></entry>
-
- <entry>The parent's requirements</entry>
-
- <entry>The parent's requirements are refined with the passed
- requirement and the result is used as the project
- requirements.</entry>
- </row>
-
- <row>
- <entry>Default build</entry>
-
- <entry><literal>default-build</literal></entry>
-
- <entry>none</entry>
-
- <entry>Sets to the passed value</entry>
- </row>
-
- <row>
- <entry>Build directory</entry>
-
- <entry><literal>build-dir</literal></entry>
-
- <entry>Empty if the parent has no build directory set.
- Otherwise, the parent's build directory with the
- relative path from parent to the current project
- appended to it.
- </entry>
-
- <entry>Sets to the passed value, interpreted as relative to the
- project's location.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>Besides defining projects and main targets, Jamfiles
- often invoke various utility rules. For the full list of rules
- that can be directly used in Jamfile see
- <xref linkend="bbv2.reference.rules"/>.
- </para>
-
- <para>Each subproject inherits attributes, constants and rules
- from its parent project, which is defined by the nearest
- Jamfile in an ancestor directory above
- the subproject. The top-level project is declared in a file
- called <filename>Jamroot</filename> rather than
- <filename>Jamfile</filename>. When loading a project,
- Boost.Build looks for either <filename>Jamroot</filename> or
- <code>Jamfile</code>. They are handled identically, except
- that if the file is called <filename>Jamroot</filename>, the
- search for a parent project is not performed.
- </para>
-
- <para>Even when building in a subproject directory, parent
- project files are always loaded before those of their
- subprojects, so that every definition made in a parent project
- is always available to its children. The loading order of any
- other projects is unspecified. Even if one project refers to
- another via the <code>use-project</code> or a target reference,
- no specific order should be assumed.
- </para>
-
- <note>
- <para>Giving the root project the special name
- “<filename>Jamroot</filename>” ensures that
- Boost.Build won't misinterpret a directory above it as the
- project root just because the directory contains a Jamfile.
- 
- </para>
- </note>
-
- 
- </section>
-
- <section id="bbv2.advanced.build_process">
- <title>The Build Process</title>
-
- <para>When you've described your targets, you want Boost.Build to run the
- right tools and create the needed targets.
- 
- This section will describe
- two things: how you specify what to build, and how the main targets are
- actually constructed.
- </para>
-
- <para>The most important thing to note is that in Boost.Build, unlike
- other build tools, the targets you declare do not correspond to specific
- files. What you declare in a Jamfile is more like a â€œmetatarget.â€
- 
- Depending on the properties you specify on the command line,
- each metatarget will produce a set of real targets corresponding
- to the requested properties. It is quite possible that the same
- metatarget is built several times with different properties,
- producing different files.
- </para>
- <tip>
- <para>
- This means that for Boost.Build, you cannot directly obtain a build
- variant from a Jamfile. There could be several variants requested by the
- user, and each target can be built with different properties.
- </para>
- </tip>
-
- <section id="bbv2.advanced.build_request">
- <title>Build Request</title>
-
- <para>
- The command line specifies which targets to build and with which
- properties. For example:
-<programlisting>
-bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
-</programlisting>
- would build two targets, "app1" and "lib1//lib1" with the specified
- properties. You can refer to any targets, using
- <link linkend="bbv2.reference.ids">target id</link> and specify arbitrary
- properties. Some of the properties are very common, and for them the name
- of the property can be omitted. For example, the above can be written as:
-<programlisting>
-bjam app1 lib1//lib1 gcc debug optimization=full
-</programlisting>
- The complete syntax, which has some additional shortcuts, is
- described in <xref linkend="bbv2.advanced.invocation"/>.
- </para>
- </section>
-
- <section><title>Building a main target</title>
-
- <para>When you request, directly or indirectly, a build of a main target
- with specific requirements, the following steps are done. Some brief
- explanation is provided, and more details are given in <xref
- linkend="bbv2.reference.buildprocess"/>.
- <orderedlist>
-
- <listitem><para>Applying default build. If the default-build
- property of a target specifies a value of a feature that is not
- present in the build request, that value is added.</para>
- 
- </listitem>
-
- <listitem><para>Selecting the main target alternative to use. For
- each alternative we look how many properties are present both in
- alternative's requirements, and in build request. The
- alternative with large number of matching properties is selected.
- </para></listitem>
-
- <listitem><para>Determining "common" properties.
- 
- The build request
- is <link linkend="bbv2.reference.variants.proprefine">refined</link>
- with target's requirements.
- 
- The conditional properties in
- requirements are handled as well. Finally, default values of
- features are added.
- </para></listitem>
-
- <listitem><para>Building targets referred by the sources list and
- dependency properties. The list of sources and the properties
- can refer to other target using <link
- linkend="bbv2.reference.ids">target references</link>. For each
- reference, we take all <link
- linkend="bbv2.reference.features.attributes.propagated">propagated</link>
- properties, refine them by explicit properties specified in the
- target reference, and pass the resulting properties as build
- request to the other target.
- </para></listitem>
-
- <listitem><para>Adding the usage requirements produced when building
- dependencies to the "common" properties. When dependencies are
- built in the previous step, they return
- 
- both the set of created
- "real" targets, and usage requirements. The usage requirements
- are added to the common properties and the resulting property
- set will be used for building the current target.
- </para></listitem>
-
- <listitem><para>Building the target using generators. To convert the
- sources to the desired type, Boost.Build uses "generators" ---
- objects that correspond to tools like compilers and linkers. Each
- generator declares what type of targets it can produce and what
- type of sources it requires. Using this information, Boost.Build
- determines which generators must be run to produce a specific
- target from specific sources. When generators are run, they return
- the "real" targets.
- </para></listitem>
-
- <listitem><para>Computing the usage requirements to be returned. The
- conditional properties in usage requirements are expanded
- 
- and the result is returned.</para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section><title>Building a Project</title>
-
- <para>Often, a user builds a complete project, not just one main
- target. In fact, invoking <command>bjam</command> without
- arguments
- 
- builds the project defined in the current
- directory.</para>
-
- <para>When a project is built, the build request is passed without
- modification to all main targets in that project.
- 
- It's is possible to
- prevent implicit building of a target in a project with the
- <code>explicit</code> rule:
-<programlisting>
-explicit hello_test ;
-</programlisting>
- would cause the <code>hello_test</code> target to be built only if
- explicitly requested by the user or by some other target.
- </para>
-
- <para>The Jamfile for a project can include a number of
- <code>build-project</code> rule calls that specify additional projects to
- be built.
- </para>
-
- </section>
-
- </section>
-
- </chapter>
-
-

Modified: branches/release/tools/build/v2/doc/src/extending.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/extending.xml (original)
+++ branches/release/tools/build/v2/doc/src/extending.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -8,64 +8,403 @@
     <section id="bbv2.extender.intro">
       <title>Introduction</title>

- <para>This document explains how to extend Boost.Build to accomodate
- your local requirements. Let's start with a simple but
- realistic example.</para>
-
- <para>Say you're writing an application that generates C++ code. If
- you ever did this, you know that it's not nice. Embedding large
- portions of C++ code in string literals is very awkward. A much
- better solution is:</para>
-
- <orderedlist>
- <listitem>
- <simpara>
- Write the template of the code to be generated, leaving
- placeholders at the points that will change
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- Access the template in your application and replace
- placeholders with appropriate text.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>Write the result.</simpara>
- </listitem>
- </orderedlist>
-
- <para>It's quite easy to achieve. You write special verbatim files that are
- just C++, except that the very first line of the file contains the name of a
- variable that should be generated. A simple tool is created that takes a
- verbatim file and creates a cpp file with a single <code>char*</code> variable
- whose name is taken from the first line of the verbatim file and whose value
- is the file's properly quoted content.</para>
+ <para>
+ This section explains how to extend Boost.Build to accomodate your
+ local requirements—primarily to add support for non-standard
+ tools you have. Before we start, be sure you have read and understoon
+ the concept of metatarget, <xref linkend="bbv2.overview.concepts"/>,
+ which is critical to understanding the remaining material.
+ </para>
+
+ <para>
+ The current version of Boost.Build has three levels of targets, listed
+ below.
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>metatarget</term>
+ <listitem>
+ <para>
+ Object that is created from declarations in Jamfiles. May
+ be called with a set of properties to produce concrete
+ targets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>concrete target</term>
+ <listitem>
+ <para>
+ Object that corresponds to a file or an action.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>jam target</term>
+ <listitem>
+ <para>
+ Low-level concrete target that is specific to Boost.Jam build
+ engine. Essentially a string—most often a name of file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>
+ In most cases, you will only have to deal with concrete targets and
+ the process that creates concrete targets from
+ metatargets. Extending metatarget level is rarely required. The jam
+ targets are typically only used inside the command line patterns.
+ </para>
+
+ <warning>
+ <para>All of the Boost.Jam target-related builtin functions, like
+ <code>DEPENDS</code> or <code>ALWAYS</code> operate on jam
+ targets. Applying them to metatargets or concrete targets has no
+ effect.</para>
+ </warning>
+
+ <section id="bbv2.extender.overview.metatargets">
+ <title>Metatargets</title>
+
+ <para>Metatarget is an object that records information specified
+ in Jamfile, such as metatarget kind, name, sources and properties,
+ and can be called with specific properties to generate concrete
+ targets. At the code level it is represented by an instance of
+ class derived from <classname>abstract-target</classname>.
+ <footnote><para>This name is historic, and will be eventuall changed to
+ <code>metatarget</code></para></footnote>
+ </para>
+
+ <para>The <methodname>generate</methodname> method takes the build properties
+ (as an instance of the <classname>property-set</classname> class) and returns
+ a list containing:</para>
+ <itemizedlist>
+ <listitem><para>As front element—Usage-requirements from this invocation
+ (an instance of <classname>property-set</classname>)</para></listitem>
+ <listitem><para>As subsequent elements—created concrete targets (
+ instances of the <classname>virtual-target</classname> class.)</para></listitem>
+ </itemizedlist>
+
+ <para>It's possible to lookup a metataget by target-id using the
+ <code>targets.resolve-reference</code> function, and the
+ <code>targets.generate-from-reference</code> function can both
+ lookup and generate a metatarget.</para>
+
+ <para>The <classname>abstract-target</classname> class has three immediate
+ derived classes:</para>
+ <itemizedlist>
+
+ <listitem><para><classname>project-target</classname> that
+ corresponds to a project and is not intended for further
+ subclassing. The <methodname>generate</methodname> method of this
+ class builds all targets in the project that are not marked as
+ explicit.</para></listitem>
+
+ <listitem><para><classname>main-target</classname> corresponds to a target in a project
+ and contains one or more target alternatives. This class also should not be
+ subclassed. The <methodname>generate</methodname> method of this class selects
+ an alternative to build, and calls the <methodname>generate</methodname> method of that
+ alternative.</para></listitem>
+
+ <listitem><para><classname>basic-target</classname> corresponds to a
+ specific target alternative. This is base class, with a number of
+ derived classes. The <methodname>generate</methodname> method
+ processes the target requirements and requested build properties to
+ determine final properties for the target, builds all sources, and
+ finally calls the abstract <classname>construct</classname> method with the list
+ of source virtual targets, and the final properties.
+ </para></listitem>
+
+ </itemizedlist>
+
+ <para>The instances of the <classname>project-target</classname> and
+ <classname>main-target</classname> classes are created
+ implicitly—when loading a new Jamfiles, or when a new target
+ alternative with as-yet unknown name is created. The instances of the
+ classes derived from <classname>basic-target</classname> are typically
+ created when Jamfile calls a <firstterm>metatarget rule</firstterm>,
+ such as such as <code>exe</code>.
+ </para>
+
+ <para>It it permissible to create a custom class derived from
+ <classname>basic-target</classname> and create new metatarget rule
+ that creates instance of such target. However, in the majority
+ of cases, a specific subclass of <classname>basic-target</classname>—
+ <classname>typed-target</classname> is used. That class is associated
+ with a <firstterm>type</firstterm> and relays to <firstterm>generators</firstterm>
+ to construct concrete targets of that type. This process will be explained below.
+ When a new type is declared, a new metatarget rule is automatically defined.
+ That rule creates new instance of type-target, associated with that type.
+ </para>
+
+ </section>
+
+ <section id="bbv2.extender.overview.targets">
+ <title>Concrete targets</title>
+
+ <para>Concrete targets are represented by instance of classes derived
+ from <classname>virtual-target</classname>. The most commonly used
+ subclass is <classname>file-target</classname>. A file target is associated
+ with an action that creates it— an instance of the <classname>action</classname>
+ class. The action, in turn, hold a list of source targets. It also holds the
+ <classname>property-set</classname> instance with the build properties that
+ should be used for the action.</para>
+
+ <para>Here's an example of creating a target from another target, <code>source</code></para>
+<programlisting>
+local a = [ new action $(source) : common.copy : $(property-set) ] ;
+local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ;
+</programlisting>
+ <para>The first line creates an instance of the <classname>action></classname> class.
+ The first parameter is the list of sources. The second parameter is the name
+ a jam-level <link linkend="bbv2.overview.jam_language.actions">action</link>.
+ The third parameter is the property-set applying to this action. The second line
+ creates a target. We specifie a name, a type and a project. We also pass the
+ action object created earlier. If the action creates several targets, we can repeat
+ the second line several times.</para>
+
+ <para>In some cases, code that creates concrete targets may be invoked more than
+ once with the same properties. Returning to different instance of <classname>file-target</classname>
+ that correspond to the same file clearly will result in problems. Therefore, whenever
+ returning targets you should pass them via the <code>virtual-target.register</code>
+ function, that will replace targets with previously created identical ones, as
+ necessary.<footnote><para>This create-then-register pattern is caused by limitations
+ of the Boost.Jam language. Python port is likely to never create duplicate targets.</para></footnote>
+ Here are a couple of examples:
+<programlisting>
+return [ virtual-target.register $(t) ] ;
+return [ sequence.transform virtual-target.register : $(targets) ] ;
+</programlisting>
+ </para>
+
+ </section>
+
+ <section id="bbv2.extender.overview.generators">
+ <title>Generators</title>
+
+ <para>In theory, every kind of metatarget in Boost.Build (like <code>exe</code>,
+ <code>lib</code> or <code>obj</code>) could be implemented
+ by writing a new metatarget class that, independently of the other code, figures
+ what files to produce and what commands to use. However, that would be rather inflexible.
+ For example, adding support for a new compiler would require editing several metatargets.
+ </para>

- <para>Let's see what Boost.Build can do.</para>
+ <para>In practice, most files have specific types, and most tools
+ consume and produce files of specific type. To take advantage of this
+ fact, Boost.Build defines concept of target type and
+ <indexterm><primary>generators</primary></indexterm>
+ <firstterm>generators</firstterm>, and has special metatarget class
+ <classname>typed-target</classname>. Target type is merely an
+ identifier. It is associated with a set of file extensions that
+ correspond to that type. Generator is an abstraction of a tool. It advertises
+ the types it produces and, if called with a set of input target, tries to construct
+ output targets of the advertised types. Finally, <classname>typed-target</classname>
+ is associated with specific target type, and relays the generator (or generators)
+ for that type.
+ </para>
+
+ <para>A generator is an instance of a class derived from <classname>generator</classname>.
+ The <classname>generator</classname> class itself is suitable for common cases.
+ You can define derived classes for custom scenarios.</para>
+
+ 

+ 
+
+ </section>
+
+ </section>
+
+ <section id="bbv2.extender.example">
+ <title>Example: 1-to-1 generator</title>
+
+ <para>Say you're writing an application that generates C++ code. If
+ you ever did this, you know that it's not nice. Embedding large
+ portions of C++ code in string literals is very awkward. A much
+ better solution is:</para>
+
+ <orderedlist>
+ <listitem>
+ <simpara>
+ Write the template of the code to be generated, leaving
+ placeholders at the points that will change
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ Access the template in your application and replace
+ placeholders with appropriate text.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>Write the result.</simpara>
+ </listitem>
+ </orderedlist>
+
+ <para>It's quite easy to achieve. You write special verbatim files that are
+ just C++, except that the very first line of the file contains the name of a
+ variable that should be generated. A simple tool is created that takes a
+ verbatim file and creates a cpp file with a single <code>char*</code> variable
+ whose name is taken from the first line of the verbatim file and whose value
+ is the file's properly quoted content.</para>
+
+ <para>Let's see what Boost.Build can do.</para>
+
+ <para>First off, Boost.Build has no idea about "verbatim files". So, you must
+ register a new target type. The following code does it:</para>
+
<programlisting>
import type ;
type.register VERBATIM : verbatim ;
</programlisting>

- <para>The first parameter to <functionname>type.register</functionname> gives
- the name of the declared type. By convention, it's uppercase. The second
- parameter is the suffix for files of this type. So, if Boost.Build sees
- <filename>code.verbatim</filename> in a list of sources, it knows that it's of
- type <code>VERBATIM</code>.</para>
-
- <para>Next, you tell Boost.Build that the verbatim files can be
- transformed into C++ files in one build step. A
- <firstterm>generator</firstterm> is a template for a build step that
- transforms targets of one type (or set of types) into another. Our
- generator will be called <code>verbatim.inline-file</code>; it
- transforms <code>VERBATIM</code> files into <code>CPP</code> files:
+ <para>The first parameter to <functionname>type.register</functionname> gives
+ the name of the declared type. By convention, it's uppercase. The second
+ parameter is the suffix for files of this type. So, if Boost.Build sees
+ <filename>code.verbatim</filename> in a list of sources, it knows that it's of
+ type <code>VERBATIM</code>.</para>
+
+ <para>Next, you tell Boost.Build that the verbatim files can be
+ transformed into C++ files in one build step. A
+ <firstterm>generator</firstterm> is a template for a build step that
+ transforms targets of one type (or set of types) into another. Our
+ generator will be called <code>verbatim.inline-file</code>; it
+ transforms <code>VERBATIM</code> files into <code>CPP</code> files:

<programlisting>
import generators ;
@@ -73,9 +412,9 @@
</programlisting>
   </para>

- <para>Lastly, you have to inform Boost.Build about the shell
- commands used to make that transformation. That's done with an
- <code>actions</code> declaration.
+ <para>Lastly, you have to inform Boost.Build about the shell
+ commands used to make that transformation. That's done with an
+ <code>actions</code> declaration.

<programlisting>
actions inline-file

Modified: branches/release/tools/build/v2/doc/src/faq.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/faq.xml (original)
+++ branches/release/tools/build/v2/doc/src/faq.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -30,7 +30,7 @@
       <listitem>
         <simpara>
           Use conditional requirements or indirect conditional requirements. See
- <xref linkend="bbv2.advanced.targets.requirements.conditional"/>.
+ <xref linkend="bbv2.overview.targets.requirements.conditional"/>.
         </simpara>
       </listitem>
       <listitem>

Modified: branches/release/tools/build/v2/doc/src/howto.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/howto.xml (original)
+++ branches/release/tools/build/v2/doc/src/howto.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -9,20 +9,20 @@
       If you've just found out about Boost.Build V2 and want to know
       if it will work for you, start with <xref linkend=
       "bbv2.tutorial" />. You can continue with <xref
- linkend="bbv2.advanced" />. When you're ready to try Boost.Build
+ linkend="bbv2.overview" />. When you're ready to try Boost.Build
       in practice, go to <xref linkend="bbv2.installation"/>.
     </para>

     <para>
       If you are about to use Boost.Build on your project, or already
       using it and have a problem, look at <xref linkend=
- "bbv2.advanced"/>.
+ "bbv2.overview"/>.
     </para>

     <para>
       If you're trying to build a project which uses Boost.Build,
       see <xref linkend="bbv2.installation"/> and then read about
- <xref linkend="bbv2.advanced.invocation"/>.
+ <xref linkend="bbv2.overview.invocation"/>.
     </para>

     <para>

Modified: branches/release/tools/build/v2/doc/src/reference.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/reference.xml (original)
+++ branches/release/tools/build/v2/doc/src/reference.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -158,7 +158,7 @@
         <term><literal>project</literal></term>

         <listitem><para>Declares project id and attributes, including
- project requirements. See <xref linkend="bbv2.advanced.projects"/>.
+ project requirements. See <xref linkend="bbv2.overview.projects"/>.
         </para></listitem>
       </varlistentry>

@@ -235,7 +235,7 @@

   </section>

- <section id="bbv2.advanced.builtins.features">
+ <section id="bbv2.overview.builtins.features">
     <title>Builtin features</title>

     <para>This section documents the features that are built-in into
@@ -299,7 +299,7 @@
         </listitem>
       </varlistentry>

- <varlistentry id="bbv2.advanced.builtins.features.link">
+ <varlistentry id="bbv2.overview.builtins.features.link">
         <term><literal>link</literal></term>

         <listitem>
@@ -314,7 +314,7 @@
         </listitem>
       </varlistentry>

- <varlistentry id="bbv2.advanced.builtins.features.runtime-link">
+ <varlistentry id="bbv2.overview.builtins.features.runtime-link">
         <indexterm><primary>runtime linking</primary></indexterm>
         <term><literal>runtime-link</literal></term>

@@ -1399,7 +1399,7 @@
     <title>Build process</title>

     <para>The general overview of the build process was given in the
- <link linkend="bbv2.advanced.build_process">user documentation</link>.
+ <link linkend="bbv2.overview.build_process">user documentation</link>.
       This section provides additional details, and some specific rules.
     </para>

@@ -1631,7 +1631,7 @@

             <para>Features of this kind are
               propagated to dependencies. That is, if a <link linkend=
- "bbv2.advanced.targets.main">main target</link> is built using a
+ "bbv2.overview.targets.main">main target</link> is built using a
               propagated
               property, the build systems attempts to use the same property
               when building any of its dependencies as part of that main
@@ -1947,180 +1947,6 @@

   </section>

- <section id="bbv2.reference.generators">
- <title>Generators</title>
-
- <warning><para>The information is this section is likely to be outdated
- and misleading.
- </para></warning>
-
- <para>To construct a main target with given properties from sources,
- it is required to create a dependency graph for that main target,
- which will also include actions to be run. The algorithm for
- creating the dependency graph is described here.</para>
-
- <para>The fundamental concept is <emphasis>generator</emphasis>. If encapsulates
- the notion of build tool and is capable to converting a set of
- input targets into a set of output targets, with some properties.
- Generator matches a build tool as closely as possible: it works
- only when the tool can work with requested properties (for
- example, msvc compiler can't work when requested toolset is gcc),
- and should produce exactly the same targets as the tool (for
- example, if Borland's linker produces additional files with debug
- information, generator should also).</para>
-
- <para>Given a set of generators, the fundamental operation is to
- construct a target of a given type, with given properties, from a
- set of targets. That operation is performed by rule
- <literal>generators.construct</literal> and the used algorithm is described
- below.</para>
-
- <section>
- <title>Selecting and ranking viable generators</title>
-
- <para>Each generator, in addition to target types that it can
- produce, have attribute that affects its applicability in
- particular sitiation. Those attributes are:</para>
-
- <orderedlist>
- <listitem>
- <simpara>
- Required properties, which are properties absolutely
- necessary for the generator to work. For example, generator
- encapsulating the gcc compiler would have <toolset>gcc as
- required property.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- Optional properties, which increase the generators
- suitability for a particual build.
- </simpara>
- </listitem>
- </orderedlist>
-
- <para>
- Generator's required and optional properties may not include
- either free or incidental properties. (Allowing this would
- greatly complicate caching targets).
- </para>
-
- <para>When trying to construct a target, the first step is to select
- all possible generators for the requested target type, which
- required properties are a subset of requested properties.
- Generators that were already selected up the call stack are
- excluded. In addition, if any composing generators were selected
- up the call stack, all other composing generators are ignored
- (TODO: define composing generators). The found generators
- are assigned a rank, which is the number of optional properties
- present in requested properties. Finally, generators with highest
- rank are selected for futher processing.</para>
-
- </section>
- <section>
- <title>Running generators</title>
-
- <para>When generators are selected, each is run to produce a list of
- created targets. This list might include targets that are not of
- requested types, because generators create the same targets as
- some tool, and tool's behaviour is fixed. (Note: should specify
- that in some cases we actually want extra targets). If generator
- fails, it returns an empty list. Generator is free to call
- 'construct' again, to convert sources to the types it can handle.
- It also can pass modified properties to 'construct'. However, a
- generator is not allowed to modify any propagated properties,
- otherwise when actually consuming properties we might discover
- that the set of propagated properties is different from what was
- used for building sources.</para>
-
- <para>For all targets that are not of requested types, we try to
- convert them to requested type, using a second call to
- <literal>construct</literal>. This is done in order to support
- transformation sequences where single source file expands to
- several later. See <ulink url=
- "http://groups.yahoo.com/group/jamboost/message/1667">this
- message</ulink> for details.</para>
-
- </section>
-
- <section>
- <title>Selecting dependency graph</title>
-
- <para>
- After all generators are run,
- it is necessary to decide which of successfull invocation will be
- taken as final result. At the moment, this is not done. Instead,
- it is checked whether all successfull generator invocation
- returned the same target list. Error is issued otherwise.
- </para>
-
- </section>
-
- <section>
- <title>Property adjustment</title>
-
- <para>Because target location is determined by the build system, it
- is sometimes necessary to adjust properties, in order to not
- break actions. For example, if there's an action that generates
- a header, say "a_parser.h", and a source file "a.cpp" which
- includes that file, we must make everything work as if a_parser.h
- is generated in the same directory where it would be generated
- without any subvariants.</para>
-
- <para>Correct property adjustment can be done only after all targets
- are created, so the approach taken is:</para>
-
- <orderedlist>
- <listitem>
- <para>
- When dependency graph is constructed, each action can be
- assigned a rule for property adjustment.
- </para>
- </listitem>
-
- <listitem>
- <para>
- When virtual target is actualized, that rule is run and
- return the final set of properties. At this stage it can use
- information of all created virtual targets.
- </para>
- </listitem>
- </orderedlist>
-
- <para>In case of quoted includes, no adjustment can give 100% correct
- results. If target dirs are not changed by build system, quoted
- includes are searched in "." and then in include path, while angle
- includes are searched only in include path. When target dirs are
- changed, we'd want to make quoted includes to be search in "." then in
- additional dirs and then in the include path and make angle includes
- be searched in include path, probably with additional paths added at
- some position. Unless, include path already has "." as the first
- element, this is not possible. So, either generated headers should not
- be included with quotes, or first element of include path should be
- ".", which essentially erases the difference between quoted and angle
- includes. <emphasis role="bold">Note:</emphasis> the only way to get
- "." as include path into compiler command line is via verbatim
- compiler option. In all other case, Boost.Build will convert "." into
- directory where it occurs.</para>
-
- </section>
-
- <section>
- <title>Transformations cache</title>
-
- <para>
- Under certain conditions, an
- attempt is made to cache results of transformation search. First,
- the sources are replaced with targets with special name and the
- found target list is stored. Later, when properties, requested
- type, and source type are the same, the store target list is
- retrieved and cloned, with appropriate change in names.
- </para>
-
- </section>
- </section>
-
</chapter>

<!--

Modified: branches/release/tools/build/v2/doc/src/standalone.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/standalone.xml (original)
+++ branches/release/tools/build/v2/doc/src/standalone.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -11,7 +11,7 @@
   <xi:include href="howto.xml"/>
   <xi:include href="install.xml"/>
   <xi:include href="tutorial.xml"/>
- <xi:include href="advanced.xml"/>
+ <xi:include href="overview.xml"/>
   <xi:include href="tasks.xml"/>
   <xi:include href="reference.xml"/>
   <xi:include href="extending.xml"/>

Modified: branches/release/tools/build/v2/doc/src/tasks.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/tasks.xml (original)
+++ branches/release/tools/build/v2/doc/src/tasks.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -12,7 +12,7 @@
   <para>
     This section describes main targets types that Boost.Build supports
     out-of-the-box. Unless otherwise noted, all mentioned main target rules have
- the common signature, described in <xref linkend="bbv2.advanced.targets"/>.
+ the common signature, described in <xref linkend="bbv2.overview.targets"/>.
   </para>

   <section id="bbv2.tasks.programs">
@@ -537,7 +537,7 @@
       If you run <command>bjam</command> and <filename>file.out</filename> does
       not exist, Boost.Build will run the <command>in2out</command> command to
       create that file. For more details on specifying actions, see <xref
- linkend="bbv2.advanced.jam_language.actions"/>.
+ linkend="bbv2.overview.jam_language.actions"/>.
     </para>

     <para>
@@ -725,7 +725,7 @@

     <para>
       When using gcc, you first need to specify your cross compiler
- in <filename>user-config.jam</filename> (see <xref linkend="bbv2.advanced.configuration"/>),
+ in <filename>user-config.jam</filename> (see <xref linkend="bbv2.overview.configuration"/>),
       for example:</para>
<programlisting>
using gcc : arm : arm-none-linux-gnueabi-g++ ;

Modified: branches/release/tools/build/v2/doc/src/tutorial.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/tutorial.xml (original)
+++ branches/release/tools/build/v2/doc/src/tutorial.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -285,7 +285,7 @@
       information</para>
     </footnote>
     More details can be found in
- <xref linkend= "bbv2.advanced.projects"/>.
+ <xref linkend= "bbv2.overview.projects"/>.
     </para>

     <para>

Modified: branches/release/tools/build/v2/doc/src/userman.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/userman.xml (original)
+++ branches/release/tools/build/v2/doc/src/userman.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -11,7 +11,7 @@
   <xi:include href="howto.xml"/>
   <xi:include href="install.xml"/>
   <xi:include href="tutorial.xml"/>
- <xi:include href="advanced.xml"/>
+ <xi:include href="overview.xml"/>
   <xi:include href="tasks.xml"/>
   <xi:include href="reference.xml"/>
   <xi:include href="extending.xml"/>

Modified: branches/release/tools/build/v2/doc/src/v1_vs_v2.xml
==============================================================================
--- branches/release/tools/build/v2/doc/src/v1_vs_v2.xml (original)
+++ branches/release/tools/build/v2/doc/src/v1_vs_v2.xml 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -16,7 +16,7 @@
   some of the syntax was changed, and some new important features were
   added. This chapter describes most of the changes.</para>

- <section id="bbv2.advanced.differences_to_v1.configuration">
+ <section id="bbv2.overview.differences_to_v1.configuration">
       <title>Configuration</title>

       <para>In V1, toolsets were configured by environment variables. If you
@@ -25,12 +25,12 @@
       toolset. In V2, toolsets are configured by the
       <functionname>using</functionname>, and you can easily configure several
       versions of a toolset. See <xref
- linkend="bbv2.advanced.configuration"/> for details.
+ linkend="bbv2.overview.configuration"/> for details.
       </para>

     </section>

- <section id="bbv2.advanced.differences_to_v1.jamfiles">
+ <section id="bbv2.overview.differences_to_v1.jamfiles">
       <title>Writing Jamfiles</title>

       <para>Probably one of the most important differences in V2 Jamfiles is
@@ -38,7 +38,7 @@
       requirements (for example, a common <code>#include</code> path), it was necessary to
       manually write the requirements or use a helper rule or template target. In V2, the
       common properties can be specified with the <code>requirements</code> project
- attribute, as documented in <xref linkend="bbv2.advanced.projects"/>.
+ attribute, as documented in <xref linkend="bbv2.overview.projects"/>.
       </para>

       <para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
@@ -54,7 +54,7 @@
       <para>The difference between <code>lib</code> and <code>dll</code> targets in V1 is completely
       eliminated in V2. There's only one library target type, <code>lib</code>, which can create
       either static or shared libraries depending on the value of the
- <link linkend="bbv2.advanced.builtins.features.link"><varname><link></varname>
+ <link linkend="bbv2.overview.builtins.features.link"><varname><link></varname>
       feature</link>. If your target should be only built in one way, you
       can add <code><link>shared</code> or <code><link>static</code> to its requirements.
       </para>
@@ -77,7 +77,7 @@

     </section>

- <section id="bbv2.advanced.differences_to_v1.build_process">
+ <section id="bbv2.overview.differences_to_v1.build_process">
       <title>Build process</title>

       <para>The command line syntax in V2 is completely different. For example
@@ -92,7 +92,7 @@
<programlisting>
bjam msvc release some_target
</programlisting>
- See <link linkend="bbv2.advanced.invocation">the reference</link> for a
+ See <link linkend="bbv2.overview.invocation">the reference</link> for a
       complete description of the syntax.
       </para>

Modified: branches/release/tools/build/v2/index.html
==============================================================================
--- branches/release/tools/build/v2/index.html (original)
+++ branches/release/tools/build/v2/index.html 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -67,7 +67,7 @@
                 <input type="submit" value="Search">
                 </form> -->
           </ul>
- <li>Bug tracker
+ <li>Bug tracker

       </ul>
     </p>
@@ -127,9 +127,9 @@
     <p>Milestone 13 is planned as bugfix release. Milestone 14 will
     focus on improving user documentation. Milestone 15 will see most
     of Boost.Build reimplemented in Python, to make extending
- Boost.Build even easier for end users (see PythonPort).
+ Boost.Build even easier for end users (see PythonPort).
     The specific issues planned for each release can be found on the
- roadmap.
+ roadmap.



@@ -139,7 +139,7 @@
     Post everything to the mailing list.</p>

     <p>Bugs and feature requests can be entered at our
- bug tracker.
+ bug tracker.

     <p>If you'd like to help with development, just pick a bug
     in the tracker that you'd like to fix, or feel free to implement

Modified: branches/release/tools/build/v2/kernel/bootstrap.jam
==============================================================================
--- branches/release/tools/build/v2/kernel/bootstrap.jam (original)
+++ branches/release/tools/build/v2/kernel/bootstrap.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -111,6 +111,8 @@
BOOST_BUILD_PATH += $(whereami:D)/$(subdirs) ;

modules.poke .ENVIRON : BOOST_BUILD_PATH : $(BOOST_BUILD_PATH) ;
+
+ modules.poke : EXTRA_PYTHONPATH : $(whereami) ;
}

# Reload the modules, to clean up things. The modules module can tolerate
@@ -129,11 +131,110 @@
#
if ! $(dont-build)
{
- # Allow users to override the build system file from the
- # command-line (mostly for testing)
- local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ;
- build-system ?= build-system ;
+ if ! [ MATCH (--python) : $(ARGV) ]
+ {
+ # Allow users to override the build system file from the
+ # command-line (mostly for testing)
+ local build-system = [ MATCH --build-system=(.*) : $(ARGV) ] ;
+ build-system ?= build-system ;

- # Use last element in case of multiple command-line options
- import $(build-system[-1]) ;
+ # Use last element in case of multiple command-line options
+ import $(build-system[-1]) ;
+ }
+ else
+ {
+ ECHO "Boost.Build V2 Python port (experimental)" ;
+
+ # Define additional interface that is exposed to Python code. Python code will
+ # also have access to select bjam builtins in the 'bjam' module, but some
+ # things are easier to define outside C.
+ module python_interface
+ {
+ rule load ( module-name : location )
+ {
+ USER_MODULE $(module-name) ;
+ # Make all rules in the loaded module available in
+ # the global namespace, so that we don't have
+ # to bother specifying "right" module when calling
+ # from Python.
+ module $(module-name)
+ {
+ __name__ = $(1) ;
+ include $(2) ;
+ local rules = [ RULENAMES $(1) ] ;
+ IMPORT $(1) : $(rules) : $(1) : $(1).$(rules) ;
+ }
+ }
+
+ rule peek ( module-name ? : variables + )
+ {
+ module $(<)
+ {
+ return $($(>)) ;
+ }
+ }
+
+ rule set-variable ( module-name : name : value * )
+ {
+ module $(<)
+ {
+ $(>) = $(3) ;
+ }
+ }
+
+ rule set-top-level-targets ( targets * )
+ {
+ DEPENDS all : $(targets) ;
+ }
+
+ rule set-update-action ( action : targets * : sources * : properties * )
+ {
+ $(action) $(targets) : $(sources) : $(properties) ;
+ }
+
+ rule set-target-variable ( targets + : variable : value * : append ? )
+ {
+ if $(append)
+ {
+ $(variable) on $(targets) += $(value) ;
+ }
+ else
+ {
+ $(variable) on $(targets) = $(value) ;
+ }
+ }
+
+ rule get-target-variable ( target : variable )
+ {
+ return [ on $(target) return $($(variable)) ] ;
+ }
+
+ rule import-rules-from-parent ( parent-module : this-module : user-rules )
+ {
+ IMPORT $(parent-module) : $(user-rules) : $(this-module) : $(user-rules) ;
+ EXPORT $(this-module) : $(user-rules) ;
+ }
+
+ rule mark-included ( targets * : includes * ) {
+ INCLUDES $(targets) : $(INCLUDES) ;
+ }
+ }
+
+ PYTHON_IMPORT_RULE bootstrap : bootstrap : PyBB : bootstrap ;
+ modules.poke PyBB : root : [ NORMALIZE_PATH $(.bootstrap-file:DT)/.. ] ;
+
+ module PyBB
+ {
+ bootstrap $(root) ;
+ }
+
+
+ #PYTHON_IMPORT_RULE boost.build.build_system : main : PyBB : main ;
+
+ #module PyBB
+ #{
+ # main ;
+ #}
+
+ }
}

Modified: branches/release/tools/build/v2/test/library_chain.py
==============================================================================
--- branches/release/tools/build/v2/test/library_chain.py (original)
+++ branches/release/tools/build/v2/test/library_chain.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -58,7 +58,7 @@
lib b : b.cpp ../a//a ;
""")

-t.run_build_system(stderr=None)
+t.run_build_system("-d2", stderr=None)
t.expect_addition("bin/$toolset/debug/main.exe")
t.rm(["bin", "a/bin", "b/bin"])

Modified: branches/release/tools/build/v2/test/library_order.py
==============================================================================
--- branches/release/tools/build/v2/test/library_order.py (original)
+++ branches/release/tools/build/v2/test/library_order.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -50,7 +50,7 @@
t.write("jamroot.jam", """
""")

-t.run_build_system()
+t.run_build_system("-d2")
t.expect_addition("bin/$toolset/debug/main.exe")

Modified: branches/release/tools/build/v2/test/qt4/jamroot.jam
==============================================================================
--- branches/release/tools/build/v2/test/qt4/jamroot.jam (original)
+++ branches/release/tools/build/v2/test/qt4/jamroot.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -37,6 +37,7 @@
       # Multimedia toolkits.
       [ link qtwebkit.cpp /qt//QtWebKit ]
       [ link phonon.cpp /qt//phonon ]
+ [ link qtmultimedia.cpp /qt//QtMultimedia ]

       # Help systems.
       [ link qthelp.cpp /qt//QtHelp ]

Modified: branches/release/tools/build/v2/test/qt4/phonon.cpp
==============================================================================
--- branches/release/tools/build/v2/test/qt4/phonon.cpp (original)
+++ branches/release/tools/build/v2/test/qt4/phonon.cpp 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -5,7 +5,7 @@

#define BOOST_TEST_MODULE QtPhonon

-#include <phonon>
+#include <Phonon/MediaObject>

#include <boost/test/unit_test.hpp>

Modified: branches/release/tools/build/v2/test/searched_lib.py
==============================================================================
--- branches/release/tools/build/v2/test/searched_lib.py (original)
+++ branches/release/tools/build/v2/test/searched_lib.py 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -68,7 +68,7 @@
helper() { foo(); }
""")

-t.run_build_system()
+t.run_build_system("-d2")
t.expect_addition("bin/$toolset/debug/main.exe")
t.rm("bin/$toolset/debug/main.exe")

Modified: branches/release/tools/build/v2/tools/builtin.jam
==============================================================================
--- branches/release/tools/build/v2/tools/builtin.jam (original)
+++ branches/release/tools/build/v2/tools/builtin.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -264,8 +264,8 @@
# The specific instruction set in an architecture to compile.
feature.feature instruction-set :
     # x86 and x86-64
- i386 i486 i586 i686 pentium pentium-mmx pentiumpro pentium2 pentium3
- pentium3m pentium-m pentium4 pentium4m prescott nocona conroe conroe-xe
+ native i386 i486 i586 i686 pentium pentium-mmx pentiumpro pentium2 pentium3
+ pentium3m pentium-m pentium4 pentium4m prescott nocona core2 conroe conroe-xe
     conroe-l allendale mermon mermon-xe kentsfield kentsfield-xe penryn wolfdale
     yorksfield nehalem k6 k6-2 k6-3 athlon athlon-tbird athlon-4 athlon-xp
     athlon-mp k8 opteron athlon64 athlon-fx winchip-c6 winchip2 c3 c3-2

Modified: branches/release/tools/build/v2/tools/gcc.jam
==============================================================================
--- branches/release/tools/build/v2/tools/gcc.jam (original)
+++ branches/release/tools/build/v2/tools/gcc.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -373,10 +373,12 @@
             {
                 option = -m32 ;
             }
- else
+ else if $(model) = 64
             {
                 option = -m64 ;
             }
+ # For darwin, the model can be 32_64. darwin.jam will handle that
+ # on its own.
         }
         OPTIONS on $(targets) += $(option) ;
     }
@@ -936,6 +938,9 @@
# Set architecture/instruction-set options.
#
# x86 and compatible
+# The 'native' option appeared in gcc 4.2 so we cannot safely use it
+# as default. Use conservative i386 instead.
+cpu-flags gcc OPTIONS : x86 : native : -march=native ;
cpu-flags gcc OPTIONS : x86 : i386 : -march=i386 : default ;
cpu-flags gcc OPTIONS : x86 : i486 : -march=i486 ;
cpu-flags gcc OPTIONS : x86 : i586 : -march=i586 ;
@@ -951,6 +956,7 @@
cpu-flags gcc OPTIONS : x86 : pentium4m : -march=pentium4m ;
cpu-flags gcc OPTIONS : x86 : prescott : -march=prescott ;
cpu-flags gcc OPTIONS : x86 : nocona : -march=nocona ;
+cpu-flags gcc OPTIONS : x86 : core2 : -march=core2 ;
cpu-flags gcc OPTIONS : x86 : k6 : -march=k6 ;
cpu-flags gcc OPTIONS : x86 : k6-2 : -march=k6-2 ;
cpu-flags gcc OPTIONS : x86 : k6-3 : -march=k6-3 ;

Modified: branches/release/tools/build/v2/tools/intel-linux.jam
==============================================================================
--- branches/release/tools/build/v2/tools/intel-linux.jam (original)
+++ branches/release/tools/build/v2/tools/intel-linux.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -118,7 +118,7 @@

actions compile.c++ bind PCH_FILE
{
- "$(CONFIG_COMMAND)" -c -xc++ $(OPTIONS) -D$(DEFINES) -I"$(INCLUDES)" -use-pch"$(PCH_FILE)" -c -o "$(<)" "$(>)"
+ "$(CONFIG_COMMAND)" -c -xc++ $(OPTIONS) $(USER_OPTIONS) -D$(DEFINES) -I"$(INCLUDES)" -use-pch"$(PCH_FILE)" -c -o "$(<)" "$(>)"
}

rule compile.c ( targets * : sources * : properties * )
@@ -131,7 +131,7 @@

actions compile.c bind PCH_FILE
{
- "$(CONFIG_COMMAND)" -c -xc $(OPTIONS) -D$(DEFINES) -I"$(INCLUDES)" -use-pch"$(PCH_FILE)" -c -o "$(<)" "$(>)"
+ "$(CONFIG_COMMAND)" -c -xc $(OPTIONS) $(USER_OPTIONS) -D$(DEFINES) -I"$(INCLUDES)" -use-pch"$(PCH_FILE)" -c -o "$(<)" "$(>)"
}

rule compile.c++.pch ( targets * : sources * : properties * )

Modified: branches/release/tools/build/v2/tools/intel-win.jam
==============================================================================
--- branches/release/tools/build/v2/tools/intel-win.jam (original)
+++ branches/release/tools/build/v2/tools/intel-win.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -25,6 +25,7 @@
generators.override intel-win.compile.c.pch : pch.default-c-pch-generator ;
generators.override intel-win.compile.c++.pch : pch.default-cpp-pch-generator ;
generators.override intel-win.compile.rc : rc.compile.resource ;
+generators.override intel-win.compile.mc : mc.compile ;

toolset.flags intel-win.compile PCH_SOURCE <pch>on : <pch-source> ;

@@ -77,6 +78,8 @@
     toolset.flags intel-win.link .LD $(condition) : $(setup)xilink ;
     toolset.flags intel-win.archive .LD $(condition) : $(setup)xilink /lib ;
     toolset.flags intel-win.link .MT $(condition) : $(setup)mt -nologo ;
+ toolset.flags intel-win.compile .MC $(condition) : $(setup)mc ;
+ toolset.flags intel-win.compile .RC $(condition) : $(setup)rc ;

     local m = [ MATCH (.).* : $(version) ] ;
     local major = $(m[1]) ;

Modified: branches/release/tools/build/v2/tools/notfile.jam
==============================================================================
--- branches/release/tools/build/v2/tools/notfile.jam (original)
+++ branches/release/tools/build/v2/tools/notfile.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -39,7 +39,8 @@
             action = [ new action $(sources) : notfile.run
               : $(property-set) ] ;
         }
- return [ new notfile-target $(name) : $(project) : $(action) ] ;
+ return [ virtual-target.register
+ [ new notfile-target $(name) : $(project) : $(action) ] ] ;
     }
}

Modified: branches/release/tools/build/v2/tools/python.jam
==============================================================================
--- branches/release/tools/build/v2/tools/python.jam (original)
+++ branches/release/tools/build/v2/tools/python.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -486,7 +486,7 @@
             python-cmd = \"$(python-cmd)\" ;
         }
         local full-cmd =
- $(python-cmd)" -c \"from sys import *; print '"$(format:J=\\n)"' % ("$(exprs:J=,)")\"" ;
+ $(python-cmd)" -c \"from sys import *; print('"$(format:J=\\n)"' % ("$(exprs:J=,)"))\"" ;

         local output = [ shell-cmd $(full-cmd) ] ;
         if $(output)
@@ -855,7 +855,7 @@
         }
         target-requirements += <python>$(version:E=default) ;
     }
-
+
     target-requirements += <target-os>$(target-os) ;

     # See if we can find a framework directory on darwin.
@@ -1064,6 +1064,18 @@

IMPORT python : python-extension : : python-extension ;

+rule py2to3
+{
+ common.copy $(>) $(<) ;
+ 2to3 $(<) ;
+}
+
+actions 2to3
+{
+ 2to3 -wn "$(<)"
+ 2to3 -dwn "$(<)"
+}
+

# Support for testing.
type.register PY : py ;
@@ -1083,8 +1095,35 @@

     rule run ( project name ? : property-set : sources * : multiple ? )
     {
+ local pyversion = [ $(property-set).get <python> ] ;
         local python ;
         local other-pythons ;
+
+ #XXX(bhy) DEBUG CODE BEGIN
+ ECHO beforerun= ;
+ for local s in $(sources)
+ {
+ ECHO [ $(s).name ] ;
+ }
+ ECHO ;
+ #XXX(bhy) DEBUG CODE END
+
+ # Make new target that converting Python source by 2to3 when running with Python 3.
+ local rule make-2to3-source ( source )
+ {
+ if $(pyversion) >= 3.0
+ {
+ local a = [ new action $(source) : python.py2to3 : $(property-set) ] ;
+ local t = [ utility.basename [ $(s).name ] ] ;
+ local p = [ new file-target $(t) : PY : $(project) : $(a) ] ;
+ return $(p) ;
+ }
+ else
+ {
+ return $(source) ;
+ }
+ }
+
         for local s in $(sources)
         {
             if [ $(s).type ] = PY
@@ -1092,12 +1131,13 @@
                 if ! $(python)
                 {
                     # First Python source ends up on command line.
- python = $(s) ;
+ python = [ make-2to3-source $(s) ] ;
+
                 }
                 else
                 {
                     # Other Python sources become dependencies.
- other-pythons += $(s) ;
+ other-pythons += [ make-2to3-source $(s) ] ;
                 }
             }
         }
@@ -1226,7 +1266,16 @@

rule bpl-test ( name : sources * : requirements * )
{
+ local s ;
     sources ?= $(name).py $(name).cpp ;
+ #XXX(bhy) DEBUG CODE BEGIN
+ ECHO bpl-test= ;
+ for local s in $(sources)
+ {
+ ECHO $(s) ;
+ }
+ ECHO ;
+ #XXX(bhy) DEBUG CODE END
     return [ testing.make-test run-pyd : $(sources) /boost/python//boost_python
         : $(requirements) : $(name) ] ;
}

Modified: branches/release/tools/build/v2/tools/qt4.jam
==============================================================================
--- branches/release/tools/build/v2/tools/qt4.jam (original)
+++ branches/release/tools/build/v2/tools/qt4.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -434,6 +434,9 @@
     # Phonon Multimedia (Qt 4.4)
     add-shared-library phonon : QtGui QtXml : QT_PHONON_LIB : $(target-requirements) ;

+ # Multimedia engine (Qt 4.6)
+ add-shared-library QtMultimedia : QtGui : QT_MULTIMEDIA_LIB : $(target-requirements) ;
+
     # XmlPatterns-Engine (Qt 4.4)
     add-shared-library QtXmlPatterns : QtNetwork : QT_XMLPATTERNS_LIB : $(target-requirements) ;

Modified: branches/release/tools/build/v2/tools/rc.jam
==============================================================================
--- branches/release/tools/build/v2/tools/rc.jam (original)
+++ branches/release/tools/build/v2/tools/rc.jam 2009-10-28 03:47:51 EDT (Wed, 28 Oct 2009)
@@ -59,6 +59,7 @@
rule compile.resource ( target : sources * : properties * )
{
local rc-type = [ on $(target) return $(.RC_TYPE) ] ;
+ rc-type ?= null ;
compile.resource.$(rc-type) $(target) : $(sources[1]) ;
}

Next message: anthony_at_[hidden]: "[Boost-commit] svn:boost r57187 - trunk/status"
Previous message: steven_at_[hidden]: "[Boost-commit] svn:boost r57185 - in sandbox/tools/profile_templates: . src"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk