From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-09-27 09:16:09
On Friday 23 September 2005 23:43, David Abrahams wrote:
> 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.
So, here's a refined version. Comments are welcome!
Referring to projects
To refer from one Boost.Build project to another project, we use the notion
of project id. The simplest project id is a path to another project's Jamfile.
Such path can be either absolute, or relative to referring Jamfile.
Since the paths can become long and inconvenient, we also provide symbolic
names that can be used to shorten paths. For example:
can possibly be abbreviated to boost/filesystem, where "boost" is a symbolic
name defined in referring Jamfile to mean "/home/ghost/Work/boost-rc", and
"filesystem" is a symbolic id defined in Boost's Jamfile to mean
"libs/filesystem". Below, semantic of project ids is detailed.
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
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.
Absolute path to project Y is a valid project ID for Y in X.
Symbolic project id:
A project can define symbolic project ID using the "use-project" rule.
use-project boost-release : path/to/some/boost/tree ;
After this declaration, project id "boost-release" becomes valid
in the project where "use-project" is invoked, and is equivalent to
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"
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,"
is a valid ID for that subproject
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:
[ VP: Is this the same as "use-project boost : . ; " ? ]
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
To summarize the above, resolution of project id is performed by
1. Set "current-project" to the project where project ID is used.
2. Take leftmost slash separated part of project ID
3. Check if the leftmost part is:
- symbolic project id defined in current project
- directory under current projects directory
- symbolic project id defined in current projects parent's
- default global project ID
4. The first match in point 3 gives us the directory referred to by the
leftmost part. We set current project to that directory, remove the
leftmost part from project ID and continue again.
5. If the directory found at some step has no Jamfile, then we don't check
for symbolic project IDs in next 3, but process is otherwise the same.
Referring to targets
To refer in Jamfile to a file in the source directory for that Jamfile,
the name of file is used. To refer in a Jamfile to a target defined in
the same Jamfile, the name of target is used. [[ Need to decide what
happens if a name matches both a file and a target. Now, we use file ]].
To refer to a target in another project, it's needed to specify the project-id
for that other project, followed by slash, and followed by target or file
name that's valid in that project.
Note: A target name is not allowed to contain a slash, so there's no need to
separate project id and target name with a double slash.
[¹] 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.
-- Vladimir Prus http://vladimir_prus.blogspot.com Boost.Build V2: http://boost.org/boost-build2
Boost-Build 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