Daniel Pfeiffer > makepp > Mpp::FileOpt

Download:
makepp-2.0.98.2.tgz

Annotate this POD

CPAN RT

New  3
Open  1
View/Report Bugs
Source   Latest Release: makepp-2.0.98.5

NAME ^

Mpp::FileOpt -- optional subs to complement Mpp::File

DESCRIPTION ^

This file defines some additional subroutines for the Mpp::File package that are useful only within makepp. This allows Mpp/File.pm to be used outside of makepp itself.

build_info_string

  my $string = build_info_string($finfo,'key');
  my @strings = build_info_string($finfo,qw'key1 key2 ...');

Returns information about this file which was saved on the last build. This information is stored in a separate file, and is automatically invalidated if the file it refers to has changed. It is intended for remembering things like the command used to build the file when it was last built, or the signatures of the dependencies.

See also: set_build_info_string

get_rule

  my $rule = get_rule( $finfo, $no_last_chance );

Returns the rule to build the file, if there is one, or undef if there is none. If $no_last_chance is set, then don't consider last chance rules or autoloads.

exists_or_can_be_built

exists_or_can_be_built_or_remove

  if (exists_or_can_be_built( $finfo )) { ... }

Returns true (actually, returns the Mpp::File structure) if the file exists and is readable, or does not yet exist but can be built. This function determines whether a file exists by checking the build signature, not by actually looking in the file system, so if you set up a signature function that can return a valid build signature for a pseudofile (like a dataset inside an HDF file or a member of an archive) then this function will return true.

If this is not what you want, then consider the function file_exists(), which looks in the file system to see whether the file exists or not.

The ..._or_remove variant removes the file if $Mpp::rm_stale_files is set and the file is stale. You shouldn't call this unless you're confident that the file's rule will not be learned later, but it's exactly what you need for scanners, because if you don't remove stale files from the search path, then they'll get picked up erroneously (by the command itself, but usually *not* by the scanner) when they are in front of the file's new directory.

Optimization: The results of exists_or_can_be_built_norecurse (and hence exists_or_can_be_built) are cached in EXISTS_OR_CAN_BE_BUILT. But, since this function used to get called an obscene number of times, they don't themselves check the cache, instead providing it to its potential caller.

name

  $string = $finfo->name;

Returns the absolute name of the file. Note: other classes have this method too, so when you're not sure you have a Mpp::File, better use method syntax.

set_additional_dependencies

  set_additional_dependencies($finfo,$dependency_string, $makefile, $makefile_line);

Indicates that the list of objects in $dependency_string are extra dependencies of the file. These dependencies are appended to the list of dependencies from the rule to build the file. $makefile and $makefile_line are used only when we have to expand the list of dependencies. We can't do this until we actually need to make the file, because we might not be able to expand wildcards or other things properly.

set_build_info_string

  set_build_info_string($finfo, $key, $value, $key, $value, ...);

Sets the build info string for the given key(s). This can be read back in later or on a subsequent build by build_info_string().

You should call update_build_infos() to flush the build information to disk, or else it will never be stored. It's a good idea to call update_build_infos() fairly frequently, so that nothing is lost in the case of a machine crash or someone killing your program.

mark_build_info_for_update

  mark_build_info_for_update( $finfo );

Marks this build info for update the next time an update is done. You only need to call this if you modify the BUILD_INFO hash directly; if you call set_build_info_string, it's already handled for you.

clear_build_info

  clear_build_info( $finfo );

Clears the build info strings for all keys. The principal reason to do this would be that the file is about to be regenerated.

set_rule

  set_rule($finfo, $rule);

Sets a rule for building the specified file. If there is already a rule, which rule overrides is determined by the following procedure:

  1. A rule that recursively invokes make never overrides any other rule. This is a hack necessary to deal with some legacy makefiles which have rules for targets that actually invoke the proper rule in some other makefile, something which is no longer necessary with makepp.
  2. If either rule is an explicit rule, and not a pattern rule or a backward inference rule, then the explicit rule is used. If both rules are explicit rules, then this is an error.

    Note that a pattern rule which is specified like this:

      %.o: %.c : foreach abc.c def.c ghi.c

    where no wildcards are involved is treated as an explicit rule for abc.o, def.o, and ghi.o.

  3. A pattern rule overrides a backward inference rule. (This should never happen, since backward inference rules should only be generated if no pattern rule exists.)
  4. A pattern rule from a "nearer" makefile overrides one from a "farther" makefile. Nearness is determined by the length of the relative file name of the target compared to the makefile's cwd.
  5. A pattern rule seen later overrides one seen earlier. Thus more specific pattern rules should be placed after the more general pattern rules.
  6. A builtin rule is always overridden by any other kind of rule, and never overrides anything.

signature

   $str = signature( $fileinfo )

Returns a signature for this file that can be used to know when the file has changed. The signature consists of the file modification time and the file size concatenated.

Returns undef if the file doesn't exist.

This signature is used for several purposes:

update_build_infos

  Mpp::File::update_build_infos();

Flushes our cache of build information to disk. You should call this fairly frequently, or else if the machine crashes or some other bad thing happens, some build information may be lost.

was_built_by_makepp

   $built = was_built_by_makepp( $fileinfo );

Returns TRUE iff the file was put there by makepp and not since modified.

is_stale

   $stale = is_stale( $fileinfo );

Returns TRUE iff the file was put there by makepp and not since modified, but now there is no rule for it, or it is not from a repository and the only rule for it is to get it from a repository.

assume_unchanged

Returns TRUE iff the file or directory is assumed to be unchanged. A file or directory is assumed to be unchanged if any of its ancestor directories are assumed unchanged.

dont_build

Returns TRUE iff the file or directory is marked for don't build. A file or directory is treated as marked for don't build if any of its ancestor directories are so marked and the youngest such ancestor is not older than the youngest ancestor that is marked for do build.

in_sandbox

Returns TRUE iff the file or directory is marked for in-sandbox (or if sandboxing isn't enabled). A file or directory is treated as marked for in-sandbox if any of its ancestor directories are so marked and the youngest such ancestor is not older than the youngest ancestor that is marked for out-of-sandbox.

dont_read

Returns TRUE iff the file or directory is marked for don't read. A file or directory is treated as marked for don't read if any of its ancestor directories are so marked and the youngest such ancestor is not older than the youngest ancestor that is marked for do read.

syntax highlighting: