[BBv2 doc editorial] Projects

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-22 13:03:28

> Projects
> 
> As mentioned before, targets are grouped into projects, and each
> Jamfile is a separate project. Projects are useful because they
> allow us to group related targets together, define properties common
> to all those targets, and assign a symbolic name to the project that
> can be used in referring to its targets.
> 
> Projects are named using the project rule, which has the following syntax:
> 
> project id : attributes ;
^^ ^^^^^^^^^^---- "attribute-declarations"
^^
"project-id"

> Here, attributes is a sequence of rule arguments, each of which
> begins with an attribute-name and is followed by any number of build
> properties. The list of attribute names along with its handling is
> also shown in the table below. For example, it is possible to write:
> 
> project tennis 
> : requirements <threading>multi 
> : default-build release
> ;
> 
> The possible attributes are listed below.
> 
Use the correct spelling for all of these as they should appear in
code. No capitalization, underscores or dashes as appropriate, etc.
Set it in an appropriate font. I know you're trying to keep project
id separate, but listing it as an attribute at all is misleading.
The syntax description above implies that it can go after the colon,
and other elements of the docs suggest that it will be inherited by
children.
VVVVVVVVVV
> Project id is a short way to denote a project, as opposed to the
^^^^^
strike

> Jamfile's pathname. It is a hierarchical path, unrelated to
"often"-----------^ "the"-----^
> filesystem, such as "boost/thread". 
> Target references make use of project ids to specify a target.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

the part of a target references that appears before "//" is either
a project id or a directory path

:(

Once again, I've said it a thousand times and I still believe it:
project ids should be clearly, syntactically, distinguished.

@some/project/id//target-name

would be less confusing and less error-prone. And I still don't
understand the need for the double slash. Is there any practical use
for a target name that contains a slash?

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

Not quite

"The paths to source files used by targets in this project are given
relative to this directory"

would be more accurate.

> Project requirements are requirements that apply to all the targets
> in the projects as well as all subprojects.
^^^^^^^^
"project"
> 
> Default build is the build request that should be used when no build
> request is specified explicitly.

Really? So when a build request is given, all the contents of default
build are ignored? I think this contradicts earlier statements that
default build is the list of properties that will be used unless 
a value for the same feature is specified by the user.

> The default values for those attributes are given in the table below.
> 
> Table 4.1. 
> +---------------+---------------+--------------------+--------------------+
> |Attribute |Name |Default value |Handling by the |
> | | | |project rule |
> +---------------+---------------+--------------------+--------------------+
> |Project id |none |none |Assigned from the |
^^^^^^^^^^^^^
"set to the value of"
> | | | |first parameter of |
> | | | |the 'project' |
> | | | |rule. It is assumed |
> | | | |to denote absolute |
> | | | |project id. |
> +---------------+---------------+--------------------+--------------------+
> |Source location|source-location|The location of |Sets to the passed |
> | | |jamfile for the |value |
^^^^^^^-"the Jamfile"
> | | |project | |
> +---------------+---------------+--------------------+--------------------+
> |Requirements |requirements |The parent's |The parent's |
> | | |requirements |requirements are |
> | | | |refined with the |

"refined with" is still mysterious.

> | | | |passed requirement |
> | | | |and the result is |
> | | | |used as the project |
> | | | |requirements. |
> +---------------+---------------+--------------------+--------------------+
> |Default build |default-build |none |Sets to the passed |
> | | | |value |
> +---------------+---------------+--------------------+--------------------+
> |Build directory|build-dir |Empty if the parent |Sets to the passed |
> | | |has no build |value, interpreted |
> | | |directory |as relative to the |
> | | |set. Otherwise, the |project's location. |
> | | |parent's build | |
> | | |directory with with | |
^^^^
strike
> | | |the relative path | |
> | | |from parent to the | |
> | | |current project | |
> | | |appended to it. | |
> +---------------+---------------+--------------------+--------------------+
>
> Besides defining projects and main targets, Jamfiles commonly invoke
> utility rules such as constant and path-constant, which inject a
> specified Boost.Jam variable setting into this project's Jamfile
> module and those of all its subprojects. See the section called
> “Jamfile Utility Rules” for a complete description of these utility
> rules. Jamfiles are regular Boost.Jam source files and Boost.Build
> modules, so naturally they can contain any kind of Boost.Jam code,
> including rule definitions.
> 
> Each subproject inherits attributes, constants and rules from its
> parent project, which is defined by the nearest Jamfile in an
> ancestor directory above the subproject. The top-level project is
> declared in a file called Jamroot rather than Jamfile. When loading
> a project, Boost.Build looks for either Jamroot or Jamfile. They are
> handled indentically, except that if the file is called Jamroot, the
> search for a parent project is not performed.
> 
> Even when building in a subproject directory, parent project files
> are always loaded before those of their subprojects, so that every
> definition made in a parent project is always available to its
> children. The loading order of any other projects is
> unspecified. Even if one project refers to another via use-project,
> or a target reference, no specific order should be assumed. Note

Strike the following note. It makes calling the root Jamfile
"Jamroot" sound like it is optional.

> Giving the root project the special name “Jamroot” ensures that
> Boost.Build won't misinterpret a directory above it as the project
> root just because the directory contains a Jamfile.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com