Solving the target reference problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-23 14:43:02

In recent editorial postings I've described problems with paths and
target references. In this post I am proposing a solution. Volodya
and I discussed the solution offline, and he has agreed in principle.
I am adding some details such as rule names and argument order here
that we did not discuss; I expect there to be some minor issues to
work out around those. One open question is whether leading slashes
should ever be used on project IDs. It would be simpler -- and
probably better -- to forbid it. I have placed some alternative rules
-- should we decide the leading forward slash must be allowed -- in
double square brackets below, for discussion.

Comments appreciated.

Paths
-----

All paths can be described to in the host platform's native format
(unfortunately on Windows that means either quoting or doubling
backslashes). All _relative_ paths can also be described in *nix
format, also known as "the portable path format", using forward
slashes. [¹]

Project IDs
-----------

Project ID constants:
In accordance with the conclusion of
http://thread.gmane.org/gmane.comp.lib.boost.build/5864, 

use-project boost-release : path/to/some/boost/tree ;

establishes a project ID constant "boost-release" for the project
whose Jamroot is in path/to/some/boost/tree. Like constants
and path constants defined in projects, a project id constant
is in effect in all subprojects unless explicitly overridden. [[Such
a constant does not have a leading slash.]]

Project ID aliases:
if the second argument to use-project begins with '@', the rest of
that argument is expected to be a project id, rather than a path.

use-project boost-release : @boost-1.33.0

creates a project ID constant "boost-release" for a project with
project ID "boost-1.33.0"

ID construction:
A subproject X of a project Y can be referred to by prepending an id
for Y that is valid in the current project to an ID for X that is
valid in Y. So for example, after 

use-project boost-release : @boost-1.33.0 ;

if "boost-1.33.0" has a subproject "serialization,"

boost-release/serializaton 

is a valid ID for that subproject

Relative path subproject/superproject IDs:
A portable path from any project X to any other project Y is a valid
project ID for Y in X, and takes precedence over project IDs declared
in any projects other than X.

Default Global Project IDs:
Every project can declare its own project IDs with the project rule:

project boost ;
project boost-1.33.0 ;

Those ids ID refers to the same project in any other project that
does not use the same identifier as a project id constant -and- does
not have a subdirectory by that name. [[They can also be referred to
from anywhere using the leading slash:

/boost-1.33.0
]]

Ambiguities:
The ways to interpret a project ID are given a strict precedence by
the rules already expressed here, ensuring they are always
unambiguous. To recap, in order of decreasing precedence:

1. project ID constants declared in this Jamfile
2. relative path project IDs
3. project ID constants inherited from parent projects
4. default global project IDs

A project ID will never be subject to unexpected redefinition due
to a remote change, since local project IDs and relative paths get
the highest precedence.

Two projects declaring the same global project ID can be referred
to unambiguously by assigning them to different project ID
constants.

Target References
-----------------

Syntax:
Target references always consist of the '@' character, followed by a
project ID, followed by a slash, followed by the name of a target
declared in that project. 

Thanks to relative path project IDs and the ID construction rule,
there's no need to ever include a slash in a target name[²] and
there's no need for a double slash separating project ID and target
name. Thanks to the leading '@', project IDs will never be confused
with paths in the filesystem.

Footnotes: 
[¹] If we encounter a platform where forward
slashes can be part of a legitimate path we'll introduce a way to
escape them. If we encounter a platform where *nix paths are
legitimate native paths with a different meaning we'll introduce a way
to escape native paths.

[²] Should we ever encounter a need to include slashes in a target
names, we'll introduuce a way to escape them.

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