From a0cfe4076e0dca4a67ce1ec0c817eacfd4a8ea3d Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Mon, 12 Aug 2002 10:35:24 +0000 Subject: [PATCH] Documentation update. * boost_build_v2.html: Extend feature description. Change wordings in some places. * new/feature.jam: Remove comments that are now in boost_build_v2.html. [SVN r14782] --- boost_build_v2.html | 198 +++++++++++++++++++++++------------------ new/feature.jam | 86 +++--------------- v2/boost_build_v2.html | 198 +++++++++++++++++++++++------------------ v2/build/feature.jam | 86 +++--------------- 4 files changed, 244 insertions(+), 324 deletions(-) diff --git a/boost_build_v2.html b/boost_build_v2.html index deea44f3c..9c7852bab 100644 --- a/boost_build_v2.html +++ b/boost_build_v2.html @@ -31,7 +31,7 @@
- This is preliminary version intended to document everything + This is a preliminary version intended to document everything implemeneted but not yet ready for any practical use.

@@ -66,24 +66,46 @@

Definition

-

A feature is a normalized (toolset-independent) description - of an individual build parameter, such as whether inlining is - enabled.

+

A feature is a normalized (toolset-independent) aspect of a + build configuration, such as whether inlining is enabled.

-

A property is a (feature, value) pair. Each features is - described by a name and the set of attributes from the following - list:

+

A feature value is a specific available setting for a + feature.

+ +

A property is a (feature,value) pair, expressed as + <feature>value.

+ +

A subfeature is a feature which only exists in the presence + of its parent, and whose identity can be derived (in the context of its + parent) from the name of its value.

+ +

A value-string is a string of the form + value-subvalue1-subvalue2...-subvalueN, where value is + a feature value and subvalue1...subvalueN are values of related + subfeatures. For example, by using value-string properties + <toolset>gcc <toolset-version>3.0.1, can be expressed more + conscicely, as <toolset>gcc-3.0.1.

+ +

A set of properties is called, naturally, property set. For + example, <toolset>gcc <runtime-link>static. + Sometimes it's better to represent a property set without spaces. In that + case property path is used, which consists of all properties, + joined with slashes. To continue with example, property path + representation would be + <toolset>gcc/<runtime-link>static .

+ +

Each feature can have any of the following attributes:

-

TODO: give a name and describe the property set joined with slashes. I - use the term "property path" somewhere below.

+

TODO: document active features..

- -

It is possible that build system tries to generate a target with a - certain set of properties but is is only possible to obtain a target with - somewhat different property set. It is needed to know if the actual - property set can be used instead of the property set that was needed. At - this moment we use a simple approach to answering that question. Two - property sets are called link-compatible when targets with those - property sets can be used interchangably. In turn, two property sets are - link compatible when there's no link-incompatible feature which has - different values in those property sets.

+

When the build system tries to generate a target (such as library + dependency) matching a given build request, it may find that an exact + match isn't possible — for example, the target may impose additonal + build requirements. We need to determine whether a buildable version of + that target can actually be used.

+ +

In general, there are many possible situations: a libary which is + dependency of a main target and should be linked into it, target which is + directly requested on the command line, or build executable which is used + in the build process itself. At this moment we use a simple approach.

+ +

Two property sets are called link-compatible when targets + with those property sets can be used interchangably. In turn, two + property sets are link compatible when there's no link-incompatible + feature which has different values in those property sets. Whenever + requested and actual properties are link-compatible, it's OK. Otherwise, + it's an error.

Definition of property refinement

@@ -219,7 +240,7 @@ set
  • If the original property set includes property with a different - value of non free-valued feature, that property is removed.
    • + value of non free feature, that property is removed.

    Initialization

    @@ -252,12 +273,17 @@

    Command line

    -

    Boost.Build extends Jam's command line in two ways. First, command - line arguments can be used not only to specify targets to build, but also - to specify build variants or arbitrary build request. Second, there are - additional command line options.

    +

    The comamnd line may contain:

    -

    Command line arguments

    + + +

    Command line arguments

    Command line arguments specify targets and build request using the following rules. @@ -361,10 +387,10 @@

    For each project, there are several attributes.

    -

    Project id is used to denote the project from other project. - Each project id is a hierarchical path, such as "boost/thread". When - project-id need to be referred from other projects there are two - alternatives:

    +

    Project id 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". There are two ways to refer to a + project using project-id:

    -
    -
    - -

    Source location specifies directory where sources for the +

    Source location specifies the directory where sources for the project are located.

    Project requirements are requirements that apply to all the @@ -499,11 +522,11 @@ like list of source and requirement.

    It is possible to have different list of sources for different - toolsets, therefore it is possible to invoce main target rules several + toolsets, therefore it is possible to invoke main target rules several times for a single main target. For example:

    -    exe a.exe : a_gcc.cpp : <toolset> ;
-    exe a.exe : a.cpp ;
+    exe a : a_gcc.cpp : <toolset> ;
+    exe a : a.cpp ;
    Each call to the 'exe' rule defines a new main target alternative for the main target a.exe. In this case, the @@ -513,8 +536,8 @@

    Target identifiers and references

    -

    Target identifier is used to denote a target. It is described by the - following grammar:

    +

    Target identifier is used to denote a target. It is described + by the following grammar:

         target-id -> project-reference local-target-name
     project-reference -> [jamfile-location] [ "@" [project-id] ]
@@ -546,7 +569,7 @@
     After that, the target given by local-target-name in the found
     project is used. 
 
-    
    Target reference is used to specify a source target, and may
+    
    Target reference is used to specify a source target, and may
     additionally specify desired properties for that target. It has this
     syntax:
    
 
    @@ -557,9 +580,9 @@
 
         exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
 
    
-    would cause the version of cmdline library, optimized to space,
+    would cause the version of cmdline library, optimized for space,
     to be linked in even if the compile executable is build with
-    speed optimization. 
+    optimization for speed. 
 
     
    Ambiguity resolution
    
 
@@ -568,7 +591,7 @@
     pathname, it is checked if there's a jamfile in the specified path. If
     there is one, it is loaded and if the specified target is declared by
     that project it is used. Otherwise, we just treat the target reference as
-    file name.
    
+    a file name.
    
 
     
    Target paths
    
 
@@ -580,17 +603,18 @@
       
  • All targets are placed under directory corresponding to the project
       where they are defined.
    • 
 
-      
  • Each non free-valued, non incident property cause an additional
-      element to be added to the target path. That element has the form
+      
  • Each non free, non incidental property cause an additional element
+      to be added to the target path. That element has the form
       <feature-name>-<feature-value> for ordinary
       features and <feature-value> for implicit ones. [Note
       about composite features].
    • 
 
-      
  • If the set of free-valued properties is different from the set of
-      free valued properties for the project to which the target belong, a
-      part of the form main_target-<name> is added to the
-      target path. Note:It would be nice to track free-valued features
-      also, but this appears to be complex and not extremely needed.
    • 
+      
  • If the set of free, non incidental properties is different from the
+      set of free, non incidental properties for the project in which the
+      main target that uses the target is defined, a part of the form
+      main_target-<name> is added to the target path.
+      Note:It would be nice to completely track free features also,
+      but this appears to be complex and not extremely needed.
    • 
     
 
     
    For example, we might have these paths:
    
@@ -603,15 +627,17 @@
     
    Build process
    
 
     
    The build works in this way. On startup, the project in the current
-    directory is read. As the result a tree of projects is constructed. After
-    that, the build request is constructed from the command line. Then, the
-    steps are:
    
+    directory is read. In turn, it may request building of other projects,
+    which will be loaded recursively. Parent projects are also loaded to
+    inherit some of their properties. As the result, a tree of projects is
+    constructed. After that, the build request is constructed from the
+    command line. Then, the steps are:
    
 
     
      
-      
    1. The project in the current dir is passed the build request. If the
-      build request does not satisfy the project's requirements, a warning is
-      issued and the build of the project is skipped. Otherwise, the process
-      is repeated recusrively for all subprojects.
      2. 
+      
    2. All of the projects to be build are passed the build request. If
+      the build request does not satisfy the project's requirements, a
+      warning is issued and the build of the project is skipped. Projects
+      mentioned in build-project rule will still be build.
      3. 
 
       
    3. 
         An attempts to make all the main targets in the project is performed.
@@ -645,7 +671,7 @@
     therefore converted to jam's dependency graph which is then build.
      
     
      
 
-    
      Last modified: Aug 5, 2002
      
+    
      Last modified: Aug 12, 2002
      
 
     
      © Copyright Vladimir Prus 2002. Permission to copy, use, modify,
     sell and distribute this document is granted provided this copyright
diff --git a/new/feature.jam b/new/feature.jam
index 6f3d8e2e3..577ae91e4 100644
--- a/new/feature.jam
+++ b/new/feature.jam
@@ -3,23 +3,6 @@
 #  all copies. This software is provided "as is" without express or implied
 #  warranty, and with no claim as to its suitability for any purpose.
 
-# Glossary
-#
-# feature      -  a normalized aspect of a build configuration
-#
-# value        -  a specific available setting for a feature
-#
-# property     -  a feature-value pair, expressed ase value
-#
-# subfeature   -  a feature which only exists in the presence of its
-#                 parent, and whose identity can be derived (in the
-#                 context of its parent) from the name of its value
-#
-# value-string - a string of the form value-subvalue1-subvalue2...
-#                -subvalueN, where value is a feature value and
-#                subvalue1...subvalueN are values of related
-#                subfeatures.
-
 import class : * ;
 
 # A feature-space is a class to facilitate testing. We want to be able
@@ -35,66 +18,17 @@ import utility ;
 
 .all-attributes =
 
-    implicit    # features whose values alone identify the
-                # feature. For example, a user is not required to
-                # write "gcc", but can simply write
-                # "gcc". Implicit feature names also don't appear in
-                # variant paths, although the values do. Thus:
-                # bin/gcc/... as opposed to bin/toolset-gcc/.... There
-                # should typically be only a few such features, to
-                # avoid possible name clashes.
-
-    executed    # the feature corresponds to the name of a module
-                # containing an execute rule, used to actually prepare
-                # the build. For example, the toolset feature would be
-                # executed.
-
-
-    composite   # features which actually correspond to groups of
-                # properties. For example, a build variant is a
-                # composite feature. When generating targets from a
-                # set of build properties, composite features are
-                # recursively expanded and /added/ to the build
-                # property set, so rules can find them if
-                # neccessary. Non-composite non-free features override
-                # components of composite features in a build property
-                # set.
-
-
-    optional    # An optional feature is allowed to have no value at
-                # all in a particular build. Normal non-free features
-                # are always given the first of their values if no
-                # value is otherwise specified.
-
-
-    symmetric   # A symmetric feature has no default value, and is
-        # therefore not automatically included in all
-        # variants. A symmetric feature, when relevant to the
-        # toolset, always generates a corresponding subvariant
-        # directory.
-
-    free
-      
+    implicit 
+    executed 
+    composite
+    optional 
+    symmetric
+    free      
     incidental  
-
-    path        # the (free) feature's value describes a path which
-        # might be given relative to the directory of the
-        # Jamfile.
-
-    dependency  # the value of the (free) feature specifies a
-        # dependency of the target.
-
-    propagated  # when used in a build request, the (free) feature is
-        # propagated to top-level targets which are
-        # dependencies of the requested build. Propagated
-        # features would be most useful for settings such as
-        # warning levels, output message style, etc., which
-        # don't affect the built products at all.
-
-
-    link-incompatible # targets with different values of this feature
-                      # cannot be linked together under any circumstances.
-
+    path  
+    dependency  
+    propagated 
+    link-incompatible
   ;
 
 .all-features = ;
diff --git a/v2/boost_build_v2.html b/v2/boost_build_v2.html
index deea44f3c..9c7852bab 100644
--- a/v2/boost_build_v2.html
+++ b/v2/boost_build_v2.html
@@ -31,7 +31,7 @@
     
      
 
     
      
-      This is preliminary version intended to document everything
+      This is a preliminary version intended to document everything
       implemeneted but not yet ready for any practical use.
     
      
     
      
@@ -66,24 +66,46 @@
 
     
      Definition
      
 
-    
      A feature is a normalized (toolset-independent) description
-    of an individual build parameter, such as whether inlining is
-    enabled.
      
+    
      A feature is a normalized (toolset-independent) aspect of a
+    build configuration, such as whether inlining is enabled.
      
 
-    
      A property is a (feature, value) pair. Each features is
-    described by a name and the set of attributes from the following
-    list:
      
+    
      A feature value is a specific available setting for a
+    feature.
      
+
+    
      A property is a (feature,value) pair, expressed as
+    <feature>value.
      
+
+    
      A subfeature is a feature which only exists in the presence
+    of its parent, and whose identity can be derived (in the context of its
+    parent) from the name of its value.
      
+
+    
      A value-string is a string of the form
+    value-subvalue1-subvalue2...-subvalueN, where value is
+    a feature value and subvalue1...subvalueN are values of related
+    subfeatures. For example, by using value-string properties
+    <toolset>gcc <toolset-version>3.0.1, can be expressed more
+    conscicely, as <toolset>gcc-3.0.1.
      
+
+    
      A set of properties is called, naturally, property set. For
+    example, <toolset>gcc <runtime-link>static.
+    Sometimes it's better to represent a property set without spaces. In that
+    case property path is used, which consists of all properties,
+    joined with slashes. To continue with example, property path
+    representation would be
+    <toolset>gcc/<runtime-link>static .
      
+
+    
      Each feature can have any of the following attributes:
      
 
     
        
       
      • 
         incidental 
 
-        
        Incidental features do not affect build products at all. Warning
-        level is one example. As a consequence, the build system doesn't try
-        to avoid confusing targets with different values of incident
-        properties.
        
+        
        Incidental features are assumed not affect build products at all.
+        Warning level is one example. As a consequence, the build system
+        doesn't try to avoid confusing targets with different values of
+        incidental properties.
        
 
-        
        Features which are not incident are assumed to affect build
+        
        Features which are not incidental are assumed to affect build
         products, therefore they are put in different directories as
         described in target paths below.
        
       
        • 
@@ -99,14 +121,14 @@
       
 
       
      • 
-        free-valued 
+        free 
 
-        
        Usually, each feature takes takes a single value from a fixed set.
-        In particular, this means that only one value can be used when
-        building a single target. When a feature is free-valued, it can have
-        several values at a time and each value can be an arbitrary string.
-        For example, it is possible to have several preprocessor symbols
-        defined simultaneously:
        
+        
        Usually, each feature takes a single value from a fixed set. In
+        particular, this means that only one value can be used when building
+        a single target. When a feature is free, it can have several values
+        at a time and each value can be an arbitrary string. For example, it
+        is possible to have several preprocessor symbols defined
+        simultaneously:
        
 
                 <define>NDEBUG=1 <define>HAS_CONFIG_H=1
 
        
@@ -125,7 +147,7 @@
       
      • 
         symmetric 
 
-        
        A symmetric feature's default value, is not automatically included
+        
        A symmetric feature's default value is not automatically included
         in build variants. Normally a feature only
         generates a subvariant directory when its value differs from the
         value specified by the build variant, leading to an assymmetric
@@ -137,7 +159,7 @@
       
      • 
         path 
 
-        
        The value of path features specifies a path. The path is treated
+        
        The value of a path feature specifies a path. The path is treated
         as relative to the directory of Jamfile where path feature is used
         and is translated appropriately by the build system when the build is
         invoked from a different directory
        
@@ -146,19 +168,19 @@
       
      • 
         implicit 
 
-        
        features whose values alone identify the feature. For example, a
-        user is not required to write "<toolset>", but can simply write
-        "gcc". Implicit feature names also don't appear in variant paths,
-        although the values do. Thus: bin/gcc/... as opposed to
-        bin/toolset-gcc/.... There should typically be only a few such
+        
        Values of implicit features alone identify the feature. For
+        example, a user is not required to write "<toolset>", but can
+        simply write "gcc". Implicit feature names also don't appear in
+        variant paths, although the values do. Thus: bin/gcc/... as opposed
+        to bin/toolset-gcc/.... There should typically be only a few such
         features, to avoid possible name clashes.
        
       
        • 
 
       
      • 
         composite 
 
-        
        features which actually correspond to groups of properties. For
-        example, a build variant is a composite feature. When generating
+        
        Composite features actually correspond to groups of properties.
+        For example, a build variant is a composite feature. When generating
         targets from a set of build properties, composite features are
         recursively expanded and /added/ to the build property set, so rules
         can find them if neccessary. Non-composite non-free features override
@@ -171,14 +193,6 @@
         
        See below.
        
       
        • 
 
-      
      • 
-        executed 
-
-        
        
-          Do we need it?
-        
        
-      
        • 
-
       
      • 
         dependency 
 
@@ -188,21 +202,28 @@
       
        • 
     
      
 
-    
      TODO: give a name and describe the property set joined with slashes. I
-    use the term "property path" somewhere below.
      
+    
      TODO: document active features..
      
 
-    
 
-    
      It is possible that build system tries to generate a target with a
-    certain set of properties but is is only possible to obtain a target with
-    somewhat different property set. It is needed to know if the actual
-    property set can be used instead of the property set that was needed. At
-    this moment we use a simple approach to answering that question. Two
-    property sets are called link-compatible when targets with those
-    property sets can be used interchangably. In turn, two property sets are
-    link compatible when there's no link-incompatible feature which has
-    different values in those property sets.
      
+    
      When the build system tries to generate a target (such as library
+    dependency) matching a given build request, it may find that an exact
+    match isn't possible — for example, the target may impose additonal
+    build requirements. We need to determine whether a buildable version of
+    that target can actually be used.
      
+
+    
      In general, there are many possible situations: a libary which is
+    dependency of a main target and should be linked into it, target which is
+    directly requested on the command line, or build executable which is used
+    in the build process itself. At this moment we use a simple approach.
      
+
+    
      Two property sets are called link-compatible when targets
+    with those property sets can be used interchangably. In turn, two
+    property sets are link compatible when there's no link-incompatible
+    feature which has different values in those property sets. Whenever
+    requested and actual properties are link-compatible, it's OK. Otherwise,
+    it's an error.
      
 
     
      Definition of property refinement
      
 
@@ -219,7 +240,7 @@
       set
      4. 
 
       
    4. If the original property set includes property with a different
-      value of non free-valued feature, that property is removed.
      5. 
+      value of non free feature, that property is removed.
     
    
 
     
    Initialization
    
@@ -252,12 +273,17 @@
 
     
    Command line
    
 
-    
    Boost.Build extends Jam's command line in two ways. First, command
-    line arguments can be used not only to specify targets to build, but also
-    to specify build variants or arbitrary build request. Second, there are
-    additional command line options.
    
+    
    The comamnd line may contain:
    
 
-    
    Command line arguments
    
+    
      
+      
    • Jam options,
      • 
+
+      
    • Boost.Build options,
      • 
+
+      
    • Command line arguments
      • 
+    
    
+
+    
    Command line arguments
    
     Command line arguments specify targets and build request using the
     following rules. 
 
@@ -361,10 +387,10 @@
 
     
    For each project, there are several attributes.
    
 
-    
    Project id is used to denote the project from other project.
-    Each project id is a hierarchical path, such as "boost/thread". When
-    project-id need to be referred from other projects there are two
-    alternatives:
    
+    
    Project id 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". There are two ways to refer to a
+    project using project-id:
    
 
     
      
       
    • Use absolute proejct-id, which starts with "/", for example
@@ -373,11 +399,8 @@
       
    • Use relative project-id, which is appended to the project-id of the
       project where it is used.
      • 
     
    
-    
    
-     
    
-     
 
-    
    Source location specifies directory where sources for the
+    
    Source location specifies the directory where sources for the
     project are located.
    
 
     
    Project requirements are requirements that apply to all the
@@ -499,11 +522,11 @@
     like list of source and requirement.
    
 
     
    It is possible to have different list of sources for different
-    toolsets, therefore it is possible to invoce main target rules several
+    toolsets, therefore it is possible to invoke main target rules several
     times for a single main target. For example:
    
 
    -    exe a.exe : a_gcc.cpp : <toolset> ;
-    exe a.exe : a.cpp ;
+    exe a : a_gcc.cpp : <toolset> ;
+    exe a : a.cpp ;
 
    
     Each call to the 'exe' rule defines a new main target
     alternative for the main target a.exe. In this case, the
@@ -513,8 +536,8 @@
 
     
    Target identifiers and references
    
 
-    
    Target identifier is used to denote a target. It is described by the
-    following grammar:
    
+    
    Target identifier is used to denote a target. It is described
+    by the following grammar:
    
 
         target-id -> project-reference local-target-name
     project-reference -> [jamfile-location] [ "@" [project-id] ]
@@ -546,7 +569,7 @@
     After that, the target given by local-target-name in the found
     project is used. 
 
-    
    Target reference is used to specify a source target, and may
+    
    Target reference is used to specify a source target, and may
     additionally specify desired properties for that target. It has this
     syntax:
    
 
    @@ -557,9 +580,9 @@
 
         exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
 
    
-    would cause the version of cmdline library, optimized to space,
+    would cause the version of cmdline library, optimized for space,
     to be linked in even if the compile executable is build with
-    speed optimization. 
+    optimization for speed. 
 
     
    Ambiguity resolution
    
 
@@ -568,7 +591,7 @@
     pathname, it is checked if there's a jamfile in the specified path. If
     there is one, it is loaded and if the specified target is declared by
     that project it is used. Otherwise, we just treat the target reference as
-    file name.
    
+    a file name.
    
 
     
    Target paths
    
 
@@ -580,17 +603,18 @@
       
  • All targets are placed under directory corresponding to the project
       where they are defined.
    • 
 
-      
  • Each non free-valued, non incident property cause an additional
-      element to be added to the target path. That element has the form
+      
  • Each non free, non incidental property cause an additional element
+      to be added to the target path. That element has the form
       <feature-name>-<feature-value> for ordinary
       features and <feature-value> for implicit ones. [Note
       about composite features].
    • 
 
-      
  • If the set of free-valued properties is different from the set of
-      free valued properties for the project to which the target belong, a
-      part of the form main_target-<name> is added to the
-      target path. Note:It would be nice to track free-valued features
-      also, but this appears to be complex and not extremely needed.
    • 
+      
  • If the set of free, non incidental properties is different from the
+      set of free, non incidental properties for the project in which the
+      main target that uses the target is defined, a part of the form
+      main_target-<name> is added to the target path.
+      Note:It would be nice to completely track free features also,
+      but this appears to be complex and not extremely needed.
    • 
     
 
     
    For example, we might have these paths:
    
@@ -603,15 +627,17 @@
     
    Build process
    
 
     
    The build works in this way. On startup, the project in the current
-    directory is read. As the result a tree of projects is constructed. After
-    that, the build request is constructed from the command line. Then, the
-    steps are:
    
+    directory is read. In turn, it may request building of other projects,
+    which will be loaded recursively. Parent projects are also loaded to
+    inherit some of their properties. As the result, a tree of projects is
+    constructed. After that, the build request is constructed from the
+    command line. Then, the steps are:
    
 
     
      
-      
    1. The project in the current dir is passed the build request. If the
-      build request does not satisfy the project's requirements, a warning is
-      issued and the build of the project is skipped. Otherwise, the process
-      is repeated recusrively for all subprojects.
      2. 
+      
    2. All of the projects to be build are passed the build request. If
+      the build request does not satisfy the project's requirements, a
+      warning is issued and the build of the project is skipped. Projects
+      mentioned in build-project rule will still be build.
      3. 
 
       
    3. 
         An attempts to make all the main targets in the project is performed.
@@ -645,7 +671,7 @@
     therefore converted to jam's dependency graph which is then build.
      
     
      
 
-    
      Last modified: Aug 5, 2002
      
+    
      Last modified: Aug 12, 2002
      
 
     
      © Copyright Vladimir Prus 2002. Permission to copy, use, modify,
     sell and distribute this document is granted provided this copyright
diff --git a/v2/build/feature.jam b/v2/build/feature.jam
index 6f3d8e2e3..577ae91e4 100644
--- a/v2/build/feature.jam
+++ b/v2/build/feature.jam
@@ -3,23 +3,6 @@
 #  all copies. This software is provided "as is" without express or implied
 #  warranty, and with no claim as to its suitability for any purpose.
 
-# Glossary
-#
-# feature      -  a normalized aspect of a build configuration
-#
-# value        -  a specific available setting for a feature
-#
-# property     -  a feature-value pair, expressed ase value
-#
-# subfeature   -  a feature which only exists in the presence of its
-#                 parent, and whose identity can be derived (in the
-#                 context of its parent) from the name of its value
-#
-# value-string - a string of the form value-subvalue1-subvalue2...
-#                -subvalueN, where value is a feature value and
-#                subvalue1...subvalueN are values of related
-#                subfeatures.
-
 import class : * ;
 
 # A feature-space is a class to facilitate testing. We want to be able
@@ -35,66 +18,17 @@ import utility ;
 
 .all-attributes =
 
-    implicit    # features whose values alone identify the
-                # feature. For example, a user is not required to
-                # write "gcc", but can simply write
-                # "gcc". Implicit feature names also don't appear in
-                # variant paths, although the values do. Thus:
-                # bin/gcc/... as opposed to bin/toolset-gcc/.... There
-                # should typically be only a few such features, to
-                # avoid possible name clashes.
-
-    executed    # the feature corresponds to the name of a module
-                # containing an execute rule, used to actually prepare
-                # the build. For example, the toolset feature would be
-                # executed.
-
-
-    composite   # features which actually correspond to groups of
-                # properties. For example, a build variant is a
-                # composite feature. When generating targets from a
-                # set of build properties, composite features are
-                # recursively expanded and /added/ to the build
-                # property set, so rules can find them if
-                # neccessary. Non-composite non-free features override
-                # components of composite features in a build property
-                # set.
-
-
-    optional    # An optional feature is allowed to have no value at
-                # all in a particular build. Normal non-free features
-                # are always given the first of their values if no
-                # value is otherwise specified.
-
-
-    symmetric   # A symmetric feature has no default value, and is
-        # therefore not automatically included in all
-        # variants. A symmetric feature, when relevant to the
-        # toolset, always generates a corresponding subvariant
-        # directory.
-
-    free
-      
+    implicit 
+    executed 
+    composite
+    optional 
+    symmetric
+    free      
     incidental  
-
-    path        # the (free) feature's value describes a path which
-        # might be given relative to the directory of the
-        # Jamfile.
-
-    dependency  # the value of the (free) feature specifies a
-        # dependency of the target.
-
-    propagated  # when used in a build request, the (free) feature is
-        # propagated to top-level targets which are
-        # dependencies of the requested build. Propagated
-        # features would be most useful for settings such as
-        # warning levels, output message style, etc., which
-        # don't affect the built products at all.
-
-
-    link-incompatible # targets with different values of this feature
-                      # cannot be linked together under any circumstances.
-
+    path  
+    dependency  
+    propagated 
+    link-incompatible
   ;
 
 .all-features = ;