Re: [jamboost] Solving the target reference problems

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:

/home/ghost/Work/boost-rc/libs/filesystem

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.

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
-----------

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
using "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

           
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
  ]]

[ VP: Is this the same as "use-project boost : . ; " ? ]
  

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.

Resolution process:

To summarize the above, resolution of project id is performed by
these steps:
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.

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.

- Volodya

-- 
Vladimir Prus
http://vladimir_prus.blogspot.com
Boost.Build V2: http://boost.org/boost-build2