use Devel::DebugInit::GDB;
my $gdb = new Devel::DebugInit::GDB 'filenames' => ["/my/path/to/library.h"];
$gdb->write("/my/path/to/library/.gdbinit");
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.
This module also requires both the C::Scan and Data::Flow modules and will not function without them.
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 INTERNALS for how to turn them on).
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.
$gdb = new Devel::DebugInit::GDB
'filenames' => ["$Config{'archlib'}/CORE/perl.h"],
'macros_args' => $Devel::DebugInit::MACROS_ALL,
'macros_no_args' => $Devel::DebugInit::MACROS_ALL;
$gdb->write();
When written, this will create a file that is about 110k in size and have about 1750 user-defined functions. So it may be useful to limit it in scope somewhat. It is not clear that simple macros are useful from within a debugger, so the default value for 'macros_no_args' is MACROS_NONE, and to avoid printing all system level macros, the default for 'macros_args' is MACROS_LOCAL. NOTE that by using MACROS_LOCAL, you will inhibit printing of all macros not #define'd in the file listed, both from local header files and system headers alike. To get around this multiple files can be included in the array ref for the 'filenames' option. Each files macros are added to a common lookup table, but only the macros #defined in each file are printed. So could do the following:
$gdb = new Devel::DebugInit::GDB
'filenames' => ["$Config{'archlib'}/CORE/perl.h",
"$Config{'archlib'}/CORE/sv.h",
"$Config{'archlib'}/CORE/XSUB.h"],
'macros_args' => $Devel::DebugInit::MACROS_LOCAL,
'macros_no_args' => $Devel::DebugInit::MACROS_NONE;
$gdb->write();
This reduces the output file to only 21k and 250 or so macros.
$filename is
not given, it defaults to something reasonable for that debugger. All
macros in the output table for each macro type (macros with arguments and
simple macros) will be printed if it passes scrutiny by the scan() method. See the INTERNALS section for more details on controlling what macros are stored in the print
tables.
scan() method which is also overloaded by each backend
subclass. This method is called by write() to ascertain
whether or not a given macro should be written out to the output file. By
default, scan() stops undefined macros, blank macros (e.g.
macros such as <#define VMS> which are usually just conditional
compiler flags and of no use in a debugger), and macros with names that
conflict with built-in debugger commands. Users desiring a very fine
grained control over the output can override the builtin
scan() with their own on a per need basis. For example:
package myGDB;
use Devel::DebugInit::GDB;
@myGDB::ISA = (Devel::DebugInit::GDB);
sub scan {
my ($gdb,$key,$macro) = @_;
#first give the superclass scan a chance
return 0 unless $gdb->SUPER::scan(@_);
# dont' print out any macros with a leading '_'
return 0 if $macro =~ /^_/;
# print the rest
return 1;
}
perl(1), Devel::DebugInit::GDB(3), C::Scan(3), and
Data::Flow(3).