From: Sawyer X Date: Thu, 23 Feb 2012 12:18:43 +0000 (+0200) Subject: document ::Trace thoroughly X-Git-Tag: v0.9.7~13 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=a64bd0c28e043ad407e97c04955f2ffd0d423181;p=p5sagit%2FApp-FatPacker.git document ::Trace thoroughly --- diff --git a/lib/App/FatPacker/Trace.pm b/lib/App/FatPacker/Trace.pm index 28cde3a..526a318 100644 --- a/lib/App/FatPacker/Trace.pm +++ b/lib/App/FatPacker/Trace.pm @@ -35,3 +35,74 @@ CHECK { } 1; + +__END__ + +=head1 NAME + +App::FatPacker::Trace - Tracing module usage using compilation checking + +=head1 SYNOPSIS + + # open STDERR for writing + # will be like: open my $fh, '>', '&STDERR'... + perl -MApp::FatPacker::Trace=>&STDERR myscript.pl + + # open a file for writing + # will be like: open my $fh, '>>', 'fatpacker.trace' + perl -MApp::FatPacker::Trace=>>fatpacker.trace myscript.pl + +=head1 DESCRIPTION + +This module allows tracing the modules being used by your code. It does that +using clever trickery using the C method, the C block and +L's C function. + +When App::FatPacker::Trace is being used, the import() method will call +C in order to set up the global compilation-only flag perl +(the interpreter) has. This will prevent any other code from being run. + +Then in the C block which is reached at the end of the compilation +phase (see L), it will gather all modules that have been loaded, +using C<%INC>, and will write it to a file or to STDERR, determined by +parameters sent to the C method. + +=head1 METHODS + +=head2 import + +This method gets run when you just load L. It will +note the current C<%INC> and will set up the output to be written to, and +raise the compilation-only flag, which will prevent anything from being +run past that point. This flag cannot be unset, so this is most easily run +from the command line as such: + + perl -MApp::FatPacker::Trace [...] + +You can control the paramters to the import using an equal sign, as such: + + # send the parameter "hello" + perl -MApp::FatPacker::Trace=hello [...] + + # send the parameter ">&STDERR" + perl -MApp::FatPacker::Trace=>&STDERR [...] + +The import method accepts a first parameter telling it which output to open +and how. These are both sent in a single parameter. + + # append to mytrace.txt + perl -MApp::FatPacker::Trace=>>mytrace.txt myscript.pl + + # write to STDERR + perl -MApp::FatPacker::Trace=>&STDERR myscript.pl + +The import method accepts additional parameters of extra modules to load. +It will then add these modules to the trace. This is helpful if you want +to explicitly indicate additional modules to trace, even if they aren't +used in your script. Perhaps you're conditionally using them, perhaps +they're for additional features, perhaps they're loaded lazily, whatever +the reason. + + # Add Moo to the trace, even if you don't trace it in myscript.pl + perl -MApp::FatPacker::Trace=>&STDERR,Moo myscript.pl +