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;
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
> * 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.
> * 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.
> 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
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, None) if not top_path: if os.path.exists(id): return id top_path = jamfile.inherited_aliases.getdefault(elements, 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
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