NAME

    Inline::Module - Support for Inline-based CPAN Extension Modules

VERSION

    This document describes Inline::Module version 0.34. ";

SYNOPSIS

    In your module (say Acme::Math::XS):

        use Acme::Math::XS::Inline C =>
          "long add(long a, long b) { return a + b; }";

    In Makefile.PL:

        use lib 'inc';
        use ExtUtils::MakeMaker;
        use Inline::Module;
    
        WriteMakefile(
          NAME => 'Acme::Math::XS',
          postamble => {
            inline => {
              module => 'Acme::Math::XS',
              stub => 'Acme::Math::XS::Inline',
              ilsm => 'Inline::C',
              makestub => 1,
            },
          },
        );

DESCRIPTION

    This module provides support and documentation for creating and
    maintaining CPAN extension modules. ie Writing XS modules without
    having to learn XS.

    The Inline::Module::Tutorial explains the simple processes involved.

    When used from a Makefile.PL, this module provides support for
    modifying the Makefile generated by ExtUtils::MakeMaker.

    You just need to provide a postamble section. See below.

    You also need to make sure that the inc/ directory is in @INC. This is
    where the build tools will be when your module is shipped to CPAN.

 postamble Section

    Arguments are key/value pairs.

    module

          module => 'My::Module',

      Required. This is the module that contains inline C or C++ code. It
      can be an array ref of multiple modules.

    stub

          stub => 'My::Module::Inline',

      Optional. This is the name of the Inline::Module generated stub
      module. It's value defaults to the module argument with '::Inline'
      appended. It can be an array ref of multiple modules.

    ilsm

          ilsm => 'Inline::CPP',

      Optional. This is the Inline Language Support Module (ilsm) that you
      are using. It defaults to Inline::C. It can be an array ref of
      multiple ilsm-s.

    makestub

          makestub => 1,

      This will cause the stubs to be updated every time the Makefile.PL is
      run.

    bundle

          bundle => 0,

      By default Inline::Module will bundle all the dependencies under your
      distribution's inc/ directory. Setting this option to 0 will disable
      that, but then you are responsible for declaring all the dependencies
      yourself. Do this with the knowledge that if Inline::* APIs change,
      your distribution may break.

STUB MODULE GENERATION

    During development, Inline::Module needs to generate stub modules. For
    the case in the synopsis, it would need to generate
    Acme::Math::XS::Inline. There a couple ways to do this. The explicit
    way is:

        perl -MInline::Module=makestub,Acme::Math::XS::Inline

    You can also add makestub => 1 to your Makefile.PL inline section.
    Every time you run perl Makefile.PL as an author, the stubs will be
    generated under the lib/ directory.

GENERATED FILES

    When Inline is invoked it will use the .inline/ directory to do it.
    This is temporary build cache directory. You may want to add .inline/
    to your .gitignore (or similar) file.

    You may also want to add the stub file paths to .gitignore. You may
    also want to consider committing them. Even though they are generated
    code, they are very small and should almost never change. Committing
    them may be easier for your collaborating developers.

TPF GRANT

    This module was written as the major portion of the work for a 2014
    Perl Foundation grant:

    http://news.perlfoundation.org/2014/09/grant-proposal-inlinecpp-modul.h
    tml

SEE ALSO

      * Inline::Module::Tutorial

      * Inline

      * Inline::C

      * Inline::CPP

    Also see these modules made with Inline::Module:

      * Alt::Acme::Math::XS::EUMM

	* Acme::Math::XS (Pure XS version)

      * Alt::Acme::Math::XS::CPP

      * Alt::Acme::Math::XS::DistZilla

      * Alt::Acme::Math::XS::ModuleBuild

      * Alt::Acme::Math::XS::ModuleInstall

      * Alt::Acme::Math::XS::ZillaDist

      * Alt::Acme::Math::XS::External

      * Alt::Devel::GlobalDestruction::XS::Inline

      * Alt::Math::Prime::FastSieve::Inline

    And see these plugins for your favorite module framework:

      * DistZilla::Plugin::InlineModule

      * Module::Build::InlineModule

      * Module::Install::InlineModule

NOTE

    When this module was first created in November 2014, we belatedly
    realized that there was already an Inline::Module on CPAN, by Ingy. The
    other one is to "inline" one module inside another. It appears that
    nobody uses the old one, but if that is not the case, contact INGY and
    he'll redo that one under another name.

AUTHOR

    Ingy döt Net <ingy@cpan.org>

COPYRIGHT AND LICENSE

    Copyright 2014-2015. Ingy döt Net.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html