—

              
HideShow 214 lines of Pod
=pod
=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.38.
See http://github.com/ingydotnet/swim-pm#readme
=encoding utf8
=head1 NAME
Inline::Module - Support for Inline-based CPAN Extension Modules
=for html
<a href="https://travis-ci.org/ingydotnet/inline-module-pm"><img src="https://travis-ci.org/ingydotnet/inline-module-pm.png" alt="inline-module-pm"></a>
=head1 VERSION
This document describes L<Inline::Module> version B<0.34>.
";
=head1 SYNOPSIS
In your module (say C<Acme::Math::XS>):
    use Acme::Math::XS::Inline C =>
      "long add(long a, long b) { return a + b; }";
In C<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,
        },
      },
    );
=head1 DESCRIPTION
This module provides support and documentation for creating and maintaining
CPAN extension modules. ie Writing XS modules without having to learn XS.
The L<Inline::Module::Tutorial> explains the simple processes involved.
When used from a C<Makefile.PL>, this module provides support for modifying
the Makefile generated by L<ExtUtils::MakeMaker>.
You just need to provide a C<postamble> section. See below.
You also need to make sure that the C<inc/> directory is in C<@INC>. This is
where the build tools will be when your module is shipped to CPAN.
=head2 postamble Section
Arguments are key/value pairs.
=over
=item C<module>
    module => 'My::Module',
Required. This is the module that contains inline C<C> or C<C++> code. It can
be an array ref of multiple modules.
=item C<stub>
    stub => 'My::Module::Inline',
Optional. This is the name of the Inline::Module generated stub module. It's
value defaults to the C<module> argument with '::Inline' appended. It can be
an array ref of multiple modules.
=item C<ilsm>
    ilsm => 'Inline::CPP',
Optional. This is the Inline Language Support Module (ilsm) that you are
using. It defaults to L<Inline::C>. It can be an array ref of multiple ilsm-s.
=item C<makestub>
    makestub => 1,
This will cause the stubs to be updated every time the C<Makefile.PL> is run.
=item C<bundle>
    bundle => 0,
By default Inline::Module will bundle all the dependencies under your
distribution's C<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.
=back
=head1 STUB MODULE GENERATION
During development, L<Inline::Module> needs to generate I<stub> modules. For
the case in the synopsis, it would need to generate C<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 C<< makestub => 1 >> to your C<Makefile.PL> inline section.
Every time you run C<perl Makefile.PL> as an author, the stubs will be
generated under the C<lib/> directory.
=head1 GENERATED FILES
When Inline is invoked it will use the C<.inline/> directory to do it. This is
temporary build cache directory. You may want to add C<.inline/> to your
C<.gitignore> (or similar) file.
You may also want to add the stub file paths to C<.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.
=head1 TPF GRANT
This module was written as the major portion of the work for a 2014 Perl
Foundation grant:
L<http://news.perlfoundation.org/2014/09/grant-proposal-inlinecpp-modul.html>
=head1 SEE ALSO
=over
=item * L<Inline::Module::Tutorial>
=item * L<Inline>
=item * L<Inline::C>
=item * L<Inline::CPP>
=back
Also see these modules made with L<Inline::Module>:
=over
=item * L<Alt::Acme::Math::XS::EUMM>
=over
=item * L<Acme::Math::XS> (Pure XS version)
=back
=item * L<Alt::Acme::Math::XS::CPP>
=item * L<Alt::Acme::Math::XS::DistZilla>
=item * L<Alt::Acme::Math::XS::ModuleBuild>
=item * L<Alt::Acme::Math::XS::ModuleInstall>
=item * L<Alt::Acme::Math::XS::ZillaDist>
=item * L<Alt::Acme::Math::XS::External>
=item * L<Alt::Devel::GlobalDestruction::XS::Inline>
=item * L<Alt::Math::Prime::FastSieve::Inline>
=back
And see these plugins for your favorite module framework:
=over
=item * L<DistZilla::Plugin::InlineModule>
=item * L<Module::Build::InlineModule>
=item * L<Module::Install::InlineModule>
=back
=head1 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.
=head1 AUTHOR
Ingy döt Net <ingy@cpan.org>
=head1 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 L<http://www.perl.com/perl/misc/Artistic.html>
=cut