Re: Solving the target reference problems

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-30 11:46:25

Vladimir Prus <ghost_at_[hidden]> writes:

> On Tuesday 27 September 2005 20:42, David Abrahams wrote:
>> Vladimir Prus <ghost_at_[hidden]> writes:
>> > So, here's a refined version. Comments are welcome!
>>
>> What encoding did you use? 
>
> Content-Type: text/plain;
> charset=ISO-8859-1

Hmm, that doesn't seem to help.

>> I'm seeing underscores everwhere I had two 
>> adjacent spaces in the original document. 
>
> I don't understand this, sorry. I did not notice any adjacent spaces
> in the original

All the indentation was done with adjacent spaces, and I usually use
two spaces after a period.

> and don't see any underscores in the new version.

Gnus is showing me red underscores. In the raw article the underlines
show up as "=A0".
Anyway, no big deal.

>> I'm unhappy with the reordering of sections and the dropping of the
>> notion "project ID constant," which had conceptual value because of
>> the way it applies in subprojects (and is adjusted like a path
>> constant) until overridden,
>
> Ok, I did not notice that extra meaning you put in the
> term. However, I'm not happy with "project ID constant" still. It's
> not just constant that happens to be project ID, it's also name
> that's not related to filesystem path, that's why I stick "symbolic"
> everywhere. Note also that those project ID constants are not
> available with $(NAME) syntax, like orginary constants are.

Okay, I agree. You're right.

>> and with the removal of the section on project ID construction, 
>
> It's not removed. If fact, it's still there without any changes.

Sorry, I was running on no sleep as I tried to prepare my talk for SD
best practices. It's there.

>> and the moving of some information from there into the introductory
>> section; that now has too much detail.
>
> Previously, there were no overview at all. I had to gather the basic
> idea by looking at the *entire* document.

I understand now. The original was intended to be a reference
document for the features related to changes we were making, not
something to be dropped into the user documentation. For example, the
section on Paths doesn't belong under "referring to projects," since
there are plenty of other things you can do with paths.

>> Did you actually apply the changes we decided in the chat you
>> posted? Could you post a condensed list of changes?
>
> * We clarified the process that resolves project refereces --
> basically that we take left-most element, look it up in the
> order given in "Ambiguities" section, get new project and continue

Okay.

> * We clarified that after: 
>
> use-project boost : ...... ;
>
> in project foo, one can use "boost" in that project and one can use
> "foo/boost" elsewhere. There's no way to declare project ID that's
> not accessible from outside.

Right.

> * The leading "@" is not needed

Right. You left one use of it in the revised docuument.

> * The double slash is indeed not needed. We agreed that target names with 
> slash in them are disallowed.

Right.

> Changes that did not make into the document:
>
> * If project defines symbolic project ID "serialization", it's not
> possible to access "serialization" subdirectory under that project.
> If such need arises, we'll introduce some escaping syntax.

Good. I think we agreed that a trailing slash could indicate "I
really mean a directory."

Another issue: you wrote,

"The simplest project id is a path to another project's Jamfile."

The problem with that description is that it gives the impression that
a path to a Jamfile can always be used as a project ID, when in fact,
any definition of a symbolic project ID can change make some legal
paths to Jamfiles into illegal project IDs.

Also, we don't "provide symbolic names," we provide the ability to
_define_ symbolic names.

In answer to [ VP: Is this the same as "use-project boost : . ; " ?
], about "project boost": no, because it applies to all projects, even
if they are not subprojects of this one. That said, I'm changing the
way this is done.

I also think we've got trouble with the "source directory" concept.
As far as I'm concerned, if some relative paths are interpreted
w.r.t. to the source directory and some are interpreted w.r.t. the
directory containing the Jamfile, we're in deep doo-doo. For now, I'm
not trying to resolve the conflict: I'm leaving mentions of the source
directory in your "referring to targets" section alone, and not trying
to incorporate it into the other sections. 

If the "source directory" concept is important enough to keep (I have
serious doubts; the KISS argument might apply here), I favor making
all paths interpreted relative to that directory. I also favor
changing the name to "current directory" and adding a "cd" rule, so
that it's clear that a project reference followed by a rule that
changing the source/current directory is not interpreted relative to
the new directory. In other words, "source directory" is not a static
property of the project and it doesn't just apply to sources. This
still leaves some problems, I see. When interpreting X/Y in a Jamfile
other than X's, relative to what is the search for Y performed? KISS
indeed.

Anyway, here's my cleanup of your revisions. I also made a few
additions. I am beginning to hate the name "use-project" for this
purpose so I've changed it to "project-id"

--
====================
User Manual Material
====================
Referring to projects
=====================
To refer from one project to another, we use project IDs. By default,
any path to a project's Jamfile is a legal ID for that project. For
example, in 
/lib/proj1/Jamfile 
we might refer to the project in
/lib/proj2 
as ../proj2.
We can also define symbolic project aliases. For example, in
/lib/proj1/Jamfile 
project-id boost : /home/ghost/Work/boost-rc ;
defines a project ID boost that is an alias for
/home/ghost/Work/boost-rc. The new project ID is valid in
/lib/proj1/Jamfile and is inherited by all of its subprojects. Also,
any project ID <emph>x</emph> that is valid in
/home/ghost/Work/boost-rc/Jamfile can now be referred to as
boost/<emph>x</emph>.
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.
==================
Reference Material
==================
Paths in the Filesystem
=======================
All paths can be described to in the host platform's native
format. Regardless of platform, all _relative_ paths can also be
described in *nix format, also known as "the portable path format",
using forward slashes. [¹] On Windows only, backslashes can replaced
by forward slashes in absolute paths without a change in meaning.
Project IDs
===========
Project IDs can be formed in several ways. In order of precedence:
[note, below, the tokens X, Y, Z, new-id, old-id, p1, and p2 should be
formatted as <replaceable>]
Symbolic project aliases
------------------------
The project-id rule declares a symbolic alias for some valid project
ID. In project X,
project-id new-id : old-id ;
Makes new-id an alias for old-id in X, overriding any other IDs by the
same name in X.
Filesystem Paths
----------------
Any filesystem path p1 (absolute or relative) from project X
to any other project Y is a valid project ID for Y in X, unless p1 is
defined as a project alias in X.
Inherited symbolic aliases
--------------------------
A project alias p1 defined in one of X's ancestor projects is also a valid
project ID in X, unless X defines a project alias with the same name
or p1 is also a valid path in the filesystem.
Default Global Project IDs
--------------------------
When called with one argument, the project-id rule declares an alias
for the project in which it is invoked. That alias is also treated as
inherited in every Jamroot.
For example, in a project X,
project-id boost ;
project-id boost-1.33.0 ;
declares two aliases for X, overriding any subdirectories by the same
name. The aliases are also inherited by all of the current project's
Jamfiles and—indirectly—by all other projects, but may be overridden
by alias declarations or conflicts with filesystem paths.
ID construction
---------------
If p1 is a ID for Y in X's Jamfile, and p2 is a valid ID for Z in Y's
Jamfile, p1/p2 is a valid id for Z in X's Jamfile. 
For example, after
project-id boost-release : boost-1.33.0 ;
if the project identified by boost-1.33.0 has a subproject with ID
serialization,
boost-release/serializaton 
is a valid ID for that subproject
Rationale
---------
The ways to interpret a project ID are given a strict precedence by
the rules already expressed here, ensuring they are always
unambiguous.
1. project aliases declared in this Jamfile
2. paths in the filesystem
3. project aliases 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 locally-defined project aliases and
relative paths get higher precedence.
Two projects declaring the same global project ID can be referred
to unambiguously by path, or by first declaring a new alias for one
of them.
Resolution process
------------------
[This is a suggested replacement]
# returns the path to a directory corresponding to the given project
# id interpreted in the given jamfile.
def get_project_dir( jamfile, id ):
elements = id.split('/')
top_path = jamfile.local_aliases.getdefault(elements[0], None)
if not top_path:
if os.path.exists(id):
return id
top_path = jamfile.inherited_aliases.getdefault(elements[0], None)
if not top_path:
raise "can't resolve project ID"
return os.path.join(
top_path, 
get_project_dir( the_jamfile_in(top_path), elements[1:] )
)
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. 
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