NAME
Inline::Module::LeanDist - Develop your module with Inline but distribute lean XS
SYNOPSIS
In your module (say Acme::Math::XS::LeanDist):
use Inline::Module::LeanDist C => 'DATA';This module forwards all its parameters to Inline.
NOTE: Currently the entire use statement must be on one line! The DATA section is generally the best place to put your code (heredocs won't work).
In Makefile.PL:
use ExtUtils::MakeMaker;
use Inline::Module::LeanDist::MakefilePL;
WriteMakefile(
NAME => 'Acme::Math::XS::LeanDist',
OBJECT => '',
postamble => {
inline => {
file => 'lib/Acme/Math/XS/LeanDist.pm',
},
},
);NOTE: The postamble.inline.file parameter should be the filename of your module that is using Inline, and you must have an OBJECT parameter in the WriteMakefile arguments.
DESCRIPTION
This module is heavily inspired by Inline::Module. I wrote it because I wanted to be able to use Inline during development, but ship distributions that have no dependencies on Inline or any other module (for example Inline::Filters and its plugins). I wanted to ship distributions that were (from the user's perspective) identical to XS dists I would have created by hand (without Inline).
Essentially, Inline compiles your code at run-time meaning all compilation dependencies are required then. Inline::Module pushes the compilation dependency requirements back to distribution build time. However, Inline::Module::LeanDist goes one step futher and pushes back the compilation dependencies to distribution creation time (except for a regular XS tool-chain).
The advantage of the Inline::Module approach over Inline is that start-up time is faster for your modules since the fairly heavy-weight Inline system isn't loaded, and a compiled version is always available no matter what the state of your .inline directory is (or which user is running the program or file-system permissions, etc).
Inline::Module::LeanDist has all of these advantages as well as some additional ones: Downloading and installing Inline is not necessary to build the distribution. This also goes for any other dependencies (such as the ragel binary required by Inline::Filters::Ragel). Also, you don't need to worry about updates to Inline/Inline::Module/etc breaking your distribution (though note that Inline::Module recommends avoiding this by bundling the multi-hundreds of KB Inline tool-chain with every distribution). Finally, with Inline::Module::LeanDist you don't need to mess around with awkward "stub" packages.
However, Inline::Module will likely work for more ILSMs. This module has only been tested with Inline::C so far. Also, although it's a bit subjective, in my opinion Inline::Module is slightly nicer to develop with since it always puts the .so files into blib/ which is more "normal" than the .inline directory (and of course make actually compiles your code).
HOW DOES IT WORK?
Basically it's all a huge hack. :)
During development time, the Inline::Module::LeanDist forwards all its parameters to Inline so you develop with normal Inline practices.
However, Inline::Module::LeanDist::MakefilePL modifies Makefile.PL so that at make dist time, it will comment out the use Inline::Module::LeanDist::MakefilePL; line in Makefile.PL. It will also comment out the use Inline::Module::LeanDist ... line in your module and replace it with an XSLoader invocation. Finally, it copies the generated .xs file from the .inline directory into the distribution and adds this to the OBJECT parameter in Makefile.PL (as well as the dist's MANIFEST).
The consequence of all this hacking is that the created distributions are lean, XS-only distributions.
EXAMLES
Acme::Math::XS::LeanDist - This is a very simple example in the style of Acme::Math::XS and co.
Unicode::Truncate - This is an actually somewhat useful module that doubles as a proof of concept for Inline::Module::LeanDist and Inline::Filters::Ragel.
BUGS
It really ought to be possible to have multiple separate files in a single dist that use Inline, but this is not yet supported.
It should support Build.PL in addition to Makefile.PL.
It shoud be possible to do something like this with C++.
SEE ALSO
Inline-Module-LeanDist github repo
AUTHOR
Doug Hoyte, <doug@hcsw.org>
COPYRIGHT & LICENSE
Copyright 2015 Doug Hoyte.
This module is licensed under the same terms as perl itself.