From 55c99be4fc82cd412f2cf3c532f43e2ed1eda5bc Mon Sep 17 00:00:00 2001 From: Steven Watanabe Date: Wed, 4 Apr 2012 16:46:39 +0000 Subject: [PATCH] Document abstract-target and its subclasses. [SVN r77757] --- doc/src/abstract-target.xml | 115 +++++++++++++++++++++++ doc/src/basic-target.xml | 101 ++++++++++++++++++++ doc/src/main-target.xml | 83 +++++++++++++++++ doc/src/project-target.xml | 179 ++++++++++++++++++++++++++++++++++++ doc/src/reference.xml | 8 ++ 5 files changed, 486 insertions(+) create mode 100644 doc/src/abstract-target.xml create mode 100644 doc/src/basic-target.xml create mode 100644 doc/src/main-target.xml create mode 100644 doc/src/project-target.xml diff --git a/doc/src/abstract-target.xml b/doc/src/abstract-target.xml new file mode 100644 index 000000000..252253054 --- /dev/null +++ b/doc/src/abstract-target.xml @@ -0,0 +1,115 @@ + + + +
+ + Class abstract-target + + abstract-target + + + + Base class for all abstract targets. + + + + Classes derived from abstract-target: + + + project-target + + + main-target + + + basic-target + + + + + + + + rule __init__ ( name : project-target ) + + + + name + + Name of the target in Jamfile. + + + + project-target + + The project target to which this one belongs. + + + + + + + + + name + Abstract Target + + rule name ( ) + Returns the name of this target. + + + + + project + Abstract Target + + rule project ( ) + Returns the project for this target. + + + + + location + Abstract Target + + rule location ( ) + Return the location where the target was declared. + + + + + full-name + Abstract Target + + rule full-name ( ) + Returns a user-readable name for this target. + + + + + generate + Abstract Target + + rule generate ( property-set ) + + Generates virtual targets for this abstract target using the specified + properties, unless a different value of some feature is required by the + target. This is an abstract method which must be overriden by derived + classes. + + + + On success, returns: + + a property-set with the usage requirements to be applied to dependents + a list of produced virtual targets, which may be empty. + + If property-set is empty, performs the + default build of this target, in a way specific to the derived class. + + + + + +
diff --git a/doc/src/basic-target.xml b/doc/src/basic-target.xml new file mode 100644 index 000000000..e2a462e69 --- /dev/null +++ b/doc/src/basic-target.xml @@ -0,0 +1,101 @@ + + + +
+ + Class basic-target + + basic-target + + + + Derived from abstract-target. + + + + Implements the most standard way of constructing main target alternative from + sources. Allows sources to be either files or other main targets and handles + generation of those dependency targets. + + + + + + + rule __init__ ( name : project : sources * : requirements * : default-build * : usage-requirements * ) + + + + rule name ( ) + + Returns the name of this target. Inherited from + abstract-target. + + + + + rule project ( ) + + Returns the project for this target. Inherited from + abstract-target. + + + + + rule location ( ) + + Return the location where the target was declared. Inherited from + abstract-target. + + + + + rule full-name ( ) + + Returns a user-readable name for this target. Inherited from + abstract-target. + + + + + + generate + Basic Target Method + + rule generate ( property-set ) + + Overrides + abstract-target.generate. + + Determines final build properties, generates sources, and calls + construct. + This method should not be overridden. + + + + On success, returns: + + a property-set with the usage requirements to be applied to dependents + a list of produced virtual targets, which may be empty. + + + + + + + construct + Basic Target Method + + rule construct ( name : source-targets * : properties * ) + + Constructs virtual targets for this abstract target and the dependency + graph. Returns a usage-requirements property-set and a list of virtual + targets. Should be overriden in derived classes. + + + + + +
diff --git a/doc/src/main-target.xml b/doc/src/main-target.xml new file mode 100644 index 000000000..1dde67825 --- /dev/null +++ b/doc/src/main-target.xml @@ -0,0 +1,83 @@ + + + +
+ + Class main-target + + main-target + + + + Derived from abstract-target. + + + + A main-target + represents a named top-level target in a Jamfile. + + + + + + rule name ( ) + + Returns the name of this target. Inherited from + abstract-target. + + + + + rule project ( ) + + Returns the project for this target. Inherited from + abstract-target. + + + + + rule location ( ) + + Return the location where the target was declared. Inherited from + abstract-target. + + + + + rule full-name ( ) + + Returns a user-readable name for this target. Inherited from + abstract-target. + + + + + + generate + Main Target Method + + rule generate ( property-set ) + + Overrides + abstract-target.generate. + + Select an alternative for this main target, by finding all alternatives + whose requirements are satisfied by property-set and + picking the one with the longest requirements set. Returns the result + of calling generate + on that alternative. + + + + On success, returns: + + a property-set with the usage requirements to be applied to dependents + a list of produced virtual targets, which may be empty. + + + + + + +
diff --git a/doc/src/project-target.xml b/doc/src/project-target.xml new file mode 100644 index 000000000..6e57ce438 --- /dev/null +++ b/doc/src/project-target.xml @@ -0,0 +1,179 @@ + + + +
+ + Class project-target + + project-target + + + + Derived from abstract-target. + + + + This class has the following responsibilities: + + + + Maintaining a list of main targets in this project and building them. + + + + + + + Main targets are constructed in two stages: + + + + When Jamfile is read, a number of calls to 'add-alternative' are made. At + that time, alternatives can also be renamed to account for inline targets. + + + + + The first time 'main-target' or 'has-main-target' rule is called, all + alternatives are enumerated and main targets are created. + + + + + + + + + rule name ( ) + + Returns the name of this target. Inherited from + abstract-target. + + + + + rule project ( ) + + Returns the project for this target. Inherited from + abstract-target. + + + + + rule location ( ) + + Return the location of the project. Inherited from + abstract-target. + + + + + rule full-name ( ) + + Returns a user-readable name for this target. Inherited from + abstract-target. + + + + + + generate + Project Target + + rule generate ( property-set ) + + Overrides + abstract-target.generate. + + Generates virtual targets for all the targets contained in this project. + + + + On success, returns: + + a property-set with the usage requirements to be applied to dependents + a list of produced virtual targets, which may be empty. + + + + + + + build-dir + Project Target Method + + rule build-dir ( ) + + Returns the root build directory of the project. + + + + + + main-target + Project Target Method + + rule main-target ( name ) + + Returns a main-target + class instance corresponding to name. + + + + + has-main-target + Project Target Method + + rule has-main-target ( name ) + + Returns whether a main-target + with the specified name exists. + + + + + + find + Project Target Method + + rule find ( id : no-error ? ) + + Find and return the target with the specified id, treated relative to + self. Id may specify either a target or a file name with the target taking + priority. May report an error or return nothing if the target is not found + depending on the no-error parameter. + + + + + + + + + +
diff --git a/doc/src/reference.xml b/doc/src/reference.xml index 937b578c0..b0e30ccd3 100644 --- a/doc/src/reference.xml +++ b/doc/src/reference.xml @@ -1953,6 +1953,14 @@ import path : native make : native-path make-path ; +
+ Builtin classes + + + + +
+
Build process