features/wrapper.feature @@ -1,5 +1,61 @@ package Egypt::Extractor::GCC; +=head1 NAME + +Egypt::Extractor::GCC - egypt's extractor for GCC-generated intermediate files. + +=head1 DESCRIPTION + +The GCC extractor reads information from the intermediate files generated by +GCC after it compiles the source code. When using the GCC extractor, egypt +tools will traverse your directories for files matching F<*.rtl> and +F<*.expand>, and will parse them in order to obtain information. + +The original egypt implementation by Andreas Gustafsson only supported +extracting information using GCC information. After major refactoring of the +code, that logic ended up in this module as a pluggable component for use +with egypt's current implementation. + +=head1 GENERATING THE INPUT FILES + +Compile the program or source file you want to create a call graph for +with gcc, adding the option "-dr" to CFLAGS. This option causes gcc +to dump its intermediate code representation of each file it compiles +into a a file. + +For example, the following works for many programs: + + make clean + make CFLAGS=-dr + +Depending on the GCC version, the RTL file for a source file F<foo.c> +may be called something like F<foo.c.rtl>, F<foo.c.00.rtl>, or +F<foo.c.00.expand>. + +=head1 LIMITATIONS + +Relying on GCC-suplied information brings two major drawbracks: + +=over + +=item +The dependencies are processed after compiling the code, so some +information is lost. For example functions or variables that are actually +implemented as macros (#define's) are not considered in the results. + +=item +You have to compile the sources before extracting information. Depending on the +size of the project and how many times you need to extract the information, this +limitation will probably make this extractor not viable for you. + +=back + +=head1 SEE ALSO + +L<gcc>, L<egypt> + +=cut + use strict; use warnings; Egypt/Extractor/GCC.pm @@ -1,16 +1,10 @@ use ExtUtils::MakeMaker; -my $version = `perl -ne 'if (/applies to egypt version/) { s/.*version //; s/[^0-9]*\$//; print }' egypt`; -chomp $version; -unless ($version =~ /^\d+.\d+$/) { - die "Invalid version read from documentation: [$version]. There is something wrong with this package.\n"; -} - my @exe_files = glob('egypt*'); WriteMakefile( NAME => 'egypt', - VERSION => $version, + VERSION_FROM => 'egypt', EXE_FILES => \@exe_files, PMLIBDIRS => [ 'Egypt' ], AUTHOR => 'Antonio Terceiro <terceiro@softwarelivre.org>', Makefile.PL @@ -1,16 +1,16 @@ #!/usr/bin/perl -w use Pod::Usage; - -#use Getopt::Euclid; +our $VERSION = '1.8.0'; =head1 NAME -egypt - a source code analysis suite. +egypt - a source code analysis suite =head1 SYNOPSIS - egypt <tool> [options] <args> + egypt <tool> [tool-options] <toolargs> [<tool-args> ...] + egypt <option> =head1 DESCRIPTION @@ -26,7 +26,7 @@ egypt has several individual tools that share a core infrastructure, but do different analysis and produce different output. They are normally invoked like this: - egypt <tool> [OPTIONS] <directory> [<directory> ...] + egypt <tool> [tool-options] <tool-args> [<tool-args> ...] Although you can invoke egypt tools against one or few files inside a project, normally it only makes sense to run it against the entire source tree (e.g. @@ -37,6 +37,9 @@ corresponding manual for the tool(s) you want. =head1 OPTIONS +The following are the options for the wrapper egypt script. The options for +each tools are documented in the respective tool's manual page. + =over =item --version @@ -47,52 +50,89 @@ Displays version information and exits. Displays help for the 'egypt' command. -=item --usage +=back + +=head1 COPYRIGHT -Displays usage for the 'egypt' command. +=over + +=item Copyright (c) 1994-2006 Andreas Gustafsson + +=item Copyright (c) 2008-2009 Antonio Terceiro =back -=head1 VERSION +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + +=head1 AUTHORS -This documentation applies to egypt version 1.8. +Andreas Gustafsson wrote the original version of egypt. Since them several +people contributed to egypt's development. See the AUTHORS file for a complete +list. =cut use strict; use File::Basename; -sub usage { - pod2usage(-verbose => 1); - exit(1); -} - -if (scalar(@ARGV) == 0) { - usage(); -} - my $base = dirname(__FILE__); -my $command = shift(@ARGV); -if ($command !~ /^[a-z]+$/) { - usage(); +sub usage { + my $status = shift; + pod2usage(-verbose => 1, -exitval => "NOEXIT"); + list_egypt_tools(); + exit($status); } -my $program = "$base/egypt-$command"; -if (! -x $program) { - printf("\"%s\" is not an egypt command.\n", $command); - print("\n"); +sub list_egypt_tools { print("Available commands:\n"); print("\n"); for my $cmd_program (sort(glob("$base/egypt-*"))) { $cmd_program =~ /^.*egypt-(.*)$/; my $cmd = $1; - printf(" %s\n", $cmd); + printf(" %s\n", $cmd); } print("\n"); +} + +sub show_version { + printf("egypt version %s\n", $VERSION); + exit(0); +} + +if (scalar(@ARGV) == 0) { + usage(1); +} + +my $tool = shift(@ARGV); +if ($tool !~ /^[a-z]+$/) { + if ($tool eq '--version') { + show_version(); + } elsif($tool eq '--help') { + usage(0); + } else { + printf("Invalid option: %s\n", $tool); + usage(1); + } +} + +my $program = "$base/egypt-$tool"; +if (! -x $program) { + printf("\"%s\" is not an egypt command.\n\n", $tool); + list_egypt_tools(); + exit(1); +} +# do not pass --version option ahead, since the tools don't have a version on +# their own. +my @args; +if (grep { $_ eq '--version' } @ARGV) { + print("Invalid option: --version\n"); + system($program, '--help'); exit(1); +} else { + system($program, @ARGV); + exit($? >> 8); } -system($program, @ARGV); -exit($? >> 8); egypt @@ -4,32 +4,32 @@ use Getopt::Euclid; =head1 NAME -egypt - create call graph from gcc RTL dump - -=head1 VERSION - -This documentation applies to egypt version 1.8. +egypt graph - dependency graph generator =head1 USAGE - egypt [options] <file>... + egypt graph [options] <input>... =head1 DESCRIPTION -Egypt is a simple tool for creating call graphs of C programs. +egypt graph reads the dependency information from one or more source code +directories passed as arguments, and produces as output the graph of +dependencies between the modules of the software in the graphviz(1) format. + +egypt graph is part of the egypt suite. =head1 REQUIRED ARGUMENTS =over -=item <file>... +=item <input>... -egypt can process any number of RTL files passed to it on the command line. If -you pass directories in the command line, egypt will find those directories for -files that match *.rtl and *.expand, and process them. +The input directories (or files) with source code to be processed. -If no input files are given in the command line, egypt will expect the RTL data -in the standard input. +Although you can pass individual files as input, this tool is more useful if +you pass entire source directories. If you pass just a couple of files, their +dependencies on modules that are not declared and/or implemented in those +files will not be calculated. =back @@ -55,6 +55,8 @@ default, such calls are not shown. Even with this option, only direct calls will be shown; there is no way to show indirect calls to external functions. +This options only works with the GCC extractor. + =item --cluster Cluster the functions into files, so you can see in which files are the calling @@ -73,16 +75,14 @@ It doesn't make much sense to use --modules together with --cluster. =item --extractor <extractor> -Define wich extractor method use to analise source code. Default is Doxyparse. +Define wich extractor method use to analise source code. Options are "Doxyparse" and +"GCC". Default is Doxyparse. See Egypt::Extractor::GCC(3) for information on how to +setup your source tree in order to use the GCC extractor. =for Euclid: extractor.type: string, extractor =~ /\A\w+\Z/ extractor.default: 'Doxyparse' -=item --version - -Displays egypt version information and exits. - =item --help Displays help on command line syntax and options. @@ -105,85 +105,61 @@ file>); this file is much easier to extract information from than a C source file. Egypt extracts information about function calls from the RTL file and massages it into the format used by Graphviz. -=head1 GENERATING THE RTL FILE - -Compile the program or source file you want to create a call graph for -with gcc, adding the option "-dr" to CFLAGS. This option causes gcc -to dump its intermediate code representation of each file it compiles -into a a file. +=head1 VIEWING THE GRAPH -For example, the following works for many programs: +To view the generated graph, pipe egypt's output to one of the +Graphiz tools. You can use B<dotty(1)> to display the graph in a +X11 window: - make clean - make CFLAGS=-dr + $ egypt graph src/ | dotty - -Depending on the GCC version, the RTL file for a source file F<foo.c> -may be called something like F<foo.c.rtl>, F<foo.c.00.rtl>, or -F<foo.c.00.expand>. +You can also generate a file to print or include in a document +by using the B<dot(1)>. -=head1 VIEWING THE CALL GRAPH +To generate a PNG image called F<graph.png>: -To view the call graph in an X11 window, run egypt with one or -more .rtl files as command line arguments and pipe its output to the -B<dotty> program from the Graphviz package. For example, if you -compiled F<foo.c> with C<gcc -dr> to generate F<foo.c.00.rtl>, use + $ egypt graph src/ | dot -Tpng -ograph.png - - egypt foo.c.00.rtl | dotty - +To generate a PostScript version of the dependency graph for printing, you can +also use the B<dot>. For example, to generate a dependency graph in the file +F<graph.ps> fitting everything on a US letter size page in landscape mode, try -=head1 PRINTING THE CALL GRAPH + $ egypt graph src/ | dot -Grotate=90 -Gsize=11,8.5 -Tps -o graph.ps -To generate a PostScript version of the call graph for printing, use -the B<dot> program from the Graphviz package. For example, to generate -a callgraph in the file F<callgraph.ps> fitting everything on a US -letter size page in landscape mode, try +Sometimes, the graph will fit better if the dependencies arrows go from left to +right instead of top to bottom. The B<dot> option B<-Grankdir=LR> will do +that: - egypt foo.c.00.rtl | dot -Grotate=90 -Gsize=11,8.5 -Tps -o callgraph.ps + $ egypt graph src/ | dot -Gsize=8.5,11 -Grankdir=LR -Tps -o graph.ps -Sometimes, the graph will fit better if function calls go from left to -right instead of top to bottom. The B<dot> option B<-Grankdir=LR> -will do that: - - egypt foo.c.00.rtl | dot -Gsize=8.5,11 -Grankdir=LR -Tps -o callgraph.ps - -For nontrivial programs, the graph may end up too small +For large software, the graph may end up too small to comfortably read. If that happens, try N-up printing: - egypt foo.c.00.rtl | dot -Gpage=8.5,11 -Tps -o callgraph.ps + $ egypt graph src/ | dot -Gpage=8.5,11 -Tps -o graph.ps You can also try playing with other B<dot> options such as B<-Gratio>, or for a different style of graph, try using B<neato> instead of B<dot>. See the Graphwiz documentation for more information about the various options available for customizing the style of the graph. -=head1 READING THE CALL GRAPH - -Function calls are displayed as solid arrows. A dotted arrow means -that the function the arrow points from takes the address of the -function the arrow points to; this typically indicates that the latter -function is being used as a callback. +=head1 READING THE GRAPH -=head1 WHY IS IT CALLED EGYPT? +When generating a graph in the function level (i.g. without the I<--modules> +option), function calls are displayed as solid arrows. A dotted arrow means +that the function the arrow points from takes the address of the function the +arrow points to; this typically indicates that the latter function is being +used as a callback. -Egypt was going to be called B<rtlcg>, short for I<RTL Call Graph>, -but it turned out to be one of those rare cases where ROT13'ing the -name made it easier to remember and pronounce. +When the I<--modules> option is on, then there are only solid arrows. An arrow +from I<A> to I<B> means that I<A> depends on I<B>. =head1 SEE ALSO -L<gcc>, L<dotty>, L<dot>, L<neato> - -=head1 COPYRIGHT - -Copyright (c) 1994-2006 Andreas Gustafsson -Copyright (c) 2008-2009 Antonio Terceiro - -This program is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. +B<dotty(1)>, B<dot(1)>, B<neato(1)>, B<egypt(1)> -=head1 AUTHORS +=head1 COPYRIGHT AND AUTHORS -Andreas Gustafsson wrote the original version of egypt. Antonio Terceiro built -on his work and did a major refactoring while adding several features. +See B<egypt(1)> =cut @@ -210,7 +186,7 @@ $output->cluster($ARGV{'--cluster'}); # wheter to group by module or not $output->group_by_module($ARGV{'--modules'}); -$extractor->process(@{$ARGV{'<file>'}}); +$extractor->process(@{$ARGV{'<input>'}}); print $output->string; exit(0); egypt-graph @@ -4,17 +4,25 @@ use Getopt::Euclid; =head1 NAME -egypt-metrics - egypt's metric reporting tool +egypt metrics - egypt's metric reporting tool -=head1 USAGE +=head1 SYNOPSIS - egypt-metrics [options] <directory> [<directory> ...] + egypt metrics [options] <input> [<input> ...] + +=head1 DESCRIPTION + +egypt metrics analyzes source code in the directories passed as arguments and +procudes a matrics report. Such report is written to the standard output in the +YAML format (see I<http://www.yaml.org/>) + +egypt metrics is part of the egypt suite. =head1 REQUIRED ARGUMENTS =over -=item <directory>... +=item <input>... Tells egypt which source code directory(ies) you want to parse. @@ -39,14 +47,21 @@ see Egypt::Extractor::GCC(3). When using the Doxyparse extractor (default), all files matching the languages supported by doxyparse are processed. +=item --help + +Displays a help message on how to use this tool. + =back -=head1 COPYRIGHT +=head1 OUTPUT FORMAT + +The output is a stream of YAML documents. The first one presents metrics for +the project as a whole. The subsequent ones present per-module metrics, and thus +there will be as many of them as there are modules in your project. -Copyright (c) 2009 Antonio Terceiro +=head1 COPYRIGHT AND AUTHORS -This program is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. +See egypt(1) =cut @@ -58,7 +73,7 @@ use Egypt::Metrics; my $extractor = Egypt::Extractor->load($ARGV{'--extractor'}); my $metrics = Egypt::Metrics->new(model => $extractor->model); -$extractor->process(@{$ARGV{'<directory>'}}); +$extractor->process(@{$ARGV{'<input>'}}); print $metrics->report; exit(0); egypt-metrics @@ -23,7 +23,11 @@ end When /^I run "([^\"]*)"$/ do |command| system("#{command} >tmp.out 2>tmp.err") - @exit_status = $? + if $?.is_a?(Fixnum) + @exit_status = $? + else + @exit_status = $?.exitstatus + end @stdout = File.readlines('tmp.out') @stderr = File.readlines('tmp.err') end @@ -51,8 +55,26 @@ Then /^egypt must report that "([^\"]*)" is part of "([^\"]*)"$/ do |func,mod| found.should == true end +class OutputDoesNotMatch < Exception +end Then /^the output must match "([^\"]*)"$/ do |pattern| - @stdout.select {|item| item.match(pattern)}.should have_at_least(1).items + if @stdout.select {|item| item.match(pattern)}.size == 0 + delimiter_line = "-------------------------------------------------\n" + report = [] + report.push "Standard output:\n" + report.push delimiter_line + report.push @stdout + report.push delimiter_line + if !@stderr.empty? + report.push "\n" + report.push "Standard error:\n" + report.push delimiter_line + report.push @stderr + report.push delimiter_line + end + report.push "\n" + raise OutputDoesNotMatch.new(report) + end end Then /^the output must not match "([^\"]*)"$/ do |pattern| features/step_definitions/egypt_steps.rb features/graph/version.feature a49f09bafd5484f728f5d616aa015d674fb37485 Antonio Terceiro terceiro@softwarelivre.org http://github.com/terceiro/egypt/commit/459b7a02ada64d7914bada83bf7b12ed40a861b8 459b7a02ada64d7914bada83bf7b12ed40a861b8 2009-08-27T09:17:38-07:00 2009-08-27T09:17:38-07:00 Documentation and UI work 7efb15a80bea650587a8cdcdc6aed7f276327f1e Antonio Terceiro terceiro@softwarelivre.org