/ 
mpp-10
/ Rule

NAME

Rule -- Stores information about a build rule

USAGE

my $rule = new Rule "targets", "dependencies",
  "command"[, $makefile, $makefile_line];

DESCRIPTION

A rule object contains all the information necessary to make a specific file.

$makefile is a pointer to the structure returned by load_makefile. $makefile_line is an ASCII string that is used if an error message occurs while expanding variables in this rule.

This does not actually place the rule into the FileInfo hierarchy.

get_tagname

$real_tag = $rule->get_tagname($tag)

Returns a unique tag name for $tag. See "load_scaninfo".

Since a rule can have multiple commands with the same include tag, the requested tag might not match the actual tag that gets returned.

add_include_dir

$rule->add_include_dir($real_tag, $dirname);

Add an include directory for scanner caching. See "load_scaninfo".

$dirname is a name relative to build_cwd.

add_include_suffix

$rule->add_include_suffix($real_tag, $suffix);

Add an include suffix list for scanner caching. See "load_scaninfo".

add_meta_dependency

$rule->add_meta_dependency($real_tag, $src, $name, $finfo);

Add an include file for scanner caching. Return value is TRUE iff the meta dependency failed to build. See "load_scaninfo".

$name is the requested name relative to the directory named by $src (relative to the build directory). If $real_tag is undef, then it is treated as a path including only ".". $src is ignored if $name is an absolute path or none of the directories in the include path are undefined. If $src is undef, then the build directory is used.

The return value is zero on success (including if the file could not be found), nonzero on build failure.

add_implicit_dependency

$rule->add_implicit_dependency($real_tag, $src, $name, $finfo);

Add a dependency file for scanner caching. See "load_scaninfo".

This works just like add_meta_dependency, except that the rule doesn't have to be re-scanned by virtue of an implicit dependency being out of date.

add_implicit_target

$rule->add_implicit_target($name);

Add a target file for scanner caching. See "load_scaninfo".

add_implicit_env_dependency

$rule->add_implicit_env_dependency($name);

Add an environmental dependency for scanner caching. See "load_scaninfo".

set_signature_method_scanner

$rule->set_signature_method_scanner($name)

Like set_signature_method_default, except that it takes a class name instead of an object, and it caches how the signature method was set by a scanner.

mark_scaninfo_uncacheable

$rule->mark_scaninfo_uncacheable

Prohibit the rule from caching its scanner information. This is useful when the information gathered by one of the scanners that gets involved doesn't fit into the caching scheme, and that could cause build inaccuracies.

cache_scaninfo

$rule->cache_scaninfo(\@targets);

Set build_info_string's for scanner caching for each of @targets. See "load_scaninfo".

Once transferred to the build_info cache, the information is deleted from $rule, in order to save memory.

load_scaninfo

$rule->load_scaninfo($tinfo, $command_string, $explicit_dependencies);

Attempt to get all the scanned information about $rule from $tinfo's build info file. If this fails for whatever reason, including the scaninfo possibly being out of date, then the reason is returned, and $rule is left in its original state. This typically means that it must be re-scanned from scratch. Otherwise, 0 is returned.

$rule->execute($command_string, $all_targets, $all_dependencies)

$handle = $rule->execute($command_string, $all_targets, $all_dependencies);

Executes the given command string, and returns a handle for the executing process (which may not have finished by the time we return). The command string may contain several shell commands separated by newlines.

This is part of the Rule class so the default execute routine can be overridden. You can replace the execute routine with any complicated operation you want, provided it returns the appropriate kind of handles.

$rule->print_command

Print out a command instead of executing it. This is used only when we are running with -n (dry run mode).

$rule->append($rule)

Add the targets and commands from another rule to this rule. This is used only when parsing double colon rules like this:

clean::
    $(RM) *.o

# Later in the makefile:
clean::
    $(RM) y.tab.c y.tab.h

$rule->setup_environment()

Sets up the environment for the rule's makefile.

build_check_method

$rule->build_check_method;

Gets the build check method for this particular rule.

set_build_check_method

$rule->set_build_check_method(method);

Sets the build check method to be the given method.

set_build_check_method_default

$rule->set_build_check_method_default(method);

Sets the build check method, unless it has already been set.

$rule->signature_method

my $sig_method = $rule->signature_method;

Returns the signature method to use to calculate signatures for files.

The default method is the file time + file size (see Signature.pm for details).

set_signature_method

$rule->set_signature_method($sigmethod);

Sets the signature method to use for this particular rule.

$rule->scan_action

$rule->scan_action($action_string);

Scans the given actions, looking for additional dependencies (such as include files) or targets (such as .libs/xyz.lo) that weren't explicitly listed. Make variables in the action string have already been expanded.

Calls $rule->add_dependency for new dependencies, and $rule->add_target for new targets.

$rule->parser

$rule->parser()

Returns the rule scanner object, creating it if it doesn't already exist.

$rule->source

$source_string = $rule->source;

Returns a description of where this rule was encountered, suitable for error messages.