view release on metacpan or  search on metacpan

DebugInit.pm  view on Meta::CPAN

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
	
);
$VERSION = '0.3';

$Devel::DebugInit::MACROS_NONE  = 0;
$Devel::DebugInit::MACROS_LOCAL = 1;
$Devel::DebugInit::MACROS_ALL   = 2;

=head1 NAME

Devel::DebugInit - Perl extension for creating a debugger
initialization files from C header file macros

=head1 SYNOPSIS

  use Devel::DebugInit::GDB;
  my $gdb = new Devel::DebugInit::GDB 'filenames' => ["/my/path/to/library.h"];
  $gdb->write("/my/path/to/library/.gdbinit");

=head1 DESCRIPTION

Devel::DebugInit is aimed at C/C++ developers who want access to C
macro definitions from within a debugger. It provides a simple and
automated way of creating debugger initialization files for a specific
project. The initialization files created contain user-defined
functions built from the macro definitions in the project's header
files.

By calling new(), the files specified by the 'filenames' parameter are
parsed by the C preprocessor, and all macros #define'd in the file
(and if desired, all macros #define'd by all #include'd files as
well), will be parsed and expanded. By then calling the write()
method, these macros can be written to an output file in the format of
user-defined functions specific for your debugger.

By automating the process, a new file can be created whenever the code
of a project changes, and that way there will not be antiquated copies
lying around to trap the unwary.

=head1 NOTES

This module requires the use of one of the debugger-specific backend
modules, such as Devel::DebugInit::GDB which is supplied with
DebugInit. The backends supply the output routines which are specific
for that debugger. 

This module also requires both the C::Scan and Data::Flow modules and
will not function without them.

=head1 WHY CARE?

Debugger initialization files can contain user-defined functions that
make doing complicated or repetitive actions easier. Normally, from
within the debugger a user can evaluate any C function call. But for a
number of reasons, many projects use C preprocessor macros (#define
statements) in place of an actual C function call. The use of macros
instead of function calls is transparent during compilation, but most
debuggers do not allow access to macros, and so the user must type in
the code by hand each time s/he wants to use a macro, or must build an
initialization file by hand. Retyping is tedious, but hand coding the
initialization file may result in antiquated code when the project changes. By
automating the process, I hope to alleviate a few headaches for
developers.

There are two types of macros: macros with arguments, e.g:

   #define min(x,y) ((x) < (y) ? (x) : (y))

and macros without arguments (simple macros), e.g.

   #define PI 3.14

Of the two types, macros with arguments are more useful from within a
debugger, and so, printing of simple macros is turned off by default
(but see L<INTERNALS> for how to turn them on).

=head1 INTERNALS

For the casual user the defaults, and the three lines given in the
L<SYNOPSIS> should be enough. But for the determined user, a few
details of how things happen under the hood might be useful in
customizing the output of this module.

=head2 How Devel::DebugInit Parses Files

When new() is called to create an instance of a Devel::DebugInit, the
following steps occur. The C preprocessor is invoked on the file with
the 'macros only' flag set (this flag defaults to '-dM' and if this does
not work on your system, change the value of $C::Scan::MACROS_ONLY and
let the author know, and he will try and fix it :-). This lists all
macros #define'd in the file PLUS all macros #define'd in all files
#include'd by that file (both the system files <types.h> and the user
files "mystring.h"). This may include many more macros than is desired
(not everybody really wants '_LINUX_C_LIB_VERSION_MAJOR' as a user
defined function in their debugger...), so there are 3 mode flags
defined that allow the user to control which macros are included:
MACROS_ALL, MACROS_LOCAL, and MACROS_NONE.

=head2 MACROS_ALL, MACROS_LOCAL, and MACROS_NONE

These flags can be used to control what macros go into the print
tables that Devel::DebugInit uses to create the output file. The
MACROS_ALL flag instructs DebugInit to included all macros of that
type in the output table. To avoid printing out all of the system level
macros that can get #include'd you can use the MACROS_LOCAL flag. This
indicates that only macros actually #define'd in that file should be
stored, and macros #define'd in other files which are #include'd into
the file should NOT be stored (they are, however, still made available
for expansion purposes). The MACROS_LOCAL flag is the default for
macros with arguments. Finally, the MACROS_NONE flag indicates that no
macros of that type should be put in the output table. The MACROS_NONE
flag is the default for the simple macros.

=head2 Output Tables and Lookup Tables

Devel::DebugInit has two separate groups of tables that it uses -
lookup tables for expanding macro definitions and output tables for