/ 
InlineX-C2XS-0.10
River stage one • 1 direct dependent • 1 total dependent
/ InlineX::C2XS

NAME

InlineX::C2XS - Convert from Inline C code to XS.

SYNOPSIS

use InlineX::C2XS qw(c2xs);

my $module_name = 'MY::XS_MOD';
my $package_name = 'MY::XS_MOD';

# $build_dir is an optional third arg
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 = {'AUTOWRAP' => 1,
                   'AUTO_INCLUDE' => 'my_header.h',
                   'TYPEMAPS' => ['my_typemap'],
                   'INC' => '-Imy/includes/dir',
                   'WRITE_MAKEFILE_PL' => 1,
                   'VERSION' => 0.42,
                   'LIBS' => ['-L/somewhere -lmylib'],
                   'BUILD_NOISY' => 0, # No Inline::C progress messages
                  };

# Create /some/where/else/XS_MOD.xs from ./src/XS_MOD.c
c2xs($module_name, $package_name, $build_dir);

# Or create XS_MOD.xs in the cwd:
c2xs($module_name, $package_name);

The optional fourth arg (a reference to a hash) is to enable the
writing of XS files using Inline::C's autowrap capability - and
also to enable the creation of the Makefile.PL (if desired).
See the "Recognised Hash Keys" section below.

# Create XS_MOD.xs in the cwd, using the AUTOWRAP feature:
c2xs($module_name, $package_name, '.', $config_opts);

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 file 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");
 }

InlineX::C2XS looks for the 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 INLINE.h) will be written to the cwd unless a third 
argument (specifying a valid directory) is provided to the c2xs
function

The created XS file, when packaged with the '.pm' file, 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 are recognised:

 AUTO_INCLUDE
  The value specified is automatically inserted into the generated XS
  file. (Also, the specified include will be parsed 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.
  (There's no point in specifying a false value, as "false" is the 
  default anyway.) 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},
 ----

 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',
 ----

 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.
  (Must be an array reference.) eg
  
   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_',
 ----

 TYPEMAPS
  The value(s) specified are added to the list of typemaps. It makes
  sense to assign this key only when AUTOWRAP and/or WRITE_MAKEFILE_PL
  are set to a true value. (Must be an array reference.) eg:

   TYPEMAPS =>['my_typemap', 'my_other_typemap'],
 ----

 VERSION
  Set this to the version number of the module. It makes sense to assign
  this key only if WRITE_MAKEFILE_PL 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. (There's no point in specifying a false value, as "false"
  is the default anyway. You should also assign the 'VERSION' key to 
  the correct value when WRITE_MAKEFILE_PL is set.) eg:
   
   WRITE_MAKEFILE_PL => 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 org

COPYRIGHT

Copyright Sisyphus. You can do whatever you want with this code.
It comes without any guarantee or warranty.