[jamming] How does the grist works ?

[Ingo Weinhold]

On 2007-05-12 at 12:39:11 [+0200], Mildred <ml.mildred593 at online.fr> wrote:
> 
> I'm using Jam but i dtill don't understand wll whet the grist is and
> how to use it. If I understand well, the grist is the text in <>
> appended at the beginning of a target and hat contains the path of the
> target so it can't conflicts with others targets with the same name in
> other directories.
> 
> What I don't understand is why the complete path is not used instead.
> It will also avoid conflicts and it wold not make jam incompatible with
> files containing the characters <!> in their names.

I guess <...> was chosen since it's reasonably unlikely to appear at the 
beginning of file names, particularly those files that build systems 
usually deal with.

The path is not used to make target names unique for a few reasons. For one 
the path might not always be the same. E.g. when compiled with debugging 
turned on output files could be placed in a different directory. Their path 
would be different, but the (gristed) target name remains the same. Using 
only the file name is particularly nice for high level targets 
(executables, libraries). They usually don't need grist at all or a simple 
one suffices, so you have beautifully short names to address them. E.g. to 
link an executable against libfoobar.so you really just need to add 
"libfoobar.so" to NEEDLIBS and don't have to care where it is built.

> Also, If I understand how it works, it is up to the rule to add the
> grist to the target.

That depends. There are certain rules that add grist automatically, usually 
for "low level" targets like source and object files.

> But how to make shure that the action called
> afterwards is given a complete path and not something with a grist
> that the shell do not understand.

Before jam executes an action, it constructs the path for each involved 
target. The process is called binding. For binding a target jam uses two 
variables that can be set on the target: SEARCH and LOCATE. LOCATE is set 
on targets that are generated. If set, it should contain the path of the 
directory the target should be created in. If not set, the target is 
assumed to be already existing and SEARCH is consulted. It can contain a 
list of directories in which to search for the target. If the target could 
not be found jam simply uses the file name (without the grist, of course).

Note that only the targets in actions parameters $(1) and $(2) are bound by 
jam; targets in variables are not bound be default. You can request binding 
for any variable, though:

actions FooBar bind VARIABLE_TO_BE_BOUND
{
	...
}

> Actually, when I write a rule, it's quite simple. For example I wrote
> an Xslt rule like that:
>
> rule Xslt destination : source : xslt {
>     Xslt1 $(destination) : $(xslt) $(source) ;
>     Depends $(destination) : $(xslt) $(source) ;
> }
> action Xslt1 {
>     xsltproc $(2) > $(1)
> }

Unless you already do that where your rule is invoked you should at least 
set SEARCH on the input files and LOCATE on the output file (the latter via 
MakeLocate). Depending on whether you consider it likely that files with 
the same name are used in different directories, you also want to add grist 
in your rule. Furthermore, if you want "jam clean" to remove the generated 
file, you have to say so explicitely. The rule could look like:

rule Xslt _destination : _source : _xslt {
	local destination = [ FGristFiles $(_destination) ] ;
	local source = [ FGristFiles $(_source) ] ;
	local xslt = [ FGristFiles $(_xslt) ] ;

	SEARCH on $(source) $(xslt) = $(SEARCH_SOURCE) ;
	MakeLocate $(destination) : $(LOCATE_TARGET) ;

	Xslt1 $(destination) : $(xslt) $(source) ;
	Depends $(destination) : $(xslt) $(source) ;
	Clean clean : $(destination) ;
} 

CU, Ingo