From: Sawyer X <xsawyerx@cpan.org>
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?p=p5sagit%2FApp-FatPacker.git;a=commitdiff_plain;h=a64bd0c28e043ad407e97c04955f2ffd0d423181

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<import> method, the C<CHECK> block and
+L<B>'s C<minus_c> function.
+
+When App::FatPacker::Trace is being used, the import() method will call
+C<B::minus_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<CHECK> block which is reached at the end of the compilation
+phase (see L<perlmod>), 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<import> method.
+
+=head1 METHODS
+
+=head2 import
+
+This method gets run when you just load L<App::FatPacker::Trace>. 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
+