GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  INLINEX::C2XS (3)

.ds Aq ’

NAME

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

CONTENTS

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 thats 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, its deemed to be the build directory
  unless its a hash reference (in which case its deemed to be the
  hash reference containing the additional config options).

  As of version 0.19, a c2xs utility is also provided. Its just an
  Inline::C2XS wrapper - see c2xs --help.

  context($xs_file, \@func);
   Call context() after running c2xs() if and only if youve 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.

    Dont 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, dont 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. Its only the functions
    that make use of perls 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. Its 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 thats 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



 Dont feed an actual Inline::C script to this module - it wont
 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
 thats 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 its 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::Cs 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
   youll 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
   youll 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.
   Youll also need to assign the VERSION key appropriately.
   Note that its 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,Sisyphus



AUTHOR



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



Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 C2XS (3) 2014-07-27

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.