.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Inline::FAQ 3pm"
.TH Inline::FAQ 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Inline\-FAQ \- The Inline FAQ
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Welcome to the official Inline \s-1FAQ.\s0 In this case, \fB\s-1FAQ\s0\fR means: \fBFormerly
Answered Questions\fR
.PP
This is a collection of old, long-winded emails that myself and others have
sent to the Inline mailing list. (inline@perl.org) They have been reviewed and
edited for general Inline edification. Some of them may be related to a
specific language. They are presented here in a traditional \s-1FAQ\s0 layout.
.SH "GENERAL INLINE"
.IX Header "GENERAL INLINE"
Since there is only a handful of content so far, all FAQs are currently under
this heading.
.ie n .SS "How disposable is a "".Inline"" or ""_Inline"" directory?"
.el .SS "How disposable is a \f(CW.Inline\fP or \f(CW_Inline\fP directory?"
.IX Subsection "How disposable is a .Inline or _Inline directory?"
I probably need to be more emphatic about the role of \f(CW\*(C`_Inline/\*(C'\fR cache
directories. Since they are created automatically, they are completely
disposable. I delete them all the time. And it is fine to have a different one
for each project. In fact as long as you don't have \f(CW\*(C`~/.Inline/\*(C'\fR defined,
Inline will create a new \f(CW\*(C`./_Inline\*(C'\fR directory (unless, you've done something
to override this automatic process \- such as using the \s-1DIRECTORY\s0 config
option, or using the \f(CW\*(C`PERL_INLINE_DIRECTORY\*(C'\fR environment variable). You can
move that to \f(CW\*(C`./.Inline\*(C'\fR and it will continue to work if you want togive it
more longevity and hide it from view. There is a long complicated list of
rules about how \f(CW\*(C`[_.]Inline/\*(C'\fR directories are used/created. But it was
designed to give you the most flexibility/ease\-of\-use. Never be afraid to nuke
\&'em. They'll just pop right back next time they're needed. :)
.SS "What is the best way to package Inline code for \s-1CPAN\s0?"
.IX Subsection "What is the best way to package Inline code for CPAN?"
This distribution includes Inline::MakeMaker, described below, which takes
special steps during the installation of your module to make sure the code
gets compiled and installed, rather than compiled by users at runtime. But,
users of your module need to install Inline and the language support module
like Inline::CPP as prerequisites for your module.
.PP
A better way to distribute your module is with Inline::Module, which takes
special steps to remove dependencies on Inline::* and convert it to a plain \s-1XS\s0
module during the construction of your distribution before you upload it to
\&\s-1CPAN.\s0 It also integrates easily with Dist::Zilla and other modern authoring
tools for a more streamlined authoring experience.
.ie n .SS "Whatever happened to the ""SITE_INSTALL"" option?"
.el .SS "Whatever happened to the \f(CWSITE_INSTALL\fP option?"
.IX Subsection "Whatever happened to the SITE_INSTALL option?"
\&\f(CW\*(C`SITE_INSTALL\*(C'\fR is gone. I was going to leave it in and change the semantics,
but thought it better to remove it, so people wouldn't try to use it the old
way. There is now \f(CW\*(C`_INSTALL_\*(C'\fR (but you're not supposed to know that :). It
works magically through the use of Inline::MakeMaker. I explained this earlier
but it's worth going through again because it's the biggest change for 0.40.
Here's how to 'permanently' install an Inline extension (Inline based module)
with 0.40:
.IP "1." 4
Create a module with Inline.
.IP "2." 4
Test it using the normal / local \f(CW\*(C`_Inline/\*(C'\fR cache.
.IP "3." 4
Create a Makefile.PL (like the one produced by h2xs)
.IP "4." 4
Change 'use ExtUtils::MakeMaker' to 'use Inline::MakeMaker'
.IP "5." 4
In the Makefile.PL's \fBWriteMakefile()\fR insert:
.Sp
.Vb 4
\& CONFIGURE_REQUIRES => {
\& \*(AqInline::MakeMaker\*(Aq => 0.45,
\& \*(AqExtUtils::MakeMaker\*(Aq => 6.52,
\& },
.Ve
.Sp
(See the \*(L"Writing Modules with Inline\*(R" section of Inline.pod for an
explanation / elaboration.)
.IP "6." 4
Change your 'use Inline C => \s-1DATA\s0' to 'use Inline C => \s-1DATA\s0 => \s-1NAME\s0 => Foo
.PP
=> \s-1VERSION\s0 => 1.23' + Make sure \s-1NAME\s0 matches your package name ('Foo'), or
=> begins with 'Foo::'. + If you want to quiet a harmless warning that will
=> appear when the module is loaded via \*(L"require\*(R", do \*(L"Inline\->\fBinit()\fR;\*(R". See
=> \*(L"Writing Modules with Inline\*(R" in the Inline pod for details. + Make sure
=> \s-1VERSION\s0 matches \f(CW$Foo::VERSION\fR. This must be a string (not a number)
=> matching \f(CW\*(C`/^\ed\e.\ed\ed$/\*(C'\fR + Do the perl / make / test / install dance
=> (thanks binkley :)
.PP
With Inline 0.41 (or thereabouts) you can skip steps 3 & 4, and just say
\&\f(CW\*(C`perl \-MInline=INSTALL ./Foo.pm\*(C'\fR. This will work for non-Inline modules too.
It will become the defacto standard (since there is no easy standard) way of
installing a Perl module. It will allow Makefile.PL parameters \f(CW\*(C`perl \-
MInline=INSTALL ./Foo.pm \- PREFIX=/home/ingy/perl\*(C'\fR and things like that. It
will also make use of a \s-1MANIFEST\s0 if you provide one.
.SS "How do I create a binary distribution using Inline?"
.IX Subsection "How do I create a binary distribution using Inline?"
I've figured out how to create and install a \s-1PPM\s0 binary distribution;
with or without distributing the C code! And I've decided to share it
with all of you :)
.PP
\&\s-1NOTE:\s0 Future versions of Inline will make this process a one line command. But
for now just use this simple recipe.
.PP
The Inline 0.40 distribution comes with a sample extension module called
Math::Simple. Theoretically you could distribute this module on \s-1CPAN.\s0 It has
all the necessary support for installation. You can find it in \f(CW\*(C`Inline\-
0.40/modules/Math/Simple/\*(C'\fR. Here are the steps for converting this into a
binary distribution \fBwithout\fR C source code.
.PP
\&\s-1NOTE:\s0 The recipient of this binary distribution will need to have the
\s-1PPM\s0.pm module installed. This module requires a lot of other \s-1CPAN\s0
modules. ActivePerl (available for Win32, Linux, and Solaris) has all
of these bundled. While ActivePerl isn't required, it makes things (a
lot) easier.
.IP "1." 4
cd \f(CW\*(C`Inline\-0.40/Math/Simple/\*(C'\fR
.IP "2." 4
Divide Simple.pm into two files:
.Sp
.Vb 7
\& \-\-\-8<\-\-\- (Simple.pm)
\& package Math::Simple;
\& use strict;
\& require Exporter;
\& @Math::Simple::ISA = qw(Exporter);
\& @Math::Simple::EXPORT = qw(add subtract);
\& $Math::Simple::VERSION = \*(Aq1.23\*(Aq;
\&
\& use Inline (C => \*(Aqsrc/Simple.c\*(Aq =>
\& NAME => \*(AqMath::Simple\*(Aq,
\& VERSION => \*(Aq1.23\*(Aq,
\& );
\& 1;
\& \-\-\-8<\-\-\-
\& \-\-\-8<\-\-\- (src/Simple.c)
\& int add (int x, int y) {
\& return x + y;
\& }
\&
\& int subtract (int x, int y) {
\& return x \- y;
\& }
\& \-\-\-8<\-\-\-
.Ve
.IP "3." 4
now you have the Perl in one file and the C in the other. The C code must be
.PP
in a subdirectory. + Note that I also changed the term '\s-1DATA\s0' to the name of
the C file. This will work just as if the C were still inline. + Run 'perl
Makefile.PL' + Run 'make test' + Get the \s-1MD5\s0 key from
\&\f(CW\*(C`blib/arch/auto/Math/Simple/Simple.inl\*(C'\fR + Edit \f(CW\*(C`blib/lib/Math/Simple.pm\*(C'\fR.
Change \f(CW\*(C`src/Simple.c\*(C'\fR to \f(CW\*(C`02c61710cab5b659efc343a9a830aa73\*(C'\fR (the \s-1MD5\s0 key)
.IP "1." 4
Run 'make ppd'
.IP "2." 4
Edit 'Math\-Simple.ppd'. Fill in \s-1AUTHOR\s0 and \s-1ABSTRACT\s0 if you wish. Then
.PP
change:
.PP
.Vb 1
\&
\&
\& to
\&
\&
.Ve
.IP "1." 4
Run:
.Sp
.Vb 2
\& tar cvf Math\-Simple.tar blib
\& gzip \-\-best Math\-Simple.tar
.Ve
.IP "2." 4
Run:
.Sp
.Vb 2
\& tar cvf Math\-Simple\-1.23.tar Math\-Simple.ppd Math\-Simple.tar.gz
\& gzip \-\-best Math\-Simple\-1.23.tar
.Ve
.IP "3." 4
Distribute Math\-Simple\-1.23.tar.gz with the following instructions:
.RS 4
.IP "1." 4
Run:
.Sp
gzip \-d Math\-Simple\-1.23.tar.gz tar xvzf Math\-Simple\-1.23.tar
.IP "2." 4
Run 'ppm install Math\-Simple.ppd'
.IP "3." 4
Delete Math\-Simple.tar and Math\-Simple.ppd.
.IP "4." 4
Test with:
.Sp
perl \-MMath::Simple \-le 'print add(37, 42)'
.RE
.RS 4
.RE
.PP
That's it. The process should also work with zip instead of tar, but I
haven't tried it.
.PP
The recipient of the binary must have Perl built with a matching architecture.
Luckily, ppm will catch this.
.PP
For a binary dist \fBwith\fR C source code, simply omit steps 2, 3, 6, and 7.
.PP
If this seems too hard, then in a future version you should be able to
just type:
.PP
.Vb 1
\& make ppm
.Ve
.ie n .SS "Why does ""C/t/09parser.t"" fail on Cygwin ?"
.el .SS "Why does \f(CWC/t/09parser.t\fP fail on Cygwin ?"
.IX Subsection "Why does C/t/09parser.t fail on Cygwin ?"
It doesn't always fail on Cygwin, but if you find that it produces \*(L"unable to
remap .... to same address as parent\*(R" errors during the build phase, then it's
time for you to run rebaseall.
.PP
See
and, if needed, seek further help from the Cygwin mailing list.