Re: Signature configurability: documentation review

[Steven Knight]

> I found one paragraph in the draft strange:
> >
> >   Note that a file will be rebuilt whenever anything about a dependent
> >   file changes. In particular, because Cons looks for exact timestamp
> >   matches in the .consign file, *any* change to the modification time of a
> >   dependency, forward or backwards in time, will force a rebuild of the
> >   derived file.
> 
> Isn't this plain wrong, and should be removed  ?
> Maybe a rest from early versions of cons when timestamps mattered ?

You're right, the above paragraph is essentially a hold-over from
the previous documentation.  It essentially makes the point (again)
that Cons signatures are better than Make timestamps.  I left it in
without thinking much of it because it's still narrowly correct for a
specific interpretation related to looking for exact timestamp matches
in .consign files.  At a minimum, it needs to be expanded to mention the
new configurability.  I'll reword it or strike it.

> I also want to ask a question as a non-native speaker of English:
> 
>   I think I know what a "dependency" is:
>   eg. an object file has it's source file as a "dependency"
>   ( foo.o ----> foo.c )
> 
>   The draft documentation sometimes uses the word "depedent file".
>   I get the impression that the "arrow" here points in the other
>   direction (but not in the text I proposed to remove above).
> 
>   When I try to look these word up in a dictionary I can't see any
>   indication that they point in different directions.
>   This confuses me ...

I do actually draw the arrow in the other direction: foo.o <= foo.c
If foo.c changes, you have to update foo.o, so foo.o being up-to-date
"depends on" the contents of foo.c.  Your observation that the term
"dependent file" is ambiguous, though, is a good one.  I'll take a look
at rewording those uses to make it clearer.

> >     Patterns will also match files across directories; the pattern
> >     `foo/*.la' would match all (UNIX) library archives in any subdirectory
> >     underneath the foo subdirectooy.
> >
> 
> Should this be "foo/*.a" ???
> Or what does ".la" mean ? Is it some Linux specific extension ???

No, it's a typo.  I started out using "foo/*.lib" for a Win32 example,
and didn't get all of the extension when I switched the order of the
examples...  Thanks for catching it.

> >      $env = new cons(SIGNATURE => ['foo/*.o' => 'build',
> >                                    '*.o' => 'consign content',
> >                                    '*.a' => 'consign build',
> >                                    '*' => 'content']);
> 
> I use cons on both Win32 and different UNIX-versions, and wonder how
> one is supposed to write platform-independent Construct files.
> (if one wants the same "signature policy" on all platforms)
> 
> (this question comes up every now and then; of course it is solvable
> (this is Perl :-)), but the question is how easy ...)
> 
> Should I write like the following ?
> 
>     $env = new cons(SIGNATURE => ['foo/*.%SUFOBJ' => 'build',
>                                   '*.%SUFOBJ' => 'consign content',
>                                   '*.%SUFLIB' => 'consign build',
>                                   '*' => 'content']);

*Very* good point.  I think you're on the right track, and this
shouldn't be too hard to do for the SIGNATURE array.  But, there isn't
going to be any way to do the same thing for the SourceSignature()
method, because there's no environment there...  Maybe that's all right,
though, because you should at least *know* what the extensions are for
the source files in a given package you're building, regardless of the
underlying OS.

This brings up another portability issue:  The current implementation
isn't doing anything to map '/' separators in the patterns to match the
operating system's separators.  I'll add this as well.

Excellent points to catch.  Thanks again.

        --SK