[jamming] I really wish this was handled in a manual somewhere...

[Alen Ladavac]

Hi Matt,

Here's a try: (Note that I might not be perfectly accurate in this, so
it's probably best to recheck what I say.... all warranty disclaimed)

First, you have to distinguish between variables and targets (where
sources and includes are also "targets" to the sense that they are
bound to files). If you are merely dealing with a variable, feel free
to add/remove/change grist anyway you like - it's just a piece of the
string, with convenient ":" modifiers. If it will be a file, then you
can use grist to specify that there are two same names that refer to
different items on the disk. For this, you can assign different
LOCATE/SEARCH paths, so they will be located in different places. Now,
for the grist itself you can use any string you like, as long as it is
different. It is merely there to make a distinction between two
items so they can be bound to different files. Their original name
(without the grist) will be used to actually find the file in that
path.

Grist on sources is mostly useful if e.g. your C code uses relative
includes to files with the same name (stdafx.h anyone?) in different
directories. Then you have to grist them, and assign different paths
to them, from within the rule that handles includes (mine's totally
reworked, so I can't give exact suggestions on what to do with the
default one).

It can also be useful to build same sources with different parameters.
Then you may have to force the scanner to rescan the same C file for
headers using different include dirs.

I'm also using grist when doing some preprocessing on h files, to
prevent jam from automatically reprocessing an h file, when one of its
included h files changed. There I have two "targets" with different
grists for each h file. One is passed to the jam's h-file scanner, and
another is used in the preprocessing actions. In this case, they are
the same file altogether, but that file is a member of two different
dependency trees.

I've almost never found a use for grist on real targets (outputs),
because I mostly find it more convenient to just specify full paths
for them. I mostly like to specify full paths (relative to some
workspace root), whenever possible, as it makes everything so much
simpler (IMO).

Finally, I've even used grist in completely funny ways to specify
which disk a file ends up on in an installer. This has nothing to do
with the way jam expects it, but it is convenient because I don't have
to extract that info from a string using a MATCH rule, if I can
just specify the info with <disknum>.

In the end, for the task at hand, it looks like grist is not needed at
all. If you are going to be using the full path to the xml file in the
action, then you can as well specify that path directly, and simplify
it all.

In comment to the notion that your scripts use the grist inconsistenty
- it doesn't have to be consistent - you just have to make sure that
the grist is properly set before giving the var to Depends, Includes
or an Action. And you don't actually need it for things where you know
there's no duplication. So, perhaps the scripts you're working on
really are untidy, but maybe you're just looking at it from a wrong
perspective. I can't claim, but just pointing out a possibility.

HTH,
Alen


Matt wrote:

> but for the bagillionth time I'm having difficulty using grist.

> I've inherited a fairly complex build (The person who really
> understands how and why things are the way they are in it has left the
> project) which seems to use grist fairly inconsistently.

> What I'd like to know is what the lifecycle of a variable representing
> a file which needs to be uniquely identified is.

> That is, if I've got two files which share the same name in different
> directories (which is the situation in which I need grist if I
> understand it correctly).

>    Where in the build do I first put grist on the variable? (When I
> first define it or can I delay until when it's passed into a rule)
>    When do I strip grist off of a file or somehow convert it to a
> path-qualified file name?

> Just to make this interesting... you can solve part of the problem I'm having:

> I need jam to make calls to ant, so I've got a rule ApacheAnt
> it needs to call `ant -f "path/to/my/build.xml"` where the build.xml
> file is in the same directory as the jamfile that calls the rule.
> The call to the rule should know (<) what files it creates and (>)
> where it's build.xml and source .java files are (they are in a
> subdirectory of the directory containing build.xml)
> I've got multiple calls to ant, and thus several files called
> build.xml in different subdirectories.


> I'm aware that there have been tons of grist questions in the past,
> but I can't seem to find any very definitive answers... I'm sorry if
> I've missed something.

> Thanks a bunch,
>    ~Matthew E. Boyce
> _______________________________________________
> jamming mailing list  -  jamming at perforce.com
> http://maillist.perforce.com/mailman/listinfo/jamming



-- 
Alen