view release on metacpan or  search on metacpan

lib/Debuggit/Manual.pm  view on Meta::CPAN

=pod



=head1 NAME

Debuggit::Manual - Details for using Debuggit to the fullest



=head1 General Stuff


=head2 A Note on Documentation

You know, documentation is a double-edged sword.  Put too little, and no one will use your module
because it's poorly documented.  Put too much, and no one will use your module because it I<must> be
too complex ... I mean, just look at how much documentation it takes to describe it!

Well, it so happens that I actually I<like> writing documentation, so there's a healthy chunk of it
here.  But let me assure you that this is just because I'm being thorough, not because this module
is complex.  It's actually almost ridiculously simple at its core--in fact there's about 4 to 5
times more POD than code in this distro.

You should read this documentation in 3 stages:

=over 4

=item *

Start with the L</Quick Start> in the main L<Debuggit> POD.  After you get bored with how simple
Debuggit is to use like that, you may want to explore more options.

=item *

If you want some examples of cool things you can do with C<Debuggit>, take a look at
L<Debuggit::Cookbook>.

=item *

When you want more details on the nitty gritty of how C<Debuggit> actually works, come to this POD
(C<Debuggit::Manual>).  Think of this as a sort of a reference manual.

=back


=head2 A Note on Version Numbers

I know it's very fashionable to mark any module you put on CPAN for the first time as version
0.000000001, and then take about eight years before daring to release a 1.0.  However, this module
(in earlier incarnations) was used in production code for over 10 years before I put it on CPAN, so
I don't really think it makes much sense to call it 0.01.  I've chosen to start its CPAN life at
2.01, as this is its 3rd major rewrite.  If it makes you feel better, just subtract 2 from the
version number and you'll get a fairly accurate idea of its "true" CPAN version.  Just be aware that
it has had a pretty full life outside CPAN as well.

The Changes file details this life fairly accurately.  The version numbers are assigned using 20/20
hindsight, and I've filled in a few gaps in the historical notes, but all the dates and most of the
commit messages are fully accurate, thanks to the wonders of version control.



=head1 The DEBUG Constant

C<DEBUG> is a constant (similar to those defined with C<use constant>) which holds your current
debugging level.  Because it's implemented using constant folding, any conditional based on it will
actually be removed during compile-time if the debugging level isn't high enough (or turned off
completely).  For instance, this code:

    calculate_complex_stuff(1..10_000) if DEBUG >= 2;

would disappear entirely if C<DEBUG> is set to 0, or to 1.  Of course, being a constant has its own
foibles: you can't interpolate it into double-quoted strings, and you can't put it in front of a fat
comma.  See L<constant> for full details.


=head2 Setting DEBUG

You "set" C<DEBUG> when you use Debuggit:

    use Debuggit DEBUG => 2;

Once it's set, you can't change it.  You also can't set it from outside the code (like, from an
environment variable), but that's a feature I'd consider adding if people thought it was useful.

If you want your debugging turned off altogether, you can do this:

    use Debuggit DEBUG => 0;

Or you can do this:

    use Debuggit;

But there's a subtle difference between those last two.  In your top-level script, there's actually
no difference at all.  But in a module, not setting C<DEBUG> doesn't mean C<DEBUG> should be zero;
rather it means it should "inherit" the value of C<DEBUG> from the top-level script; or, to look at
it another way, the value of C<DEBUG> from the top-level script "falls through" to whatever modules
are included by it.


=head2 The top-level script

The definition of "top-level script" (to Debuggit, anyway) is "first 'use Debuggit' statement that
is executed by the Perl compiler."  Which means you should always put C<use Debuggit> before the
C<use> statements for other modules (or at least other modules of yours).

So typically what you would do is just put C<use Debuggit> at the top of all your code until you're
ready to debug.  When you hit a problem, change to C<use Debuggit DEBUG =E<gt> 3> (or whatever level
you feel is appropriate), but I<only> in the top-level script.  Then you get debugging info from all
your modules with one simple change.  Or, if you just I<know> the problem is in module X, you can
enable debugging in that module only (see below).  Convenient, right?

This may not work as well as you'd like if you can't figure out I<where> your top-level script
actually is (one great example of that is a mod_perl environment).  But you can still enable the
debugging in each module, so it isn't tragic.  Just not as convenient.


=head2 Overriding DEBUG in a specific module