lib/App/FatPacker/Trace.pm

   1 package App::FatPacker::Trace;
   2
   3 use strict;
   4 use warnings FATAL => 'all';
   5 use B ();
   6
   7 my $trace_file;
   8 my %initial_inc;
   9
  10 sub import {
  11   my (undef, $file, @extras) = @_;
  12
  13   $trace_file = $file || '>>fatpacker.trace';
  14   # For filtering out our own deps later.
  15   # (Not strictly required as these are core only and won't have packlists, but
  16   # looks neater.)
  17   %initial_inc = %INC;
  18
  19   # Use any extra modules specified
  20   eval "use $_" for @extras;
  21
  22   B::minus_c;
  23 }
  24
  25 CHECK {
  26   return unless $trace_file; # not imported
  27
  28   open my $trace, $trace_file
  29       or die "Couldn't open $trace_file to trace to: $!";
  30
  31   for my $inc (keys %INC) {
  32     next if exists $initial_inc{$inc};
  33     print $trace "$inc\n";
  34   }
  35 }
  36
  37 1;
  38
  39 __END__
  40
  41 =head1 NAME
  42
  43 App::FatPacker::Trace - Tracing module usage using compilation checking
  44
  45 =head1 SYNOPSIS
  46
  47     # open STDERR for writing
  48     # will be like: open my $fh, '>', '&STDERR'...
  49     perl -MApp::FatPacker::Trace=>&STDERR myscript.pl
  50
  51     # open a file for writing
  52     # will be like: open my $fh, '>>', 'fatpacker.trace'
  53     perl -MApp::FatPacker::Trace=>>fatpacker.trace myscript.pl
  54
  55 =head1 DESCRIPTION
  56
  57 This module allows tracing the modules being used by your code. It does that
  58 using clever trickery using the C<import> method, the C<CHECK> block and
  59 L<B>'s C<minus_c> function.
  60
  61 When App::FatPacker::Trace is being used, the import() method will call
  62 C<B::minus_c> in order to set up the global compilation-only flag perl
  63 (the interpreter) has. This will prevent any other code from being run.
  64
  65 Then in the C<CHECK> block which is reached at the end of the compilation
  66 phase (see L<perlmod>), it will gather all modules that have been loaded,
  67 using C<%INC>, and will write it to a file or to STDERR, determined by
  68 parameters sent to the C<import> method.
  69
  70 =head1 METHODS
  71
  72 =head2 import
  73
  74 This method gets run when you just load L<App::FatPacker::Trace>. It will
  75 note the current C<%INC> and will set up the output to be written to, and
  76 raise the compilation-only flag, which will prevent anything from being
  77 run past that point. This flag cannot be unset, so this is most easily run
  78 from the command line as such:
  79
  80     perl -MApp::FatPacker::Trace [...]
  81
  82 You can control the parameters to the import using an equal sign, as such:
  83
  84     # send the parameter "hello"
  85     perl -MApp::FatPacker::Trace=hello [...]
  86
  87     # send the parameter ">&STDERR"
  88     perl -MApp::FatPacker::Trace=>&STDERR [...]
  89
  90 The import method accepts a first parameter telling it which output to open
  91 and how. These are both sent in a single parameter.
  92
  93     # append to mytrace.txt
  94     perl -MApp::FatPacker::Trace=>>mytrace.txt myscript.pl
  95
  96     # write to STDERR
  97     perl -MApp::FatPacker::Trace=>&STDERR myscript.pl
  98
  99 The import method accepts additional parameters of extra modules to load.
 100 It will then add these modules to the trace. This is helpful if you want
 101 to explicitly indicate additional modules to trace, even if they aren't
 102 used in your script. Perhaps you're conditionally using them, perhaps
 103 they're for additional features, perhaps they're loaded lazily, whatever
 104 the reason.
 105
 106     # Add Moo to the trace, even if you don't trace it in myscript.pl
 107     perl -MApp::FatPacker::Trace=>&STDERR,Moo myscript.pl
 108