Commit | Line | Data |
48af1939 |
1 | package App::FatPacker::Trace; |
2 | |
3 | use strict; |
4 | use warnings FATAL => 'all'; |
5 | use B (); |
6 | |
dc7a3a08 |
7 | my $trace_file; |
8 | my %initial_inc; |
9 | |
48af1939 |
10 | sub import { |
b079df6c |
11 | my (undef, $file, @extras) = @_; |
3fdf85ca |
12 | |
13 | $trace_file = $file || '>>fatpacker.trace'; |
dc7a3a08 |
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; |
3fdf85ca |
18 | |
19 | # Use any extra modules specified |
20 | eval "use $_" for @extras; |
21 | |
48af1939 |
22 | B::minus_c; |
23 | } |
24 | |
dc7a3a08 |
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 | |
b079df6c |
31 | for my $inc (keys %INC) { |
dc7a3a08 |
32 | next if exists $initial_inc{$inc}; |
33 | print $trace "$inc\n"; |
34 | } |
35 | } |
36 | |
48af1939 |
37 | 1; |
a64bd0c2 |
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 paramters 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 | |