Commit my restructuring of user manual.

[SVN r23390]

v2/doc/src/architecture.xml

@@ -7,13 +7,135 @@
 
   <sidebar>
     <para>This document is work-in progress. Don't expect much from it
-    yet.</para>
+      yet.</para>
   </sidebar>
+  
+  <section id="bbv2.arch.overview">
+    <title>Overview</title>
 
+    <para>The Boost.Build code is structured in four different components:
+    "kernel", "util", "build" and "tools". The first two are relatively
+    uninteresting, so we'll focus on the remaining pair. The "build" component
+    provides classes necessary to declare targets, determine which properties
+    should be used for their building, and for creating the dependency
+    graph. The "tools" component provides user-visible functionality. It
+    mostly allows to declare specific kind of main targets, and declare
+    avaiable tools, which are then used when creating the dependency graph.
+    </para>
+    
+  </section>
+
+  <section id="bbv2.arch.build">
+    <title>The build layer</title>
+
+    <para>The build layer has just four main parts -- abstract targets,
+      virtual targets, generators and properties. The abstract targets,
+      represented by the "abstract-target" class, correspond to main targets
+      -- which, as you recall, can produce different files depending on
+      properties. Virtual targets, represented by the 'virtual-target' class
+      correspond to real files. The abstract-target class has a method
+      'generate', which is given a set of properties and produces virtual
+      targets for those properties.       
+    </para>
+
+    <para>There are several classes derived from "abstract-target". The
+      "main-target" class represents top-level main target, the "project-target"
+      acts like container for all main targets, and "basic-target" class is a
+      base class for all further target types.
+    </para>
+
+    <para>Since each main target can have several alternatives, all top-level
+      target objects are just containers, referring to "real" main target
+      classes. The type is that container is "main-target". For example, given:
+<programlisting>
+alias a ;
+lib a : a.cpp : &lt;toolset&gt;gcc ;
+</programlisting>
+      we would have one-top level instance of "main-target-class", which will
+      contain one instance of "alias-target-class" and one instance of
+      "lib-target-class". The "generate" method of "main-target" decides
+      which of the alternative should be used, and call "generate" on the
+      corresponding instance.
+</para>
+
+    <para>Each alternative is a instance of a class derived from
+    "basic-target". The "basic-target.generate" does several things that are
+    always should be done:
+      <itemizedlist>
+        <listitem>
+          <para>Determines what properties should be used for building the
+          target. This includes looking at requested properties, requirements,
+          and usage requirements of all sources.</para>
+        </listitem>
+        <listitem>
+          <para>Builds all sources</para>
+        </listitem>
+        <listitem>
+          <para>Computes the usage requirements which should be passes back.</para>
+        </listitem>
+      </itemizedlist>
+      For the real work of constructing virtual target, a new method
+      "construct" is called.
+    </para>
+
+    <para>The "construct" method can be implemented in any way by classes
+      derived from "basic-target", but one specific derived class plays the
+      central role -- "typed-target". That class holds the desired type of file
+      to be produces, and calls the generators modules to do the job.
+    </para>
+
+    <para>Generators are Boost.Build abstractions for a tool. For example, one
+      can register a generator which converts target of type CPP into target of
+      type OBJ. When run with on a virtual target with CPP type, the generator
+      will construct the virtual target of type OBJ. The "generators" module
+      implements an algorithm, which given a list of sources, the desired type
+      and a list of properties, find all the generators which can perform the conversion.
+    </para>
+
+    <para>The virtual targets which are produces by the main targets form a
+      graph. Targets which are produces from other ones refer to an instance of
+      "action" class, which in turn refers to action's sources, which can
+      further refer to actions. The sources, which are not produces from
+      anything, don't refer to any actions.
+    </para>
+
+    <para>When all virtual targets are produced, they are "actualized". This
+    means that the real file names are computed, and the commands that should
+    be run are generated. This is done by "virtual-target.actualize" and
+    "action.actualize" methods. The first is conceptually simple, while the
+    second need additional explanation. The commands in bjam are generated in
+    two-stage process. First, a rule with the appropriate name (for example
+    "gcc.compile") is called and is given the names of targets. The rule sets
+    some variables, like "OPTIONS". After that, the command string is taken,
+    and variable are substitutes, so use of OPTIONS inside the command string
+    become the real compile options. 
+    </para>
+
+    <para>Boost.Build added a third stage to simplify things. It's now
+    possible to automatically convert properties to appropriate assignments to
+    variables. For example, &lt;debug-symbols&gt;on would add "-g" to the
+    OPTIONS variable, without requiring to manually add this logic to
+    gcc.compile. This functionality is part of the "toolset" module.
+    </para>
+    
+    <para>When target paths are computed and the commands are set, Boost.Build
+    just gives control to bjam, which controls the execution of
+    commands.</para>
+        
+  </section>
+
+  <section id="bbv2.arch.tools">
+    <title>The tools layer</title>
+
+    <para>Write me!</para>
+
+  </section>
+  
     <section id="bbv2.arch.targets">
       <title>Targets</title>
 
-  <para>There are two user-visible kinds of targets in Boost.Build.
+  <para>NOTE: THIS SECTION IS NOT EXPECTED TO BE READ!
+        There are two user-visible kinds of targets in Boost.Build.
   First are "abstract" &#x2014; they correspond to things declared
   by user, for example, projects and executable files. The primary
   thing about abstract target is that it's possible to request them
@@ -432,3 +554,11 @@ debug/main-target-a
     </section>
   </appendix>
 
+<!--
+     Local Variables:
+     mode: xml
+     sgml-indent-data: t     
+     sgml-parent-document: ("userman.xml" "chapter")
+     sgml-set-face: t
+     End:
+-->

v2/doc/src/extending.xml

@@ -105,24 +105,86 @@ and linked it.
   "../../example/customization">example/customization</ulink>
   directory.</para>
 
-    </section>
+  </section>
-    <section id="bbv2.extending.targets">
+  <section id="bbv2.extending.targets">
-      <title>Target types</title>
+    <title>Target types</title>
+    <para/>
+  </section>
+  
+  <section id="bbv2.extending.tools">
+    <title>Tools</title>
       <para/>
-    </section>
+  </section>
+  
+  <section id="bbv2.extending.rules">
+    <title>Main target rules</title>
+    <para>
+      The main target rule is what creates a top-level target, for example "exe" or
+      "lib". It's quite likely that's you'll want to declare your own and
+      there are as much as three way to do that.
+    </para>
+    
+    <para>The first is the simplest, but is sufficient in a number of
+      case. Just write a wrapper rule, which will redirect to any of existing
+      rules. For example, you have only one library per directory and want all
+      cpp files in the directory to be compiled. You can achieve this effect
+      with:
+<programlisting>
+lib codegen : [ glob *.cpp ] ;
+</programlisting>
+      but what if you want to make it even simple. Then, you add the following
+      definition to the project-root.jam file:
+<programlisting>
+rule glib ( name : extra-sources * : requirements * )
+{
+    lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
+}
+</programlisting>
+which would allow to reduce Jamfile to
+<programlisting>
+glib codegen ;
+</programlisting>
+    </para>
 
-    <section id="bbv2.extending.tools">
+    <para>The second approach is suitable when your target rule should just
-      <title>Tools</title>
+      produce a target of specific type. Then, when declaring a type you
-      <para/>
+      should tell Boost.Build that a main target rule should be created.
-    </section>
+      For example, if you create a module "obfuscate.jam" containing:
 
-    <section id="bbv2.extending.rules">
+<programlisting>
-      <title>Main target rules</title>
+import type ;
-      <para/>
+type.register OBFUSCATED_CPP  : ocpp : : main ;
-    </section>
+
+import generators ;
+generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;
+</programlisting>
+      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 remaining method is to declared your own main target class. The
+      simplest example of this can be found in "build/alias.jam" file. The
+      current V2 uses this method when transformations are relatively
+      complex. However, we might deprecate this approach. If you find that you
+      need to use it (that is, the first two approaches are not sufficient),
+      please let us know by posting to the mailing list.
+    </para>
+    
+
+  </section>
 
     <section id="bbv2.extending.scanners">
       <title>Scanners</title>
       <para/>
     </section>
   </appendix>
+
+<!--
+     Local Variables:
+     mode: xml
+     sgml-indent-data: t     
+     sgml-parent-document: ("userman.xml" "chapter")
+     sgml-set-face: t
+     End:
+-->

v2/doc/src/reference.xml

@@ -484,7 +484,7 @@ Boost.Build comes with default versions of those files,
     symbol is either a value of an implicit feature, or target to
     be built. It is taken to be value of a feature if appropriate
     feature exists. Otherwise, it is considered a <link linkend=
-    "bbv2.advanced.ids">target id</link>. Special target name "clean"
+    "bbv2.reference.ids">target id</link>. Special target name "clean"
     has the same effect as "--clean" option.
       </simpara>
     </listitem>
@@ -631,6 +631,118 @@ linked binaries would be created.
     <section id="bbv2.reference.buildreq">
       <title>Build request</title>
 
+    <section id="bbv2.reference.ids">
+      <title>Target identifiers and references</title>
+
+      <para><emphasis>Target identifier</emphasis> is used to denote a
+      target. The syntax is:</para>
+
+<programlisting>
+target-id -&gt; (project-id | target-name | file-name )
+              | (project-id | directory-name) "//" target-name   
+project-id -&gt; path
+target-name -&gt; path
+file-name -&gt; path
+directory-name -&gt; path                  
+</programlisting>
+
+      <para>
+This grammar allows some elements to be recognized as either
+
+  <itemizedlist>
+    <listitem>
+      <simpara>
+        project id (at this point, all project ids start with slash).
+      </simpara>
+    </listitem>
+
+    <listitem>
+      <simpara>
+        name of target declared in current Jamfile (note that target
+        names may include slash).
+      </simpara>
+    </listitem>
+
+    <listitem>
+      <simpara>
+        a regular file, denoted by absolute name or name relative to
+        project's sources location.
+      </simpara>
+    </listitem>
+  </itemizedlist>
+
+  To determine the real meaning a check is made if project-id
+  by the specified name exists, and then if main target of that
+  name exists. For example, valid target ids might be:
+
+<screen>
+a                                    -- target in current project
+lib/b.cpp                            -- regular file
+/boost/thread                        -- project "/boost/thread"
+/home/ghost/build/lr_library//parser -- target in specific project
+</screen>
+
+    </para>
+
+  <para><emphasis role="bold">Rationale:</emphasis>Target is separated from project by special
+  separator (not just slash), because:</para>
+
+  <itemizedlist>
+    <listitem>
+      <simpara>
+        It emphasises that projects and targets are different things.
+      </simpara>
+    </listitem>
+
+    <listitem>
+      <simpara>
+        It allows to have main target names with slashes. 
+
+    <!-- The motivation for which is:
+
+    So, to summarize:
+
+    1. The project which extract tarfile may extract all possible kinds
+       of targets, and it's reasonable to use them directly from other
+       project.
+
+    2. The rule for unpacking tar is inplemented in terms of
+       "patch-file", for maintainability, and therefore, must use main
+       target name which contains slashes?
+
+    3. Using sub-Jamfile in "foo" to declare extracted file "foo/b" is
+       not an option, because you should not change existing tree 
+
+    That makes good rationale for why main target must contain names.
+    -->
+      </simpara>
+    </listitem>
+  </itemizedlist>
+
+  <para id="bbv2.reference.targets.references">
+    <emphasis>Target reference</emphasis> is used to
+  specify a source target, and may additionally specify desired
+  properties for that target. It has this syntax:</para>
+
+<programlisting>
+target-reference -&gt; target-id [ "/" requested-properties ]
+requested-properties -&gt; property-path
+</programlisting>
+
+      <para>
+For example,
+
+<programlisting>
+exe compiler : compiler.cpp libs/cmdline/&lt;optimization&gt;space ;
+</programlisting>
+
+would cause the version of <literal>cmdline</literal> library,
+optimized for space, to be linked in even if the
+<literal>compiler</literal> executable is build with optimization for
+speed.
+      </para>
+    </section>
+
       <para/>
     </section>