NAME

InlineX::C2XS - create an XS file from Inline C code.

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

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

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

 AUTO_INCLUDE
  The value specified is automatically inserted into the generated XS
  file. (Also, the specified include will be parsed and acted upon iff
  AUTOWRAP is set to a true value.) eg:

   AUTO_INCLUDE => '#include <my_header.h>',
 ----

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

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

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

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

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

 

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.