blib/lib/App/HashMake.pm

filter: Statementstmt 19.7% 29 / 147 Branchbran 0.0% 0 / 52 Conditioncond 0.0% 0 / 15 MC/DCmcdc 0.0% 0 / 9 Subroutinesub 66.6% 8 / 12 Podpod 100% 4 / 4 totaltotal 17.1% 41 / 239 CC 36 SCAR 68.0
CC
36
Cov
14%
run
1199.4
dbg
6.0
msg
2.0
CRAP 893.7
↑ Summary
1 package App::HashMake;
2  
3 1 ▶use 5.008003;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 1 ▶use Env qw(HASH_MAKEFILE);
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 1 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use Digest::MD5;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 1 ▶use autodie;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 =head1 NAME
15  
16 App::HashMake - Perform make-like actions based on target file's MD5 hash value
17  
18 =head1 VERSION
19  
20 Version 0.01
21  
22 =cut
23  
24 1 our $VERSION = '0.01';
25  
26 1 our $default_hash_makefile = 'Hash.Makefile';
27 1 our $index_file = '.hash_index';
28  
29 =head1 SYNOPSIS
30  
31 This module executes the logic of hashmake, based on the input arguments.
32 Hashmake operates just like make(1), except it looks at the MD5 hash value of a
33 target file, using a hidden file (.hash_index) to store and check these hash
34 values for each target. If the hash value of a file has changed, the action is
35 executed.
36  
37 Instead of Makefile, hashmake looks for Hash.Makefile to decide what to do.
38 An alternative makefile can be provided using the -f argument.
39  
40 The hash values are stored in a hidden file called .hash_index, located in the
41 same directory as the makefile. The caller can also provide an alternate
42 working directory if the target directory's not writable.
43  
44 A sample Hash.Makefile could look like this:
45  
46 foo.txt
47 echo "I found foo!"
48  
49 When hashmake is run for the first time, no MD5 is known for this file, so the
50 action is completed, and the MD5 hash value for the file is stored. Running the
51 same command a moment later will do nothing, since the MD5 of the file hasn't
52 changed.
53  
54 Here's an example of how it would be called from the command line.
55  
56 $ hashmake
57 (Hashmake does it's thing with the default build file Hash.Makefile)
58 $ hashmake -d
59 (Hashmake dumps all of the current settings.)
60 $
61  
62 The variable $@ in a Hash.Makefile line will be replaced with the target. So
63 the Hash.Makefile line
64  
65 foo.txt bar.txt
66 echo "Found $@"
67  
68 should produce output like this:
69  
70 echo foo.txt
71 echo bar.txt
72  
73 If both of the files had no MD5s or different MD5s.
74  
75 =head1 ARGUMENTS
76  
77 -B Force rebuild / ignores the 'has it changed' element and just rebuild
78 everything.
79  
80 -d Debug / This outputs useful information about what steps are being
81 taken during processing.
82  
83 -f FILE
84 Specify the hash makefile if the standard Hash.Makefile is not being
85 used. The environment variable HASH_MAKEFILE can also be used for
86 this.
87  
88 -h Display information on the command line arguments.
89  
90 -n Print only / This just prints out what commands would have been run.
91  
92 -s Silent / Don't output anything that would normally be output. Error
93 messages are still output.
94  
95 -t Touch only / Mark all targets as being the latest.
96  
97 -v Display version information.
98  
99 -y DIR
100 Specify a work directory for the index file if the hash makefile's
101 directory is not writable.
102  
103 =head1 SUBROUTINES/METHODS
104  
105 =head2 run
106  
107 Run the make procedure. Returns the exit status, along with the output from
108 STDOUT and STDERR. Called from the hashmake executable.
109  
110 =cut
111  
112 1 our $verb = 1; # Verbosity. 0 - quiet, 1 - normal, 2 - debug.
113 1 our ( @out, @err ); # Output and Error lists to be returned to caller.
114  
115 sub run
116 0 ▶{
Subroutine run: not called CC=35 SCAR=70.9
Pod documented
117 0 my ( $args ) = @_;
118  
119 0 ▶ my $debug = exists $args->{d} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $args->{'d'} ? : 0 0 0
120 0 ▶ my $print_only = exists $args->{n} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $args->{'n'} ? : 0 0 0
121 my $makefile = exists $args->{f} ?
122 0 ▶ $args->{f} : ( $HASH_MAKEFILE // $default_hash_makefile );
Branch: 1 branch
BranchTrueFalseTotal
exists $args->{'f'} ? : 0 0 0
Condition0%0/3
$App::HashMake::HASH_MAKEFILE // $App::HashMake::default_hash_makefile
l!l&&r!l&&!r
000
MC/DC0%0/2
$App::HashMake::HASH_MAKEFILE // $App::HashMake::default_hash_makefile
$App::HashMake::HASH_MAKEFILE $App::HashMake::default_hash_makefile
Truth table0%0/3
A // B
A= $App::HashMake::HASH_MAKEFILEB= $App::HashMake::default_hash_makefile
ABresult
1X1
011
000
123 0 my $work_dir = $args->{y};
124 0 ▶ my $force_rebuild = exists $args->{B} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $args->{'B'} ? : 0 0 0
125 0 ▶ my $touch_only = exists $args->{t} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $args->{'t'} ? : 0 0 0
126  
127 0 my $something = 0; # Signals if we did (our would have done) something.
128  
129 0 ▶ if ($debug) {
Branch: 1 branch
BranchTrueFalseTotal
if ($debug) 0 0 0
130  
131 0 my @output;
132 0 $verb++;
133  
134 0 my @opts = (
135 { name => 'debug', value => $debug },
136 { name => 'print_only', value => $print_only },
137 { name => 'makefile', value => $makefile },
138 { name => 'force_rebuild', value => $force_rebuild },
139 { name => 'touch_only', value => $touch_only },
140 );
141  
142 push ( @output, "Settings:",
143 0 ( map { "--> $_->{ name }: $_->{ value }" } @opts ) );
144  
145 0 ▶ if ( defined $work_dir ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $work_dir) 0 0 0
146  
147 0 push( @output, "--> working_dir: $work_dir" );
148 }
149 0 msg ( @output );
150 }
151  
152 0 ▶ if ( ! -e $makefile ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $makefile) 0 0 0
153  
154 0 err ( "$0: ERROR: Makefile $makefile not found, done." );
155  
156 0 return ( $something, { out => \@out, err => \@err } );
157 }
158  
159 # The file we're versioning may be in a directory that we can't write to,
160 # so the caller will have set up a working directory for us to use
161 # instead.
162  
163 0 my ( $vol, $dir, $file );
164 0 ▶ if ( defined $work_dir ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $work_dir) { } 0 0 0
165  
166 # Check that this directory exists.
167  
168 0 ▶ if ( ! -e $work_dir ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $work_dir) 0 0 0
169  
170 0 err ( "$work_dir doesn't exist" );
171 0 return ( $something, { out => \@out, err => \@err } );
172 }
173  
174 0 $dir = $work_dir;
175  
176 } else {
177  
178 # OK, at this point we do have a makefile, so we need to locate the index
179 # file, which should be in the same directory. If it's there, we'll load
180 # up the hash values.
181  
182 0 ( $vol, $dir, $file ) = File::Spec->splitpath ( $makefile );
183  
184 }
185 0 ▶ if ( $dir eq '' ) { $dir = '.'; }
Branch: 1 branch
BranchTrueFalseTotal
if ($dir eq "") 0 0 0
186  
187 0 my $full_index_file = File::Spec->catfile ( $dir, $index_file );
188  
189 # Let's check that we can write to this directory -- if not, exit with an
190 # error.
191  
192 0 ▶ if ( length $dir && ! -w $dir ) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $dir and not -w $dir) 0 0 0
Condition0%0/3
length $dir and not -w $dir
!ll&&!rl&&r
000
MC/DC0%0/2
length $dir and not -w $dir
length $dir not -w $dir
Truth table0%0/3
A and not(B)
A= length $dirB= not -w $dir
ABresult
0X0
100
111
193  
194 0 err ( "$0: $dir is not writable" );
195  
196 0 return ( $something, { out => \@out, err => \@err } );
197 }
198  
199 # OK, we've dealt with all of the input parameters, and now we're ready to
200 # start actually doing The Thing.
201  
202 0 my %hash_values = ();
203  
204 # If the force_rebuild flag is set, it doesn't matter if the index file
205 # exists, because we're going to act like it's not there.
206  
207 0 ▶ if ( ! $force_rebuild && -e $full_index_file ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $force_rebuild and -e $full_index_file) 0 0 0
Condition0%0/3
not $force_rebuild and -e $full_index_file
!ll&&!rl&&r
000
MC/DC0%0/2
not $force_rebuild and -e $full_index_file
not $force_rebuild -e $full_index_file
Truth table0%0/3
not(A) and B
A= not $force_rebuildB= -e $full_index_file
ABresult
0X0
100
111
208  
209 0 dbg ( "Reading index file $full_index_file" );
210  
211 0 open ( my $fh, '<', $full_index_file );
212 0 ▶ while ( <$fh> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 0 0 0
213  
214 # Ths file format is going to be filename, followed by at least one
215 # space, followed by the hash value (shown as an MD5 here). This will
216 # allow us to handle files with embedded spaces. I hope. This file is
217 # going to be a data file only, and will not have comments.
218  
219 0 my ( $target, $md5 ) = /^(.+)\s+(.+)$/;
220 0 $hash_values{ $target } = $md5;
221 }
222 0 close ( $fh );
223 }
224  
225 # Read the makefile, so that we can undeerstand the targets.
226  
227 0 dbg ( "Reading makefile $makefile" );
228  
229 0 open ( my $fh, '<', $makefile );
230 0 my ( %config, %targets );
231  
232 0 undef %targets;
233  
234 0 ▶ while ( <$fh> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 0 0 0
235  
236 0 ▶ next if ( /^#/ ); # Skip comments
Branch: 1 branch
BranchTrueFalseTotal
if /^#/ 0 0 0
237  
238 0 my $line = $_;
239 0 ▶ if ( $line =~ /^\s+$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s+$/) 0 0 0
240  
241 # Blank line means we're doing with this target's commands if we had a
242 # target to begin with.
243  
244 0 undef %targets;
245 0 next;
246 }
247
248 # Strip leading spaces and trailing new lines.
249  
250 0 $line =~ s/^\s+x$//;
251 0 $line =~ s/\s+$//;
252  
253 0 ▶ if ( keys %targets ) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %targets) { } 0 0 0
254  
255 # We have targets, so this is a command line for them.
256  
257 0 foreach my $k ( keys %targets ) {
258  
259 0 push ( @{ $config{ $k } }, $line );
260 }
261  
262 } else {
263  
264 # Allow a list of targets.
265  
266 0 undef %targets;
267 0 my @targets;
268 0 my @words = split ( /\s/, $line );
269  
270 0 foreach my $w ( @words ) {
271  
272 # If there are wild-card characters, glob will fetch the possible
273 # file names. If not, not.
274  
275 0 ▶ push ( @targets, glob ( $w ) );
Subroutine BEGIN: called CC=1 SCAR=0.2
276 }
277  
278 0 @config{ @targets } = (); # No commands for these targets yet.
279 0 @targets{ @targets } = undef;
280 }
281 }
282 0 close ( $fh );
283  
284 0 dbg ( "Targets found are: " . join ( '/', keys %config ) );
285  
286 # Nothing actionable in the makefile? Get out.
287  
288 0 ▶ if ( !keys %config ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (keys %config) 0 0 0
289  
290 0 msg ( "$0: WARN: No targets found, done." );
291 0 return ( $something, { out => \@out, err => \@err } );
292 }
293  
294 # Now it's time to check out each target. At this point, we're going to be
295 # checking them in heap order (so, random). I assume that's going to be
296 # fine.
297  
298 0 dbg ( "Checking targets" );
299  
300 0 my $action_count = 0;
301 0 foreach my $t ( keys %config ) {
302  
303 0 dbg ( "Checking target $t" );
304  
305 # Find the MD5 of the target, and see if our value matches the one from
306 # the index file.
307  
308 0 ▶ if ( ! -e $t ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $t) 0 0 0
309  
310 0 msg ( "$0: WARN: Target $t does not exist." );
311 0 next;
312 }
313  
314 0 my %digests;
315  
316 0 open ( my $fh, '<', $t );
317 0 my $md5 = Digest::MD5->new;
318 0 $md5->addfile ( $fh );
319 0 close ( $fh );
320  
321 0 my $digest = $md5->hexdigest;
322 0 my $action = 0; # No action yet;
323  
324 # If this is a forced rebuild -- we have to do the action OR If a key
325 # does exist, but it doesn't match the current value -- we have to do
326 # the action. Otherwise -- the key exists and matches, and there's no
327 # action.
328  
329 0 ▶ if ( !$force_rebuild &&
Branch: 1 branch
BranchTrueFalseTotal
if (not $force_rebuild and (exists $hash_values{$t} and $hash_values{$t} eq $digest)) { } 0 0 0
Condition0%0/6
not $force_rebuild and (exists $hash_values{$t} and $hash_values{$t} eq $digest)
!ll&&!rl&&r
000
exists $hash_values{$t} and $hash_values{$t} eq $digest
!ll&&!rl&&r
000
MC/DC0%0/3
not $force_rebuild and (exists $hash_values{$t} and $hash_values{$t} eq $digest)
not $force_rebuild exists $hash_values{$t} $hash_values{$t} eq $digest
Truth table0%0/4
not(A) and B and C
A= not $force_rebuildB= exists $hash_values{$t}C= $hash_values{$t} eq $digest
ABCresult
0XX0
10X0
1100
1111
330 ( exists $hash_values{ $t } && $hash_values{ $t } eq $digest ) ) {
331  
332 0 dbg ( "Key up to date for $t -- no action" );
333  
334 } else {
335  
336 0 $action = 1;
337 0 $hash_values{ $t } = $digest;
338  
339 0 dbg ( "Target $t needs action" );
340 }
341  
342 # If we're going to do the actions, this is where it happens. Later,
343 # we update the index file before we exit.
344  
345 0 ▶ if ( $action ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($action) { } 0 0 0
346  
347 # See if the magic variable $@ is on any of the lines -- and if so,
348 # replace it with the current target.
349  
350 0 my @cmds = map { s/\$\@/$t/ge; $_ } @{ $config{ $t } };
351  
352 0 ▶ if ( $print_only ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($print_only) { } 0 0 0
353  
354 0 msg ( map { "Would run this --> $_" } @cmds );
355  
356 } else {
357  
358 # Unless it's a touch only situation, run the commands.
359  
360 0 ▶ if ( !$touch_only ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($touch_only) 0 0 0
361  
362 0 foreach my $cmd ( @cmds ) {
363  
364 0 system ( $cmd ); # Run the command. Yikes.
365 }
366 }
367 0 $action_count++;
368 }
369 0 $something = 1; # Whether we actually did anything or not.
370  
371 } else {
372  
373 0 dbg ( "Nothing to do for the target $t." );
374 }
375 }
376  
377 0 ▶ if ( $action_count ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($action_count) 0 0 0
378  
379 # We did some actions, time to update the index.
380  
381 0 open ( my $fh, '>', $full_index_file );
382 print $fh join ( "\n",
383 0 map { "$_ $hash_values{ $_ }" } keys %hash_values ) . "\n";
384 0 close ( $fh );
385  
386 0 dbg ( "Updated full_index file $full_index_file." );
387 0 dbg ( "--> keys updated: " . join ( '/', keys %hash_values ) );
388 }
389 0 return ( $something, { out => \@out, err => \@err } );
390 }
391  
392 =head2 dbg
393  
394 Internal routine:
395 Debug messages are output when the verbosity level is 2.
396  
397 =cut
398  
399 sub dbg
400 0 ▶{
Subroutine dbg: not called CC=2 SCAR=17.9
Pod documented
401 0 my ( @msg ) = @_;
402  
403 0 ▶ if ( $verb > 1 ) { push ( @out, @msg ); }
Branch: 1 branch
BranchTrueFalseTotal
if ($App::HashMake::verb > 1) 0 0 0
404 }
405  
406 =head2 msg
407  
408 Internal routine:
409 Regular messages are output when the verbosity level is 1.
410  
411 =cut
412  
413 sub msg
414 0 ▶{
Subroutine msg: not called CC=1 SCAR=6.9
Pod documented
415 0 my ( @msg ) = @_;
416  
417 0 push ( @out, @msg );
418 }
419  
420 =head2 err
421  
422 Internal routine:
423 Error messages always get output.
424  
425 =cut
426  
427 sub err
428 0 ▶{
Subroutine err: not called CC=1 SCAR=6.9
Pod documented
429 0 my ( @msg ) = @_;
430  
431 0 push ( @err, @msg );
432 }
433  
434 =head1 AUTHOR
435  
436 T. Alex Beamish <talexb@gmail.com>
437  
438 =head1 BUGS
439  
440 Please report any bugs or feature requests to C<bug-app-hashmake at rt.cpan.org>, or through
441 the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-HashMake>. I will be notified, and then you'll
442 automatically be notified of progress on your bug as I make changes.
443  
444  
445  
446  
447 =head1 SUPPORT
448  
449 You can find documentation for this module with the perldoc command.
450  
451 perldoc App::HashMake
452  
453  
454 You can also look for information at:
455  
456 =over 4
457  
458 =item * RT: CPAN's request tracker (report bugs here)
459  
460 L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=App-HashMake>
461  
462 =item * GitHub issue tracker
463  
464 L<https://github.com/talexb/App-HashMake/issues>
465  
466 =item * Search CPAN
467  
468 L<https://metacpan.org/release/App-HashMake>
469  
470 =back
471  
472  
473 =head1 ACKNOWLEDGEMENTS
474  
475  
476 =head1 LICENSE AND COPYRIGHT
477  
478 This software is Copyright (c) 2026 by T. Alex Beamish <talexb@gmail.com>.
479  
480 This is free software, licensed under:
481  
482 The Artistic License 2.0 (GPL Compatible)
483  
484  
485 =cut
486  
487 1 1; # End of App::HashMake
↑ Summary