NAME
InlineX::C2XS - Convert from Inline C code to XS.
SYNOPSIS
#USAGE:
#c2xs($module_name, $package_name [, $build_dir] [, $config_opts])
use InlineX::C2XS qw(c2xs);
my $module_name = 'MY::XS_MOD';
my $package_name = 'MY::XS_MOD';
# $build_dir is an optional third arg.
# If omitted it defaults to '.' (the cwd).
my $build_dir = '/some/where/else';
# $config_opts is an optional fourth arg (hash reference)
# See the "Recognised Hash Keys" section below.
my $config_opts = {'WRITE_PM' => 1,
'WRITE_MAKEFILE_PL' => 1,
'VERSION' => 0.42,
};
# Create /some/where/else/XS_MOD.xs from ./src/XS_MOD.c
c2xs($module_name, $package_name, $build_dir);
# Alternatively create XS_MOD.xs in the cwd:
c2xs($module_name, $package_name);
# Or Create /some/where/else/XS_MOD.xs from $code
$code = 'void foo() {printf("Hello World\n");}' . "\n\n";
c2xs($module_name, $package_name, $build_dir, {CODE => $code});
# Or Create /some/where/else/XS_MOD.xs from the C code that's in
# ./otherplace/otherfile.ext
$loc = './otherplace/otherfile.ext';
c2xs($module_name, $package_name, $build_dir, {SRC_LOCATION => $loc});
The optional final arg (a reference to a hash) is to enable the
passing of additional information and configuration options that
Inline may need - and also to enable the creation of the
Makefile.PL and .pm file (if desired).
See the "Recognised Hash Keys" section below for a list of the
accepted keys (and explanation of their usage).
# Create XS_MOD.xs in the cwd, and also generate the Makefile.PL
# and XS_MOD.pm:
c2xs($module_name, $package_name, $config_opts);
NOTE: If you wish to supply the $config_opts argument, but not the
$build_dir argument then you simply omit the $build_dir argument.
That is, the following are equivalent:
c2xs($module_name, $package_name, '.', $config_opts);
c2xs($module_name, $package_name, $config_opts);
If a third argument is given, it's deemed to be the build directory
unless it's a hash reference (in which case it's deemed to be the
hash reference containing the additional config options).
As of version 0.19, a c2xs utility is also provided. It's just an
Inline::C2XS wrapper - see 'c2xs --help'.
context($xs_file, \@func);
Call context() after running c2xs() if and only if you've used
the PRE_HEAD config option to define PERL_NO_GET_CONTEXT.
$xs_file is the location/name of the xs file that c2xs() wrote.
@func lists the functions to which the context args apply.
The rules are simple enough:
Define PERL_NO_GET_CONTEXT via PRE_HEAD option in $config_opts.
Don't specify the context args (pTHX, pTHX_, aTHX, aTHX_) in
your code at all. That is, just write the C code as though
PERL_NO_GET_CONTEXT had *not* been defined.
Write your function definitions on the one line. That is (eg),
instead of writing:
void
foo(SV* arg1)
write it as:
void foo(SV* arg1)
In your code, don't provide parentheses when not needed. For
example, instead of:
croak("Problem with one_func()");
warn("nother_func() might return something unwanted");
do:
croak("Problem with one_func");
warn("nother_func might return something unwanted");
Otherwise, the croak/warn messages might come out as:
croak("Problem with one_func(aTHX)");
warn("nother_func(aTHX) might return something unwanted");
Create an @func that lists the names of the functions that must
(or you wish to) take the context args. It's only the functions
that make use of perl's API that actually *have* to take the
context args.
Do:
c2xs($mod, $pack, $loc, $config_opts);
context("$loc/$pack.xs", \@funcs);
And check out the demo in demos/context. It's set up to build a
module whose XS file defines PERL_NO_GET_CONTEXT. In the
demos/context folder, run 'perl build.pl'. That perl script will
then create the XS file (and other files) needed for the
FOO module. The script first calls c2xs() to write FOO.xs (and
other files) in the FOO directory - then calls context() to
rewrite that XS file in accordance with the requirements of
PERL_NO_GET_CONTEXT.
Once that's done, you should be able to 'cd' to the FOO-0.01
folder and successfully run:
perl Makefile.PL
(d|n)make test
(d|n)make install (though I doubt you really want to do that.)
(d|n)make realclean
The context() sub is definitely breakable - patches welcome,
though effort would perhaps be better invested in getting this to
work via a more sane approach.DESCRIPTION
Don't feed an actual Inline::C script to this module - it won't
be able to parse it. It is capable of parsing correctly only
that C code that is suitable for inclusion in an Inline::C
script.
For example, here is a simple Inline::C script:
use warnings;
use Inline C => Config =>
BUILD_NOISY => 1,
CLEAN_AFTER_BUILD => 0;
use Inline C => <<'EOC';
#include <stdio.h>
void greet() {
printf("Hello world\n");
}
EOC
greet();
__END__
The C code that InlineX::C2XS needs to find would contain only that code
that's between the opening 'EOC' and the closing 'EOC' - namely:
#include <stdio.h>
void greet() {
printf("Hello world\n");
}
If the C code is not provided by either the CODE or SRC_LOCATION keys,
InlineX::C2XS looks for the C source file in ./src directory - expecting
that the filename will be the same as what appears after the final '::'
in the module name (with a '.c' extension). ie if your module is
called My::Next::Mod the c2xs() function looks for a file ./src/Mod.c,
and creates a file named Mod.xs. Also created by the c2xs function, is
the file 'INLINE.h' - but only if that file is needed. The generated
xs file (and any other generated files will be written to the cwd unless
the third argument supplied to c2xs() is a string specifying a valid
directory - in which case the generated files(s) will be written to that
directory.
The created XS file, when packaged with the '.pm' file (which can be
auto-generated by setting the WRITE_PM configuration key), an
appropriate 'Makefile.PL' (which can also be auto-generated by setting
the WRITE_MAKEFILE_PL hash key), and 'INLINE.h' (if it's needed), can be
used to build the module in the usual way - without any dependence
upon the Inline::C module.Recognised Hash Keys
As regards the optional fourth argument to c2xs(), the following hash
keys/values are recognised:
AUTO_INCLUDE
The value specified is automatically inserted into the generated XS
file. (Also, the specified include will be parsed and used iff
AUTOWRAP is set to a true value.) eg:
AUTO_INCLUDE => '#include <my_header.h>',
----
AUTOWRAP
Set this to a true value to enable Inline::C's AUTOWRAP capability.
eg:
AUTOWRAP => 1,
----
BOOT
Specifies C code to be executed in the XS BOOT section. Corresponds
to the XS parameter. eg:
BOOT => 'printf("Hello .. from bootstrap\n");',
----
BOOT_F
Specifies a file containing C code to be executed in the XS BOOT
section.
eg:
BOOT_F => '/home/me/boot_code.ext',
----
BUILD_NOISY
Is set to a true value, by default. Setting to a false value will
mean that progress messages generated by Inline::C are suppressed. eg:
BUILD_NOISY => 0,
----
CC
Specify the compiler you want to use. It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
CC => 'g++',
----
CCFLAGS
Specify which compiler flags to use. (Existing value gets clobbered, so
you'll probably want to re-specify it.) It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
CCFLAGS => $Config{ccflags} . ' -DMY_DEFINE',
----
CCFLAGSEX
Add compiler flags to existing flags.
It makes sense to assign this key only when WRITE_MAKEFILE_PL is set to
a true value. eg:
CCFLAGSEX => '-DMY_DEFINE ',
----
CODE
A string containing the C code. eg:
CODE => 'void foo() {printf("Hello World\n";}' . "\n\n",
----
DIST
If set, sets WRITE_MAKEFILE_PL => 1, WRITE_PM => 1, MANIF => 1. eg:
DIST => 1,
----
EXPORT_ALL
Makes no sense to use this unless WRITE_PM has been set.
Places all XSubs except those beginning with a *single* underscore (but not
multiple underscores) in @EXPORT in the generated .pm file. eg:
EXPORT_ALL => 1,
----
EXPORT_OK_ALL
Makes no sense to use this unless WRITE_PM has been set.
Places all XSubs except those beginning with a *single* underscore (but not
multiple underscores) in @EXPORT_OK in the generated .pm file. eg:
EXPORT_OK_ALL => 1,
----
EXPORT_TAGS_ALL
Makes no sense to use this unless WRITE_PM has been set.
In the generated .pm file, creates an EXPORT_TAGS tag named 'name'
(where 'name' is whatever you have specified), and places all XSubs except
those beginning with a *single* underscore (but not multiple underscores)
in 'name'. eg, the following creates and fills a tag named 'all':
EXPORT_TAGS_ALL => 'all',
----
INC
The value specified is added to the includes search path. It makes
sense to assign this key only when AUTOWRAP and/or WRITE_MAKEFILE_PL
are set to a true value. eg:
INC => '-I/my/includes/dir -I/other/includes/dir',
INC => ['-I/my/includes/dir', '-I/other/includes/dir'],
----
LD
Specify the linker you want to use.It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
LD => 'g++',
----
LDDLFLAGS
Specify which linker flags to use. (Existing value gets clobbered, so
you'll probably want to re-specify it.) It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
LDDLFLAGS => "$my_ldopts " . $Config{lddlflags},
----
LIBS
The value(s) specified become the LIBS search path. It makes sense
to assign this key only if WRITE_MAKEFILE_PL is set to a true value.
eg:
LIBS => '-L/somewhere -lsomelib -L/elsewhere -lotherlib',
LIBS => ['-L/somewhere -lsomelib', '-L/elsewhere -lotherlib'],
----
MAKE
Specify the make utility you want to use. It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
MAKE => 'pmake', # I have no idea whether that will work :-)
----
MANIF
If true, the MANIFEST file will be written. (It will include all created
files.) eg:
MANIF => 1,
----
MYEXTLIB
Specifies a user compiled object that should be linked in.
Corresponds to the MakeMaker parameter. It makes sense to assign this
key only when WRITE_MAKEFILE_PL is set to a true value. eg:
MYEXTLIB => '/your/path/yourmodule.so',
----
OBJECT
As for ExtUtils::MakeMaker option of the same name. eg:
OBJECT => '$(O_FILES)',
OPTIMIZE
This controls the MakeMaker OPTIMIZE setting.It makes sense to assign
this key only when WRITE_MAKEFILE_PL is set to a true value. eg:
OPTIMIZE => '-g',
----
PREFIX
Specifies a prefix that will be automatically stripped from C
functions when they are bound to Perl. eg:
PREFIX => 'FOO_',
----
PRE_HEAD
Specifies code that will precede the inclusion of all files specified
in AUTO_INCLUDE (ie EXTERN.h, perl.h, XSUB.h, INLINE.h and anything
else that might have been added to AUTO_INCLUDE by the user). If the
specified value identifies a file, the contents of that file will be
inserted, otherwise the specified value is inserted.
If the specified value is a string of code, then since that string
ends in "\n" (as all code *should* terminate with at least one "\n"),
you will get a warning about an "Unsuccessful stat on filename
containing newline" when the test for the existence of a file that
matches the PRE_HEAD value is conducted.
PRE_HEAD => $code_or_filename;
----
PREREQ_PM
Makes sense to specify this only if WRITE_MAKEFILE_PL is set to true.
The string to which PREREQ_PM is set will be reproduced as is in the
generated Makefile.PL. That is, if you specify:
PREREQ_PM => "{'Some::Mod' => '1.23', 'Nother::Mod' => '3.21'}",
then the WriteMakefile hash in the generated Makefile.PL will
contain:
PREREQ_PM => {'Some::Mod' => '1.23', 'Nother::Mod' => '3.21'},
----
PROTOTYPE
Corresponds to the XS keyword 'PROTOTYPE'. See the perlxs documentation
for both 'PROTOTYPES' and 'PROTOTYPE'. As an example, the following will
set the PROTOTYPE of the 'foo' function to '$', and disable prototyping
for the 'bar' function.
PROTOTYPE => {foo => '$', bar => 'DISABLE'}
----
PROTOTYPES
Corresponds to the XS keyword 'PROTOTYPES'. Can take only values of
'ENABLE' or 'DISABLE'. (Contrary to XS, default value is 'DISABLE'). See
the perlxs documentation for both 'PROTOTYPES' and 'PROTOTYPE'.
PROTOTYPES => 'ENABLE';
----
SRC_LOCATION
Specifies a C file that contains the C source code. eg:
SRC_LOCATION => '/home/me/source.ext',
----
T
Is false by default but, When set to true will write a basic
t/00load.t test script in the build directory.
eg:
T => 1,
----
TYPEMAPS
The value(s) specified are added to the list of typemaps.
eg:
TYPEMAPS =>'my_typemap my_other_typemap',
TYPEMAPS =>['my_typemap', 'my_other_typemap'],
----
USE
Must be an array reference, listing the modules that the autogenerated
pm file needs to load (use). Makes no sense to assign this key if
WRITE_PM is not set to a true value. eg:
USE => ['Digest::MD5', 'LWP::Simple'];
----
USING
If you want Inline to use ParseRegExp.pm instead of RecDescent.pm for
the parsing, then specify either:
USING => ['ParseRegExp'],
or
USING => 'ParseRegExp',
----
VERSION
Set this to the version number of the module. It makes sense to assign
this key only if WRITE_MAKEFILE_PL and/or WRITE_PM is set to a true
value. eg:
VERSION => 0.42,
----
WRITE_MAKEFILE_PL
Set this to to a true value if you want the Makefile.PL to be
generated. (You should also assign the 'VERSION' key to the
correct value when WRITE_MAKEFILE_PL is set.) eg:
WRITE_MAKEFILE_PL => 1,
----
WRITE_PM
Set this to a true value if you want a .pm file to be generated.
You'll also need to assign the 'VERSION' key appropriately.
Note that it's a fairly simplistic .pm file - no POD, no perl
subroutines, no exported subs (unless EXPORT_ALL or EXPORT_OK_ALL
has been set), no warnings - but it will allow the utilisation of all of
the XSubs in the XS file. eg:
WRITE_PM => 1,
----TODO
Improve the t_makefile_pl test script. It currently provides strong
indication that everything is working fine ... but is not conclusive.
(This might take forever.)BUGS
None known - patches/rewrites/enhancements welcome.
Send to sisyphus at cpan dot orgLICENSE
This program is free software; you may redistribute it and/or
modify it under the same terms as Perl itself.
Copyright 2006-2009, 2010-12, 2014, 2016, 2018 SisyphusAUTHOR
Sisyphus <sisyphus at(@) cpan dot (.) org>