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

  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 org

LICENSE

  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 Sisyphus

AUTHOR

    Sisyphus <sisyphus at(@) cpan dot (.) org>