1# $Id: BuildCheck.pm,v 1.10 2012/03/04 13:56:35 pfeiffer Exp $ 2package Mpp::BuildCheck; 3 4=head1 NAME 5 6Mpp::BuildCheck -- Interface definition for various signature classes 7 8=head1 USAGE 9 10Derive a package from this package. 11 12=head1 DESCRIPTION 13 14The Mpp::BuildCheck package specifies how makepp uses the file signatures and other 15information in order to compute whether a file needs to be rebuilt or not. 16Each rule can have a different build check associated with it, if necessary. 17In the makefile, the signature class is specified by using the :build_check 18modifier, like this: 19 20 %.o : %.c 21 : build_check special_build 22 $(CC) $(CFLAGS) -c $(FIRST_DEPENDENCY) -o $(TARGET) 23 24This causes the signature class C<Mpp::BuildCheck::special_build> to be used for 25this particular rule. 26 27Only one object from each different buildcheck class is actually created; the 28object has no data, and its only purpose is to contain a blessed reference to 29the package that actually implements the functions. Each rule contains a 30reference to the build check object that is appropriate for it. The object is 31found by the name of the build check class. For example, the above rule uses 32the object referenced by C<$Mpp::BuildCheck::special_build::special_build>. (The 33purpose of this naming scheme is to make it impossible to inherit accidentally a 34singleton object, which would cause the wrong Mpp::Signature class to be used.) 35 36The build check class is independent of the signature class. In general, any 37signature method may be used with any build check. (An exception is the 38target_newer build check class, which by definition works only with file 39dates.) 40 41=head2 build_check 42 43 if ($build_check_method->build_check($tinfo, \@all_dependencies, 44 $build_command, $build_cwd, $signature_method, \%env)) { 45 ... 46 } 47 48Returns undef if the given target does not need rebuilding, or the true 49if a rebuild is needed. 50If the I<only> reason a rebuild is needed is that dependencies are changed, 51then the special value "DEPENDENCIES" should be returned, as this permits 52optimizations related to scanning. 53 54$tinfo is the Mpp::File structure for one of the targets that this rule 55can make. build_check should be called for each target. 56 57@all_dependencies is an array that contains all dependencies (including ones 58that we detected automatically, such as include files). The dependencies 59should already have been built. The list should be sorted in the final 60order we'll put them into the build information, and duplicates should be 61removed. 62 63$build_command is the command string that we are going to execute (after 64all variables have been expanded) if any files are out of date. 65 66$build_cwd is the directory that the command should be executed in if it 67needs to be executed. 68 69$signature_method is a reference to the Mpp::Signature class object that should be 70used to compute signatures. See F<Mpp/Signature.pm> for details. 71 72%env is a hash mapping names of environment variables which affect the 73target to values. If the name is of the form /(.+) in (\S+)/, then $1 is 74taken as a filename to search for in the value of the environment variable 75named by $2 (directories separated by colons), and the value is the name of 76the first directory in which it is found. 77 78The build_check subroutine should pay attention to the ASSUME_CHANGED and 79ASSUME_UNCHANGED members of the Mpp::File structure. Implemented by classes 80which inherit from this. 81 82=head2 build_check_from_build_info($build_info_hash, \@all_dependencies, 83 $build_command, $build_cwd, 84 $signature_method, \%env) 85 86 if ($build_check_method->build_check_from_build_info($bc_entry, 87 \@all_dependencies, $build_command, $build_cwd, 88 $signature_method, \%env)) { 89 ... 90 } 91 92This subroutine does exactly the same thing as C<build_check()> except that it 93accepts either a repository entry or a build cache entry. It may only look at 94the build info (the stuff that's stored in the .makepp file) to see if the 95file can be used. Since the $bc_entry argument may be either a build cache 96entry or a fileinfo describing a file in the repository, you should access the 97build info by calling 98C<<$bc_entry->build_info_string("BUILD_INFO_ENTRY_NAME")>>. You should not call 99any other methods of the object. Implemented by classes which inherit from this. 100 101=head2 changed_dependencies 102 103 @changed_files = $sigobj-> 104 changed_dependencies($tinfo, $signature_method, $build_cwd, 105 @all_dependencies); 106 107Returns a list of the dependencies which have been changed since the last time 108the target was updated. "Changed" means changed so that the signature method 109cares. For example, if your signature method simply compares the dates to see 110if any of the dependencies are newer (the C<target_newer> method), then this 111is a list of dependencies whose file date is newer than the target. 112 113This is only used to avoid rescanning for include files unnecessarily, and 114also for the $(changed_inputs) variable. It is not used for the decision of 115whether to build a file. 116 117=cut 118 119sub changed_dependencies { 120 return @_[3 .. $#_]; # You'll want to override this.... 121} 122 123=head2 build_cache_key 124 125 $build_cache_key = $self->build_cache_key($tinfo, \@all_dependencies, 126 $build_command, $build_cwd, 127 $signature_method, \%env); 128 129Returns a key for looking up this target in the build cache. The arguments 130are the same as for C<build_check>. 131 132If undef is returned, then we do not look at the file in the build cache. 133This is the default behavior; you must override it if you want to enable the 134build cache. 135 136NOTE: Build cache key equality must imply substitutability (barring a 137vanishingly improbable event such as an accidental MD5 alias), because we 138don't do a build_check after getting a cache hit. In addition to improving 139efficiency, this is necessary to combat the fact that it is impossible to 140guarantee that a build cache target and its build info actually go together 141when the build cache is on an NFS volume. 142 143=cut 144 145sub build_cache_key { 146 return undef; # Disables the build cache. 147} 148 149=head2 update_dep_sigs 150 151 $self->update_dep_sigs($tinfo, $rule); 152 153If build_cache_key returns a defined value, then this is called after 154importing from the build cache to make the DEP_SIGS in the target's build info 155match the signatures of its dependencies (rather than that of the dependencies 156in the build cache), so that its build check will pass on the next makepp run 157unless something has actually changed. Implemented by classes which inherit 158from this. 159 160=cut 161 1621; 163