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).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");',
----
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 => '-DMY_DEFINE ' . $Config{ccflags},
----
CODE
A string containing the C code. eg:
CODE => 'void foo() {printf("Hello World\n";}' . "\n\n",
----
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 :-)
----
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',
----
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_',
----
SRC_LOCATION
Specifies a C file that contains the C source code. eg:
SRC_LOCATION => '/home/me/source.ext',
----
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'],
----
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, SisyphusAUTHOR
Sisyphus <sisyphus at(@) cpan dot (.) org>