|plain (actually nameless)||
The plain signature method is the files modification time and the files
size, concatenated. These values are quickly obtainable from the operating
system and almost always change when the file changes.
Makepp used to look only at the files modification time, but if you run makepp several times within a second (e.g., in a script thats building several small things), sometimes modification times wont change. Then, hopefully the files size will change.
If the case where you may run makepp several times a second is a problem for you, you may find that using the md5 method is somewhat more reliable. If makepp builds a file, it flushes its cached MD5 signatures even if the files date hasnt changed.
For efficiencys sake, makepp wont reread the file and recompute the complex signatures below if this plain signature hasnt changed since the last time it computed it. This can theoretically cause a problem, since its possible to change the files contents without changing its date and size. In practice, this is quite hard to do so its not a serious danger. In the future, as more filesystems switch to timestamps of under a second, hopefully Perl will give us access to this info, making this failsafe.
This is the method for input files to C like compilers, if your Perl supports
MD5 (only optionally available up to 5.6.2). It checks if a files name looks
like C or C++ source code, including things like Corba IDL. If it does, this
method applies. If it doesnt, it falls back to plain signatures for binary
files (determined by name or else by content) and else to md5. Alas you
can currently tune what is to be considered C or binary only by subclassing
Mpp::Signature::c_compilation_md5 to get a new signature type and there
overriding or extending the methods recognizes_file and excludes_file.
The idea is to be independent of formatting changes. This is done by pulling everything up as far as possible, and by eliminating insignificant spaces. Words are exempt from pulling up, since they might be macros containing __LINE__, so they remain on the line where they were.
is treated as though it were
That way you can reindent your code or add or change comments without triggering a rebuild, so long as you dont change the line numbers. (This signature method recompiles if line numbers have changed because that causes calls to __LINE__ and most debugging information to change.) It also ignores whitespace and comments after the last token. This is useful for preventing a useless rebuild if your VC adds lines at a $Log$ tag when checking in.
This method is particularly useful for the following situations:
This is the default method, if your Perl supports MD5 (optionally available up
to 5.6.2). Computes an MD5 checksum of the files contents, rather than
looking at the files date or size. This means that if you change the date on
the file but dont change its contents, makepp wont try to rebuild anything
that depends on it.
This is particularly useful if you have some file which is often regenerated during the build process that other files depend on, but which usually doesnt actually change. If you use the md5 signature checking method, makepp will realize that the files contents havent changed even if the files date has changed. (Of course, this wont help if the files have a timestamp written inside of them, as archive files do for example.)
This method only works if you have the utility nm in your path, and it
accepts the -P option to output Posix format. In that case only the names
and types of symbols in dynamically loaded libraries become part of their
signature. The result is that you can change the coding of functions without
having to relink the programs that use them.
In the following command the parser will detect an implicit dependency on $(LIBDIR)/libmylib.so, and build it if necessary. However the link command will only be reperformed whenever the library exports a different set of symbols:
This works as long as the functions interfaces dont change. But in that case youd change the declaration, so youd also need to change the callers.
Note that this method only applies to files whose name looks like a shared library. For all other files it falls back to c_compilation_md5, which may in turn fall back to others.
These are two similar methods which treat xml canonically and differ only in
their handling of whitespace. The first completely ignores it around tags and
considers it like a single space elsewhere, making the signature immune to
formatting changes. The second respects any whitespace in the xml, which is
necessary even if just a small part requires that, like a <pre> section
in an xhtml document.
Common to both methods is that they sign the essence of each xml document. Presence or not of a BOM or <?xml?> header is ignored. Comments are ignored, as is whether text is protected as CDATA or with entities. Order and quoting style of attributes doesnt matter, nor does how you render empty tags.
For any file which is not valid xml, or if the Expat based XML::Parser or the XML::LibXML parser is not installed, this falls back to method md5. If you switch your Perl installation from one of the parsers to the others, makepp will think the files are different as soon as their timestamp changes. This is because the result of either parser is logically equivalent, but they produce different signatures. In the unlikely case that this is a problem, you can force use of only XML::LibXML by setting in Perl:
The C or c_compilation_md5 method has a built in list of suffixes it recognizes as being C or C-like. If it gets applied to other files it falls back to simpler signature methods. But many file types are syntactically close enough to C++ for this method to be useful. Close enough means C++ comment and string syntax and whitespace is meaningless except one space between words (and C++s problem cases - -, + +, / * and < <).
It (and its subclasses) can now easily be extended to other suffixes. Anyplace you can specify a signature you can now tack on one one of these syntaxes to make the method accept additional filenames:
C.suffix1,suffix2,suffix3 One or more comma-separated suffixes can be added to the method by a colon. For example C.ipp,tpp means that besides the built in suffixes it will also apply to files ending in .ipp or .tpp, which you might be using for the inline and template part of C++ headers. C.(suffix-regexp) This is like the previous, but instead of enumerating suffixes, you give a Perl regular expression to match the ones you want. The previous example would be C.(ipp|tpp) or C.([it]pp) in this syntax. C(regexp) Without a dot the Perl regular expression can match anywhere in the file name. If it includes a slash, it will be tried against the fully qualified filename. So if you have C++ style suffixless headers in a directory include, use C(/include/) as your signature method. However the above suffix example would be quite nasty this way, C(\.(?:ipp|tpp)$$) or C(\.[it]pp$$) because $ is the expansion character in makefiles.
Signature methods apply to all files of a rule. Now if you have a compiler that takes a C like source code and an XML configuration file youd either need a combined signature method that smartly handles both file types, or you must choose an existing method which will not know whether a change in the other file is significant.
In the future signature method configuration may be changed to filename-pattern, optionally per command.
You can, if you want, define your own methods for calculating file signatures and comparing them. You will need to write a Perl module to do this. Have a look at the comments in Mpp/Signature.pm in the distribution, and also at the existing signature algorithms in Mpp/Signature/*.pm for details.
Here are some cases where you might want a custom signature method:
o When you want all changes in a file to be ignored. Say you always want dateStamp.o to be a dependency (to force a rebuild), but you dont want to rebuild if only dateStamp.o has changed. You could define a signature method that inherits from c_compilation_md5 that recognizes the dateStamp.o file by its name, and always returns a constant value for that file. o When you want to ignore part of a file. Suppose that you have a program that generates a file that has a date stamp in it, but you dont want to recompile if only the date stamp has changed. Just define a signature method similar to c_compilation_md5 that understands your file format and skips the parts you dont want to take into account.
|perl v5.20.3||MAKEPP_SIGNATURES (1)||2012-02-07|