c2ast - C source analysis
version 0.35
c2ast.pl [options] [file ...] Options: --help Brief help message --cpp <argument> cpp executable. Default is 'cpp'. --cppfile <filename> The name of the file being preprocessed. --cppdup <filename> Save the preprocessed output to this filename. --lexeme <lexeme> Lexemes of interest. --progress Progress bar with ETA information. --check <checkName> Perform some hardcoded checks on the code. --dump Dump parse tree value on STDOUT. --dumpfile <file> Dump parse tree value to this named file. --allowAmbiguity Allow more than a single parse tree value. --loglevel <level> A level that has to be meaningful for Log::Log4perl, typically WARN, INFO, ERROR, etc. --logstderr Logs to stderr or not.
This script will use Marpa::R2 to analyse the file given in argument.
Say --help on the command-line to have the full list of options, and examples.
c2ast.pl - C source code transformation to AST and eventual check of C Programming Best Practices
This help
cpp executable. Default is 'cpp'.
If your setup requires additional option, then you should repeat this option. For example: your cpp setup is "cl -E". Then you say:
--cpp cl --cpp -E
Take care: it has been observed that "cpp" output could be different than "compiler -E". If c2ast complains and the output manifestly reports something that has not been preprocessed corrected, then retry with: --cpp your_compiler --cpp your_compiler_option
This has been observed on Darwin for instance, where one have to say:
--cpp gcc --cpp -E
The name of the file being preprocessed. Usually this option is not necessary. By default this is the main file being pre-processed, as indicated by the first preprocessor line directive. (Preprocessor line directives start are lines starting with '#line'.) For the --lexeme tracing phase or the --check phase, c2ast includes only the information that is relevant to the lexemes contained in the "cppfile".
One circumstance where this option is necessary if when the C files are not the source files, but were generated by another program. For example, the input file might be named 'generated.c', but the actual source, from which 'generated.c' was generated, might be in a file named 'source.c'. If convention is being followed, 'generated.c' will contain lines of the form, to indicate which portions of the code originally came from 'source.c'.
# line xxx "source.c"
You can tell c2ast.pl to analyze the code originally from "source.c", as indicated by the preprocessor line directives, with the option
--cppfile "source.c"
Save the preprocessed output to this filename. Only useful for debugging c2ast.
Lexemes of interest. Look to the grammar to have the exhaustive list. In practice, only IDENTIFIER, TYPEDEF_NAME, ENUMERATION_CONSTANT and STRING_LITERAL_UNIT are useful. An internal lexeme, not generated by Marpa itself also exist: PREPROCESSOR_LINE_DIRECTIVE. This option must be repeated for every lexeme of interest. Giving a value __ALL__ will make all lexemes candidates for logging. The output will go to STDOUT.
Progress bar with ETA information. The "name" associated with the progress bar will the last of the arguments unknown to c2ast. So it is quite strongly suggested to always end your command-line with the file you want to analyse.
Perform some hardcoded checks on the code. Supported values for checkName are:
Check IDENTIFIER lexemes v.s. Gnu recommended list of Reserved Names [1].
Any check that is not ok will print on STDERR.
Dump parse tree value on STDOUT.
Dump parse tree value to this named file.
Take care: dumping the parse tree value can hog your memory and CPU. This will not be c2ast fault, but the module used to do the dump (currently, Data::Dumper).
Default is to allow a single parse tree value. Nevertheless, if the grammar in use by c2ast has a hole, use this option to allow multiple parse tree values. In case of multiple parse tree values, only the first one will be used in the check phase (option --check).
A level that has to be meaningful for Log::Log4perl, typically WARN, INFO, ERROR, etc. Default is WARN.
Note that tracing Marpa library itself is possible, but only using environment variable MARPA_TRACE /and/ saying --loglevel TRACE.
In case of trouble, typical debugging phases c2ast are: --loglevel INFO then: --loglevel DEBUG then: --loglevel TRACE
Logs to stderr or not. Default is $logstderr.
Any option not documented upper will be considered as a cpp option, and sent to the underlying the cpp program.
Examples:
c2ast.pl -D MYDEFINE1 -D MYDEFINE2 -I /tmp/myIncludeDir /tmp/myfile.c c2ast.pl -D MYDEFINE1 -D MYDEFINE2 -I /tmp/myIncludeDir /tmp/myfile.c --lexeme IDENTIFIER --lexeme TYPEDEF_NAME c2ast.pl --cpp cl --cpp -E -D MYDEFINE1 -D MYDEFINE2 -I C:/Windows/myIncludeDir C:/Windows/Temp/myfile.c c2ast.pl -D MYDEFINE1 -D MYDEFINE2 -I /tmp/myIncludeDir /tmp/myfile.c --progress --check reservedNames
Less typical usage:
c2ast.pl -I libmarpa_build --cpp gcc --cpp -E --cppfile ./marpa.w --progress --check reservedNames libmarpa_build/marpa.c
http://www.gnu.org/software/libc/manual/html_node/Reserved-Names.html
Jean-Damien Durand <jeandamiendurand@free.fr>
This software is copyright (c) 2013 by Jean-Damien Durand.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install MarpaX::Languages::C::AST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MarpaX::Languages::C::AST
CPAN shell
perl -MCPAN -e shell install MarpaX::Languages::C::AST
For more information on module installation, please visit the detailed CPAN module installation guide.