XS::Check - check XS for problems
use FindBin '$Bin'; use XS::Check; my $check = XS::Check->new (); $check->check_file ("$Bin/synopsis.xs");
produces output
/usr/home/ben/projects/xs-check/examples/synopsis.xs:3: x not a constant type. /usr/home/ben/projects/xs-check/examples/synopsis.xs:3: len is not a STRLEN variable (unsigned int ).
(This example is included as synopsis.pl in the distribution.)
This documents version 0.08 of XS::Check corresponding to git commit b0c84d70e906e954deb76ca5e749f674d26ca3f7 released on Mon Aug 28 09:24:43 2017 +0900.
This module offers ways to check XS files for common flaws.
my $check = XS::Check->new ();
Make a new XS::Check object.
For user-defined error reporting, supply a code reference with the key reporter as follows:
reporter
my $usercheck = XS::Check->new (reporter => sub { print "help!" });
The arguments to the user defined function are a hash containing the fields
the file name of the file where the error occurred, if using "check_file" or if set with "set_file", otherwise the undefined value (undef),
undef
the line number where the error occurred, starting from 1,
the message from the module, a text string.
The following example demonstrates a user-defined callback using the message and line fields:
message
line
use XS::Check; my $rchecker = XS::Check->new (reporter => \& reporter); $rchecker->check ("Perl_croak ('croaking');\n"); sub reporter { my %rstuff = @_; print "$rstuff{message} at $rstuff{line}.\n"; }
Remove the 'Perl_' prefix from Perl_croak at 1.
(This example is included as reporter.pl in the distribution.)
Callback error reporting was added to the module in version 0.07.
$check->check ($xs);
See "SUGGESTIONS" for what this reports.
$check->check ($xs_file);
Convenience method to read in $xs_file then run "check" on it.
This assumes UTF-8 encoding of $xs_file.
$check->set_file ($file);
Set the file name for error reporting. Use any false value to clear it. For example:
use XS::Check; my $check = XS::Check->new (); my $xs = "Perl_croak (\"frog\")\n"; $check->check ($xs); $check->set_file ('Yabadabado'); $check->check ($xs); $check->set_file (''); $check->check ($xs);
1: Remove the 'Perl_' prefix from Perl_croak. Yabadabado:1: Remove the 'Perl_' prefix from Perl_croak. 1: Remove the 'Perl_' prefix from Perl_croak.
(This example is included as set-file.pl in the distribution.)
This method was added in version 0.08.
This section details the possible suggestions made by the module and the motivations behind them.
Using an int type for the second argument to SvPV may cause errors on 64-bit Perls.
Be careful to not overwrite Perl's own buffer, which SvPV returns.
Replace with Newx etc.
These cause "free to wrong pool" errors on multithreaded Windows Perls.
Functions like Perl_croak should not be used, just croak.
Perl_croak
croak
This check was added in version 0.04.
XS functions cannot use the ANSI C (void) to indicate that they do not take any arguments, instead this results in a variable called "void" being created.
(void)
This check was added in version 0.06.
As of 0.08, the module has the following limitations.
The module is not very good at parsing struct members, so XS code like the following doesn't get dealt with properly:
s.txt = SvPV (sv, s.len);
"check_file" uses "read_text" in File::Slurper to read the text, which means it only takes UTF-8.
The current method of parsing variable declarations uses a very simplistic hack, and it is likely to produce false results if a variable name is used twice for two different things in the same file.
This supplies the regular expressions used to parse C by the module.
This is used by "check_file".
This is used to get the line numbers.
A command line tool called checkxs is installed with the module. It runs the "check_file" method on each file named on the command line.
checkxs
checkxs Some.xs
As of 0.08, there are no options to the script. Its output goes to standard error.
A collection of more or less obscure bugs found by CPAN testers, the original inspiration for this module.
Ben Bullock, <bkb@cpan.org>
This package and associated files are copyright (C) 2017 Ben Bullock.
You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.
To install XS::Check, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XS::Check
CPAN shell
perl -MCPAN -e shell install XS::Check
For more information on module installation, please visit the detailed CPAN module installation guide.