[Boost-commit] svn:boost r45067 - trunk/tools/build/v2/doc/src

From: jurko.gospodnetic_at_[hidden]
Date: 2008-05-03 09:17:38

Author: jurko
Date: 2008-05-03 09:17:37 EDT (Sat, 03 May 2008)
New Revision: 45067
URL: http://svn.boost.org/trac/boost/changeset/45067

Log:
Updated the documentation for Boost.Build's 'path' & 'propagated' feature attributes. Minor stylistic changes.
Text files modified: 
   trunk/tools/build/v2/doc/src/extending.xml |   133 ++++++++++++++++++++------------------- 
   1 files changed, 67 insertions(+), 66 deletions(-)

Modified: trunk/tools/build/v2/doc/src/extending.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/extending.xml	(original)
+++ trunk/tools/build/v2/doc/src/extending.xml	2008-05-03 09:17:37 EDT (Sat, 03 May 2008)
@@ -130,14 +130,14 @@
         automatically generate necessary build actions only because you
         specify the desired type (using the different main target rules), and
         because Boost.Build can guess the type of sources from their
-        extensions.        
+        extensions.
       </para>
 
       <para>The first two parameters for the <code>type.register</code> rule
         are the name of new type and the list of extensions associated with
         it. A file with an extension from the list will have the given target
         type. In the case where a target of the declared type is generated
-        from other sources, the first specified extension will be used. 
+        from other sources, the first specified extension will be used.
       </para>
 
     <para>Sometimes you want to change the suffix used for generated targets
@@ -149,7 +149,7 @@
 </programlisting>
     </para>
 
-    <para>A new target type can be inherited from an existing one. 
+    <para>A new target type can be inherited from an existing one.
 <programlisting>
 type.register PLUGIN : : SHARED_LIB ;
 </programlisting>
@@ -174,10 +174,10 @@
       <section id="bbv2.extending.scanners">
         <title>Scanners</title>
         <para>
-          Sometimes, a file can refer to other files via some include
-          mechanism. To make Boost.Build track dependencies to the included
-          files, you need to provide a scanner. The primary limitation is that
-          only one scanner can be assigned to a target type.
+          Sometimes, a file can refer to other files via some include system. To
+          make Boost.Build track dependencies between included files, you need
+          to provide a scanner. The primary limitation is that only one scanner
+          can be assigned to a target type.
         </para>
 
         <para>First, we need to declare a new class for the scanner:
@@ -189,7 +189,7 @@
         return "//###include[ ]*\"([^\"]*)\"" ;
     }
 }
-</programlisting>         
+</programlisting>
           All the complex logic is in the <code>common-scanner</code>
           class, and you only need to override the method that returns
           the regular expression to be used for scanning. The
@@ -221,7 +221,7 @@
       </section>
 
   </section>
-  
+
   <section id="bbv2.extending.tools">
     <title>Tools and generators</title>
       <para>
@@ -319,7 +319,7 @@
 <!-- What is the point of this __init__ function?? -->
 }
 
-generators.register 
+generators.register
   [ new custom-generator verbatim.inline-file : VERBATIM : CPP ] ;
 </programlisting>
         This generator will work exactly like the
@@ -363,13 +363,13 @@
 generators.register [ new itrace-generator nm.itrace : EXE : ITRACE ] ;
 </programlisting>
         The <code>generated-targets</code> method will be called with a single
-        source target of type <literal>EXE</literal>. The call to 
+        source target of type <literal>EXE</literal>. The call to
         <code>virtual-target.traverse</code> will return all targets the
         executable depends on, and we further find files that are not
         produced from anything. <!-- What does "not produced from anything" mean? -->
         The found targets are added to the sources.
       </para>
-      
+
       <para>The <code>run</code> method can be overriden to completely
         customize the way the generator works. In particular, the conversion of
         sources to the desired types can be completely customized. Here's
@@ -382,7 +382,7 @@
         done:
 <programlisting>
 rule run ( project name ? : property-set : sources * )
-{       
+{
     local python ;
     for local s in $(sources)
     {
@@ -400,26 +400,26 @@
             libs += $(s) ;
         }
     }
-    
+
     local new-sources ;
     for local s in $(sources)
     {
-        if [ type.is-derived [ $(s).type ] CPP ] 
+        if [ type.is-derived [ $(s).type ] CPP ]
         {
             local name = [ $(s).name ] ;    # get the target's basename
-            if $(name) = [ $(python).name ] 
+            if $(name) = [ $(python).name ]
             {
                 name = $(name)_ext ;        # rename the target
-            }                                
+            }
             new-sources += [ generators.construct $(project) $(name) :
               PYTHON_EXTENSION : $(property-set) : $(s) $(libs) ] ;
         }
     }
-        
-    result = [ construct-result $(python) $(new-sources) : $(project) $(name) 
-                 : $(property-set) ] ;        
-}    
-</programlisting>        
+
+    result = [ construct-result $(python) $(new-sources) : $(project) $(name)
+                 : $(property-set) ] ;
+}
+</programlisting>
         <!-- Why are we doing this with a generator??? It seems
              insane.  We could just use a nice front-end rule that
              calls some normal target-creation rules. No? -->
@@ -428,16 +428,16 @@
         sources. For each C++ source we create a separate Python extension by
         calling <code>generators.construct</code> and passing the C++ source
         and the libraries. At this point, we also change the extension's name,
-        if necessary.        
+        if necessary.
       </para>
 
- 
+
     </section>
 
     <section id="bbv2.extending.features">
       <title>Features</title>
       <para>
-        Often, we need to control the options passed the invoked tools. This 
+        Often, we need to control the options passed the invoked tools. This
         is done with features. Consider an example:
 <programlisting>
 # Declare a new free feature
@@ -492,9 +492,9 @@
       linkend="bbv2.faq.external"/> for an example of very smart usage of that
       feature).  Of course one should always strive to use portable
       features, but these are still be provided as a backdoor just to make
-      sure Boost.Build does not take away any control from the user. 
+      sure Boost.Build does not take away any control from the user.
     </para>
-   
+
     <para>
       Using portable features is a good idea because:
       <itemizedlist>
@@ -508,7 +508,7 @@
             <!-- It's a computer program.  It doesn't "care" about options -->
           </para>
         </listitem>
-        
+
         <listitem>
           <para>Unlike with “raw” features, you don't need to use
           specific command-line flags in your Jamfile, and it will be
@@ -517,7 +517,7 @@
         </listitem>
       </itemizedlist>
     </para>
-           
+
       <bridgehead>Steps for adding a feauture</bridgehead>
       <!-- This section is redundant with the previous one -->
       <para>Adding a feature requires three steps:
@@ -529,27 +529,28 @@
               attributes</link>:
 
               <itemizedlist>
-                <listitem><para>if a feature has several values<!-- what do you mean by that?? --> and
-                    significantly affects the build, make it “propagated,” so that the
-                    whole project is built with the same value by
-                    default</para></listitem> 
-
-                <listitem><para>if a feature does not have a fixed
-                list of values, it must be “free.”  For example, the
-                <code>include</code> feature is a free
-                feature.</para></listitem>
-
-                <listitem><para>if a feature is used to refer to a
-                path relative to the Jamfile, it must be a “path”
-                feature.  <code>include</code> is also a path
-                feature.</para></listitem>
-        
+                <listitem><para>if you want a feature value set for one target
+                to automaticaly propagate to its dependant targets then make it
+                “propagated”. <!-- Examples needed. --></para></listitem>
+
+                <listitem><para>if a feature does not have a fixed list of
+                values, it must be “free.”  For example, the <code>include
+                </code> feature is a free feature.</para></listitem>
+
+                <listitem><para>if a feature is used to refer to a path relative
+                to the Jamfile, it must be a “path” feature. Such features will
+                also get their values automatically converted to Boost Build's
+                internal path representation. For example, <code>include</code>
+                is a path feature.</para></listitem>
+
                 <listitem><para>if feature is used to refer to some target, it
-                must be a “dependency” feature. <!-- for example? --></para></listitem>
+                must be a “dependency” feature. <!-- for example? --></para>
+
+                <!-- Any other feature attributes? -->
+                </listitem>
               </itemizedlist>
               </para>
           </listitem>
-              
 
           <listitem><para>Representing the feature value in a
           target-specific variable. Build actions are command
@@ -568,13 +569,13 @@
 
       <para>Here's another example.
         Let's see how we can make a feature that refers to a target. For example,
-        when linking dynamic libraries on windows, one sometimes needs to specify
-        "DEF file", telling what functions should be exported. It would be nice to
-        use this file like this:
+        when linking dynamic libraries on Windows, one sometimes needs to
+        specify a "DEF file", telling what functions should be exported. It
+        would be nice to use this file like this:
 <programlisting>
         lib a : a.cpp : &lt;def-file&gt;a.def ;
 </programlisting>
-<!-- Why would that be nice?  It seems to me that having a.def in the sources is the obvious and much nicer thing to do: 
+<!-- Why would that be nice?  It seems to me that having a.def in the sources is the obvious and much nicer thing to do:
 
         lib a : a.cpp a.def ;
 -->
@@ -603,9 +604,9 @@
 </programlisting>
             <!-- And that line does... what? -->
             </para></listitem>
-            
+
         <listitem><para>Since the DEF_FILE variable is not used by the
-msvc.link action, 
+msvc.link action,
 <!-- It's not?  You just told us that MSVC "cares" about DEF files. I
      presume that means that it uses them in some appropriate way? -->
 we need to modify it to be:
@@ -617,8 +618,8 @@
 }
 </programlisting>
             </para>
-          
-          
+
+
           <para> Note the <code>bind DEF_FILE</code> part. It tells
           bjam to translate the internal target name in
           <varname>DEF_FILE</varname> to a corresponding filename in
@@ -640,11 +641,11 @@
     DEPENDS $(&lt;) : [ on $(&lt;) return $(DEF_FILE) ] ;
 }
 </programlisting>
-<!-- You *must* explain the part in [...] above.  It's completely opaque to the casual reader -->
+<!-- You *must* explain the part in [...] above. It's completely opaque to the casual reader -->
 
             This is needed to accomodate some bug in bjam, which hopefully
             will be fixed one day.
-            <!-- This is *NOT* a bug!!  Anyway,  BBv2 shouild handle this automatically.  Why doesn't it? -->
+            <!-- This is *NOT* a bug!!  Anyway, BBv2 shouild handle this automatically. Why doesn't it? -->
 </para></listitem>
 
       </orderedlist>
@@ -652,7 +653,7 @@
       <bridgehead>Variants and composite features.</bridgehead>
 
       <para>Sometimes you want to create a shortcut for some set of
-        features. For example, <code>release</code> is a value of 
+        features. For example, <code>release</code> is a value of
         <code>&lt;variant&gt;</code> and is a shortcut for a set of features.
       </para>
 
@@ -671,7 +672,7 @@
       </para>
 
       <para>You are not restricted to using the <code>variant</code> feature
-      only. 
+      only.
       <!-- What do you mean by that?  How is defining a new feature related to what came before? -->
       Here's example that defines a brand new feature:
 <programlisting>
@@ -683,11 +684,11 @@
      above is at best confusing and unexplained -->
         This will allow you to specify the value of feature
         <code>parallelism</code>, which will expand to link to the necessary
-        library. 
+        library.
       </para>
-     
+
   </section>
-  
+
   <section id="bbv2.extending.rules">
     <title>Main target rules</title>
     <para>
@@ -703,7 +704,7 @@
       rule is already defined for you! When you define a new type, Boost.Build
       automatically defines a corresponding rule. The name of the rule is
       obtained from the name of the type, by downcasing all letters and
-      replacing underscores with dashes. 
+      replacing underscores with dashes.
       <!-- This strikes me as needless complexity, and confusing.  Why
            do we have the uppercase-underscore convention for target
            types?  If we just dropped that, the rule names could be
@@ -721,7 +722,7 @@
       and import that module, you'll be able to use the rule "obfuscated-cpp"
       in Jamfiles, which will convert source to the OBFUSCATED_CPP type.
     </para>
-    
+
     <para>
       The second way is to write a wrapper rule that calls any of the existing
       rules. For example, suppose you have only one library per directory and
@@ -814,7 +815,7 @@
         <listitem><para>Check for multiple initialization. A user can try to
             initialize the module several times. You need to check for this
             and decide what to do. Typically, unless you support several
-            versions of a tool, duplicate initialization is a user error. 
+            versions of a tool, duplicate initialization is a user error.
             <!-- Why should that be typical? -->
             If the
             tool's version can be specified during initialization, make sure the
@@ -852,7 +853,7 @@
     </para>
 
 
-      
+
 
   </section>
 
@@ -860,7 +861,7 @@
 
 <!--
      Local Variables:
-     sgml-indent-data: t     
+     sgml-indent-data: t
      sgml-parent-document: ("userman.xml" "chapter")
      sgml-set-face: t
      End: