|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r65790 - in trunk/tools/build/v2/doc: . src
From: ghost_at_[hidden]
Date: 2010-10-06 16:18:11
Author: vladimir_prus
Date: 2010-10-06 16:18:09 EDT (Wed, 06 Oct 2010)
New Revision: 65790
URL: http://svn.boost.org/trac/boost/changeset/65790
Log:
Kill some sections in jam docs. Expand list of options in Boost.Build docs.
Text files modified:
trunk/tools/build/v2/doc/bjam.qbk | 192 ----------------------------------------
trunk/tools/build/v2/doc/src/overview.xml | 72 +++++++++++---
trunk/tools/build/v2/doc/src/standalone.xml | 2
3 files changed, 58 insertions(+), 208 deletions(-)
Modified: trunk/tools/build/v2/doc/bjam.qbk
==============================================================================
--- trunk/tools/build/v2/doc/bjam.qbk (original)
+++ trunk/tools/build/v2/doc/bjam.qbk 2010-10-06 16:18:09 EDT (Wed, 06 Oct 2010)
@@ -44,33 +44,6 @@
[template lines[items]'''<simplelist type='vert' columns='1'>'''[items]'''</simplelist>''']
[template line[text]'''<member>'''[text]'''</member>''']
-[section:intro Introduction]
-
-[warning Most probably, you are looking for [@http://boost.org/boost-build2/doc/html/index.html Boost.Build
-manual]. This document is not meant to be read standalone and will only
-confuse you. Boost.Build manual refers to specific sections when necessary.]
-
-Boost.Jam (BJam) is the low-level build engine tool for
-[@http://boost.org/boost-build2 Boost.Build]. Historically, Boost.Jam is based
-on on FTJam and on :Perforce_Jam: but has grown a number of significant
-features and is now developed independently, with no merge back expected to
-happen, and little use outside Boost.Build.
-
-This is version :version: of BJam and is based on version 2.4 of Jam/MR:
-
-[pre
-/+\
-+\ Copyright 1993-2002 Christopher Seiwald and Perforce Software, Inc.
-\+/
-This is Release 2.4 of Jam/MR, a make-like program.
-License is hereby granted to use this software and distribute it
-freely, as long as this copyright notice is retained and modifications
-are clearly marked.
-ALL WARRANTIES ARE HEREBY DISCLAIMED.
-]
-
-[endsect]
-
[section:building Building BJam]
Installing =BJam= after building it is simply a matter of copying the
@@ -406,171 +379,6 @@
[endsect]
-[section:usage Using BJam]
-
-[warning Most probably, you are looking for
-[@http://boost.org/boost-build2/doc/html/index.html Boost.Build
-manual] or [@http://www.boost.org/boost-build2/doc/html/bbv2/overview/invocation.html Boost.Build
-command-line syntax]. This section documents only low-level options used by
-the Boost.Jam build engine, and does not mention any high-level syntax of Boost.Build]
-
-
-If /target/ is provided on the command line, =bjam= builds /target/; otherwise =bjam= builds the target =all=.
-
-[pre
-bjam ( -option \[value\] | target ) *
-]
-
-[section:options Options]
-
-Options are either singular or have an accompanying value. When a value is allowed, or required, it can be either given as an argument following the option argument, or it can be given immediately after the option as part of the option argument. The allowed options are:
-
-[variablelist
-
- [ [[literal -a]]
- [Build all targets anyway, even if they are up-to-date.] ]
-
- [ [[literal -d /n/]]
- [
- Enable cummulative debugging levels from 1 to n. Values are:
-
- [orderedlist
- [li Show the actions taken for building targets, as they are executed (the default).]
- [li Show "quiet" actions and display all action text, as they are executed.]
- [li Show dependency analysis, and target/source timestamps/paths.]
- [li Show arguments and timming of shell invocations.]
- [li Show rule invocations and variable expansions.]
- [li Show directory/header file/archive scans, and attempts at binding to targets.]
- [li Show variable settings.]
- [li Show variable fetches, variable expansions, and evaluation of '"if"' expressions.]
- [li Show variable manipulation, scanner tokens, and memory usage.]
- [li Show profile information for rules, both timing and memory.]
- [li Show parsing progress of Jamfiles.]
- [li Show graph of target dependencies.]
- [li Show change target status (fate).]
- ]
- ] ]
-
- [ [[literal -d +/n/]]
- [Enable debugging level /n/.] ]
-
- [ [[literal -d 0]]
- [Turn off all debugging levels. Only errors are reported.] ]
-
- [ [[literal -f /Jambase/]] [Read /Jambase/ instead of using the built-in
- Jambase. Only one -f flag is permitted, but the /Jambase/ may explicitly
- include other files. A /Jambase/ name of "-" is allowed, in which case
- console input is read until it is closed, at which point the input is
- treated as the Jambase.] ]
-
- [ [[literal -j /n/]]
- [Run up to /n/ shell commands concurrently (UNIX and NT only). The default is 1.] ]
-
- [ [[literal -l /n/]]
- [Limit actions to running for /n/ number of seconds, after which they are stopped. Note: Windows only.] ]
-
- [ [[literal -n]]
- [Don't actually execute the updating actions, but do everything else. This changes the debug level default to =-d 2=.] ]
-
- [ [[literal -o /file/]]
- [Write the updating actions to the specified file instead of running them.] ]
-
- [ [[literal -q]]
- [Quit quickly (as if an interrupt was received) as soon as *any* target fails.] ]
-
- [ [[literal -s /var/=/value/]]
- [Set the variable /var/ to /value/, overriding both internal variables and variables imported from the environment.] ]
-
- [ [[literal -t /target/]]
- [Rebuild /target/ and everything that depends on it, even if it is up-to-date.] ]
-
- [ [[literal -- /value/]]
- [The option and /value/ is ignored, but is available from the =$(ARGV)= variable. ]]
-
- [ [[literal -v]]
- [Print the version of =bjam= and exit.] ]
-]
-
-[section Command-line and Environment Variable Quoting]
-
-Classic Jam had an odd behavior with respect to command-line variable (=-s...=) and environment variable settings which made it impossible to define an arbitrary variable with spaces in the value. Boost Jam remedies that by treating all such settings as a single string if they are surrounded by double-quotes. Uses of this feature can look interesting, since shells require quotes to keep characters separated by whitespace from being treated as separate arguments:
-
-[pre
-jam -sMSVCNT="\\"\\"C:\\Program Files\\Microsoft Visual C++\\VC98\\"\\"" ...
-]
-
-The outer quote is for the shell. The middle quote is for Jam, to tell it to take everything within those quotes literally, and the inner quotes are for the shell again when paths are passed as arguments to build actions. Under NT, it looks a lot more sane to use environment variables before invoking jam when you have to do this sort of quoting:
-
-[pre
-set MSVCNT=""C:\\Program Files\\Microsoft Visual C++\\VC98\\""
-]
-
-[endsect]
-
-[endsect]
-
-[section:operation Operation]
-
-BJam has four phases of operation: start-up, parsing, binding, and updating.
-
-[section:startup Start-up]
-
-Upon start-up, =bjam= imports environment variable settings into =bjam= variables. Environment variables are split at blanks with each word becoming an element in the variable's list of values. Environment variables whose names end in =PATH= are split at =$(SPLITPATH)= characters (e.g., =":"= for Unix).
-
-To set a variable's value on the command line, overriding the variable's environment value, use the =-s= option. To see variable assignments made during bjam's execution, use the =-d+7= option.
-
-The Boost.Build v2 initialization behavior has been implemented. This behavior only applies when the executable being invoked is called "=bjam=" or, for backward-compatibility, when the =BOOST_ROOT= variable is set.
-
-# We attempt to load "=boost-build.jam=" by searching from the current invocation directory up to the root of the file system. This file is expected to invoke the =boost-build= rule to indicate where the Boost.Build system files are, and to load them.
-
-# If =boost-build.jam= is not found we error and exit, giving brief instructions on possible errors. As a backward-compatibility measure for older versions of Boost.Build, when the =BOOST_ROOT= variable is set, we first search for =boost-build.jam= in =$(BOOST_ROOT)/tools/build= and =$(BOOST_BUILD_PATH)=. If found, it is loaded and initialization is complete.
-
-# The =boost-build= rule adds its (optional) argument to the front of =BOOST_BUILD_PATH=, and attempts to load =bootstrap.jam= from those directories. If a relative path is specified as an argument, it is treated as though it was relative to the =boost-build.jam= file.
-
-# If the =bootstrap.jam= file was not found, we print a likely error message and exit.
-
-[endsect]
-
-[section:parsing Parsing]
-
-In the parsing phase, =bjam= reads and parses the =Jambase= file, by default the built-in one. It is written in the [link jam.language jam language]. The last action of the =Jambase= is to read (via the "include" rule) a user-provided file called "=Jamfile=".
-
-Collectively, the purpose of the =Jambase= and the =Jamfile= is to name build targets and source files, construct the dependency graph among them, and associate build actions with targets. The =Jambase= defines boilerplate rules and variable assignments, and the =Jamfile= uses these to specify the actual relationship among the target and source files.
-
-[endsect]
-
-[section:binding Binding]
-
-After parsing, =bjam= recursively descends the dependency graph and binds every file target with a location in the filesystem. If =bjam= detects a circular dependency in the graph, it issues a warning.
-
-File target names are given as absolute or relative path names in the filesystem. If the path name is absolute, it is bound as is. If the path name is relative, it is normally bound as is, and thus relative to the current directory. This can be modified by the settings of the =$(SEARCH)= and =$(LOCATE)= variables, which enable jam to find and build targets spread across a directory tree. See [link jam.language.variables.builtins.search SEARCH and LOCATE Variables] below.
-
-[section:fate Update Determination]
-
-After binding each target, =bjam= determines whether the target needs updating, and if so marks the target for the updating phase. A target is normally so marked if it is missing, it is older than any of its sources, or any of its sources are marked for updating. This behavior can be modified by the application of special built-in rules, =ALWAYS=, =LEAVES=, =NOCARE=, =NOTFILE=, =NOUPDATE=, and =TEMPORARY=. See [link jam.language.rules.builtins.modifying_binding Modifying Binding] below.
-
-[endsect]
-
-[section:headerscan Header File Scanning]
-
-During the binding phase, =bjam= also performs header file scanning, where it looks inside source files for the implicit dependencies on other files caused by C's #include syntax. This is controlled by the special variables $(HDRSCAN) and $(HDRRULE). The result of the scan is formed into a rule invocation, with the scanned file as the target and the found included file names as the sources. Note that this is the only case where rules are invoked outside the parsing phase. See [link jam.language.variables.builtins.hdrscan HDRSCAN and HDRRULE Variables] below.
-
-[endsect]
-
-[endsect]
-
-[section:updating Updating]
-
-After binding, =bjam= again recursively descends the dependency graph, this time executing the update actions for each target marked for update during the binding phase. If a target's updating actions fail, then all other targets which depend on that target are skipped.
-
-The =-j= flag instructs =bjam= to build more than one target at a time. If there are multiple actions on a single target, they are run sequentially.
-
-[endsect]
-
-[endsect]
-
-[endsect]
-
[section:language Language]
=BJam= has an interpreted, procedural language. Statements in =bjam= are rule (procedure) definitions, rule invocations, flow-of-control structures, variable assignments, and sundry language support.
Modified: trunk/tools/build/v2/doc/src/overview.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/overview.xml (original)
+++ trunk/tools/build/v2/doc/src/overview.xml 2010-10-06 16:18:09 EDT (Wed, 06 Oct 2010)
@@ -711,20 +711,6 @@
</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
@@ -771,7 +757,63 @@
<literal>user-config.jam</literal> configuration files.
</para>
</listitem>
- </varlistentry>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d0</option></term>
+ <listitem>
+ <para>Supress all informational messages.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d <replaceable>N</replaceable></option></term>
+ <listitem>
+ <para>Enable cummulative debugging levels from 1 to n. Values are:
+ <orderedlist>
+ <listitem>Show the actions taken for building targets, as they are executed (the default).</listitem>
+ <listitem>Show "quiet" actions and display all action text, as they are executed.</listitem>
+ <listitem>Show dependency analysis, and target/source timestamps/paths.</listitem>
+ <listitem>Show arguments and timming of shell invocations.</listitem>
+ <listitem>Show rule invocations and variable expansions.</listitem>
+ <listitem>Show directory/header file/archive scans, and attempts at binding to targets.</listitem>
+ <listitem>Show variable settings.</listitem>
+ <listitem>Show variable fetches, variable expansions, and evaluation of '"if"' expressions.</listitem>
+ <listitem>Show variable manipulation, scanner tokens, and memory usage.</listitem>
+ <listitem>Show profile information for rules, both timing and memory.</listitem>
+ <listitem>Show parsing progress of Jamfiles.</listitem>
+ <listitem>Show graph of target dependencies.</listitem>
+ <listitem>Show change target status (fate).</listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d +<replaceable>N</replaceable></option></term>
+ <listitem>
+ <para>Enable debugging level <replaceable>N</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o <replaceable>file</replaceable></option></term>
+ <listitem>
+ <para>Write the updating actions to the specified file instead of running them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s <replaceable>var</replaceable>=<replaceable>value</replaceable></option></term>
+ <listitem>
+ <para>Set the variable <replaceable>var</replaceable> to
+ <replaceable>value</replaceable> in the global scope of the jam
+ language interpreter, overriding variables imported from the
+ environment.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</section>
Modified: trunk/tools/build/v2/doc/src/standalone.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/standalone.xml (original)
+++ trunk/tools/build/v2/doc/src/standalone.xml 2010-10-06 16:18:09 EDT (Wed, 06 Oct 2010)
@@ -39,7 +39,7 @@
<appendix id="bbv2.jam">
<title>Boost.Jam Documentation</title>
<xi:include href="jam_docs.xml" parse="xml"
- xpointer="xpointer(id('jam.intro')|id('jam.intro')/following-sibling::*)"/>
+ xpointer="xpointer(id('jam.building')|id('jam.building')/following-sibling::*)"/>
</appendix>
<index/>
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