.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "alienfile 3"
.TH alienfile 3 2024-06-12 "perl v5.38.2" "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
alienfile \- Specification for defining an external dependency for CPAN
.SH VERSION
.IX Header "VERSION"
version 2.83
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Do-it-yourself approach:
.PP
.Vb 1
\& use alienfile;
\& 
\& probe [ \*(Aqpkg\-config \-\-exists libarchive\*(Aq ];
\& 
\& share {
\& 
\&   start_url \*(Aqhttp://libarchive.org/downloads/libarchive\-3.2.2.tar.gz\*(Aq;
\& 
\&   # the first one which succeeds will be used
\&   download [ \*(Aqwget %{.meta.start_url}\*(Aq ];
\&   download [ \*(Aqcurl \-o %{.meta.start_url}\*(Aq ];
\& 
\&   extract [ \*(Aqtar xf %{.install.download}\*(Aq ];
\& 
\&   build [
\&     # Note: will not work on Windows, better to use Build::Autoconf plugin
\&     # if you need windows support
\&     \*(Aq./configure \-\-prefix=%{.install.prefix} \-\-disable\-shared\*(Aq,
\&     \*(Aq%{make}\*(Aq,
\&     \*(Aq%{make} install\*(Aq,
\&   ];
\& }
\& 
\& gather [
\&   [ \*(Aqpkg\-config\*(Aq, \*(Aq\-\-modversion\*(Aq, \*(Aqlibarchive\*(Aq, \e\*(Aq%{.runtime.version}\*(Aq ],
\&   [ \*(Aqpkg\-config\*(Aq, \*(Aq\-\-cflags\*(Aq,     \*(Aqlibarchive\*(Aq, \e\*(Aq%{.runtime.cflags}\*(Aq  ],
\&   [ \*(Aqpkg\-config\*(Aq, \*(Aq\-\-libs\*(Aq,       \*(Aqlibarchive\*(Aq, \e\*(Aq%{.runtime.libs}\*(Aq    ],
\& ];
.Ve
.PP
With plugins (better):
.PP
.Vb 1
\& use alienfile;
\& 
\& plugin \*(AqPkgConfig\*(Aq => \*(Aqlibarchive\*(Aq;
\& 
\& share {
\&   start_url \*(Aqhttp://libarchive.org/downloads/\*(Aq;
\&   plugin Download => (
\&     filter => qr/^libarchive\-.*\e.tar\e.gz$/,
\&     version => qr/([0\-9\e.]+)/,
\&   );
\&   plugin Extract => \*(Aqtar.gz\*(Aq;
\&   plugin \*(AqBuild::Autoconf\*(Aq;
\&   plugin \*(AqGather::IsolateDynamic\*(Aq;
\&   build [
\&     \*(Aq%{configure}\*(Aq,
\&     \*(Aq%{make}\*(Aq,
\&     \*(Aq%{make} install\*(Aq,
\&   ];
\& };
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An alienfile is a recipe used by Alien::Build to, probe for system libraries or download from the internet, and build source
for those libraries.  This document acts as reference for the alienfile system, but if you are starting out writing your own Alien
you should read Alien::Build::Manual::AlienAuthor, which will teach you how to write your own complete Alien using alienfile +
Alien::Build + ExtUtils::MakeMaker.  Special attention should be taken to the section "a note about dynamic vs. static
libraries".
.SH DIRECTIVES
.IX Header "DIRECTIVES"
.SS requires
.IX Subsection "requires"
"any" requirement (either share or system):
.PP
.Vb 2
\& requires $module;
\& requires $module => $version;
.Ve
.PP
configure time requirement:
.PP
.Vb 4
\& configure {
\&   requires $module;
\&   requires $module => $version;
\& };
.Ve
.PP
system requirement:
.PP
.Vb 4
\& sys {
\&   requires $module;
\&   requires $module => $version;
\& };
.Ve
.PP
share requirement:
.PP
.Vb 4
\& share {
\&   requires $module;
\&   requires $module => $version;
\& };
.Ve
.PP
specifies a requirement.  Alien::Build takes advantage of dynamic requirements, so only
modules that are needed for the specific type of install need to be loaded.  Here are the
different types of requirements:
.IP configure 4
.IX Item "configure"
Configure requirements should already be installed before the alienfile is loaded.
.IP any 4
.IX Item "any"
"Any" requirements are those that are needed either for the probe stage, or in either the
system or share installs.
.IP share 4
.IX Item "share"
Share requirements are those modules needed when downloading and building from source.
.IP system 4
.IX Item "system"
System requirements are those modules needed when the system provides the library or tool.
.SS plugin
.IX Subsection "plugin"
.Vb 2
\& plugin $name => (%args);
\& plugin $name => $arg;
.Ve
.PP
Load the given plugin.  If you prefix the plugin name with an \f(CW\*(C`=\*(C'\fR sign,
then it will be assumed to be a fully qualified path name.  Otherwise the
plugin will be assumed to live in the \f(CW\*(C`Alien::Build::Plugin\*(C'\fR namespace.
If there is an appropriate negotiate plugin, that one will be loaded.
Examples:
.PP
.Vb 4
\& # Loads Alien::Build::Plugin::Fetch::Negotiate
\& # which will pick the best Alien::Build::Plugin::Fetch
\& # plugin based on the URL, and system configuration
\& plugin \*(AqFetch\*(Aq => \*(Aqhttp://ftp.gnu.org/gnu/gcc\*(Aq;
\& 
\& # loads the plugin with the badly named class!
\& plugin \*(Aq=Badly::Named::Plugin::Not::In::Alien::Build::Namespace\*(Aq;
\& 
\& # explicitly loads Alien::Build::Plugin::Prefer::SortVersions
\& plugin \*(AqPrefer::SortVersions\*(Aq => (
\&   filter => qr/^gcc\-.*\e.tar\e.gz$/,
\&   version => qr/([0\-9\e.]+)/,
\& );
.Ve
.SS probe
.IX Subsection "probe"
.Vb 2
\& probe \e&code;
\& probe \e@commandlist;
.Ve
.PP
Instructions for the probe stage.  May be either a code reference, or a command list.
Multiple probes and probe plugins can be given.  These will be used in sequence,
stopping at the first that detects a system installation.  Alien::Build will use
a share install if no system installation is detected by the probes.
.SS configure
.IX Subsection "configure"
.Vb 3
\& configure {
\&   ...
\& };
.Ve
.PP
Configure block.  The only directive allowed in a configure block is
requires.
.SS sys
.IX Subsection "sys"
.Vb 3
\& sys {
\&   ...
\& };
.Ve
.PP
System block.  Allowed directives are: requires and gather.
.SS share
.IX Subsection "share"
.Vb 3
\& share {
\&   ...
\& };
.Ve
.PP
System block.  Allowed directives are: download, fetch, decode, prefer, extract, build, gather.
.SS start_url
.IX Subsection "start_url"
.Vb 3
\& share {
\&   start_url $url;
\& };
.Ve
.PP
Set the start URL for download.  This should be the URL to an index page, or the actual tarball of the source.
.SS digest
.IX Subsection "digest"
[experimental]
.PP
.Vb 3
\& share {
\&   digest $algorithm, $digest;
\& };
.Ve
.PP
Check fetched and downloaded files against the given algorithm and
digest.  Typically you will want to use SHA256 as the algorithm.
.SS download
.IX Subsection "download"
.Vb 4
\& share {
\&   download \e&code;
\&   download \e@commandlist;
\& };
.Ve
.PP
Instructions for the download stage.  May be either a
code reference, or a command list.
.SS fetch
.IX Subsection "fetch"
.Vb 4
\& share {
\&   fetch \e&code;
\&   fetch \e@commandlist;
\& };
.Ve
.PP
Instructions for the fetch stage.  May be either a
code reference, or a command list.
.SS decode
.IX Subsection "decode"
.Vb 4
\& share {
\&   decode \e&code;
\&   decode \e@commandlist;
\& };
.Ve
.PP
Instructions for the decode stage.  May be either a
code reference, or a command list.
.SS prefer
.IX Subsection "prefer"
.Vb 4
\& share {
\&   prefer \e&code;
\&   prefer \e@commandlist;
\& };
.Ve
.PP
Instructions for the prefer stage.  May be either a
code reference, or a command list.
.SS extract
.IX Subsection "extract"
.Vb 4
\& share {
\&   extract \e&code;
\&   extract \e@commandlist;
\& };
.Ve
.PP
Instructions for the extract stage.  May be either a
code reference, or a command list.
.SS patch
.IX Subsection "patch"
.Vb 4
\& share {
\&   patch \e&code;
\&   patch \e@commandlist;
\& };
.Ve
.PP
Instructions for the patch stage.  May be either a
code reference, or a command list.
.SS patch_ffi
.IX Subsection "patch_ffi"
.Vb 4
\& share {
\&   patch_ffi \e&code;
\&   patch_ffi \e@commandlist;
\& };
.Ve
.PP
[DEPRECATED]
.PP
Instructions for the patch_ffi stage.  May be either a
code reference, or a command list.
.SS build
.IX Subsection "build"
.Vb 4
\& share {
\&   build \e&code;
\&   build \e@commandlist;
\& };
.Ve
.PP
Instructions for the build stage.  May be either a
code reference, or a command list.
.SS build_ffi
.IX Subsection "build_ffi"
.Vb 4
\& share {
\&   build \e&code;
\&   build \e@commandlist;
\& };
.Ve
.PP
[DEPRECATED]
.PP
Instructions for the build FFI stage.  Builds shared libraries instead of static.
This is optional, and is only necessary if a fresh and separate build needs to be
done for FFI.
.SS gather
.IX Subsection "gather"
.Vb 2
\& gather \e&code;
\& gather \e@commandlist;
\& 
\& share {
\&   gather \e&code;
\&   gather \e@commandlist;
\& };
\& 
\& sys {
\&   gather \e&code;
\&   gather \e@commandlist;
\& };
.Ve
.PP
Instructions for the gather stage.  May be either a code reference, or a command list.
In the root block of the alienfile it will trigger in both share and system build.
In the share or sys block it will only trigger in the corresponding build.
.SS gather_ffi
.IX Subsection "gather_ffi"
.Vb 4
\& share {
\&   gather_ffi \e&code;
\&   gather_ffi \e@commandlist;
\& }
.Ve
.PP
[DEPRECATED]
.PP
Gather specific to \f(CW\*(C`build_ffi\*(C'\fR.  Not usually necessary.
.SS ffi
.IX Subsection "ffi"
.Vb 10
\& share {
\&   ffi {
\&     patch \e&code;
\&     patch \e@commandlist;
\&     build \e&code;
\&     build \e@commandlist;
\&     gather \e&code;
\&     gather \e@commandlist;
\&   }
\& }
.Ve
.PP
Specify patch, build or gather stages related to FFI.
.SS meta_prop
.IX Subsection "meta_prop"
.Vb 1
\& my $hash = meta_prop;
.Ve
.PP
Get the meta_prop hash reference.
.SS meta
.IX Subsection "meta"
.Vb 1
\& my $meta = meta;
.Ve
.PP
Returns the meta object for your alienfile.  For methods that can be used on the
meta object, see "META METHODS" in Alien::Build.
.SS log
.IX Subsection "log"
.Vb 1
\& log($message);
.Ve
.PP
Prints the given log to stdout.
.SS test
.IX Subsection "test"
.Vb 8
\& share {
\&   test \e&code;
\&   test \e@commandlist;
\& };
\& sys {
\&   test \e&code;
\&   test \e@commandlist;
\& };
.Ve
.PP
Run the tests
.SS before
.IX Subsection "before"
.Vb 1
\& before $stage => \e&code;
.Ve
.PP
Execute the given code before the given stage.  Stage should be one of
\&\f(CW\*(C`probe\*(C'\fR, \f(CW\*(C`download\*(C'\fR, \f(CW\*(C`fetch\*(C'\fR, \f(CW\*(C`decode\*(C'\fR, \f(CW\*(C`prefer\*(C'\fR, \f(CW\*(C`extract\*(C'\fR,
\&\f(CW\*(C`patch\*(C'\fR, \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`gather\*(C'\fR.
.PP
The before directive is only legal in the same blocks as the stage would
normally be legal in.  For example, you can't do this:
.PP
.Vb 1
\& use alienfile;
\& 
\& sys {
\&   before \*(Aqbuild\*(Aq => sub {
\&     ...
\&   };
\& };
.Ve
.PP
Because a \f(CW\*(C`build\*(C'\fR wouldn't be legal inside a \f(CW\*(C`sys\*(C'\fR block.
.SS after
.IX Subsection "after"
.Vb 1
\& after $stage => \e&code;
.Ve
.PP
Execute the given code after the given stage.  Stage should be one of
\&\f(CW\*(C`probe\*(C'\fR, \f(CW\*(C`download\*(C'\fR, \f(CW\*(C`fetch\*(C'\fR, \f(CW\*(C`decode\*(C'\fR, \f(CW\*(C`prefer\*(C'\fR, \f(CW\*(C`extract\*(C'\fR,
\&\f(CW\*(C`patch\*(C'\fR, \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`gather\*(C'\fR.
.PP
The after directive is only legal in the same blocks as the stage would
normally be legal in.  For example, you can't do this:
.PP
.Vb 1
\& use alienfile;
\& 
\& sys {
\&   after \*(Aqbuild\*(Aq => sub {
\&     ...
\&   };
\& };
.Ve
.PP
Because a \f(CW\*(C`build\*(C'\fR wouldn't be legal inside a \f(CW\*(C`sys\*(C'\fR block.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP Alien 4
.IX Item "Alien"
.PD 0
.IP Alien::Build 4
.IX Item "Alien::Build"
.IP Alien::Build::MM 4
.IX Item "Alien::Build::MM"
.IP Alien::Base 4
.IX Item "Alien::Base"
.PD
.SH AUTHOR
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Diab Jerius (DJERIUS)
.PP
Roy Storey (KIWIROY)
.PP
Ilya Pavlov
.PP
David Mertens (run4flat)
.PP
Mark Nunberg (mordy, mnunberg)
.PP
Christian Walde (Mithaldu)
.PP
Brian Wightman (MidLifeXis)
.PP
Zaki Mughal (zmughal)
.PP
mohawk (mohawk2, ETJ)
.PP
Vikas N Kumar (vikasnkumar)
.PP
Flavio Poletti (polettix)
.PP
Salvador Fandiño (salva)
.PP
Gianni Ceccarelli (dakkar)
.PP
Pavel Shaydo (zwon, trinitum)
.PP
Kang-min Liu (劉康民, gugod)
.PP
Nicholas Shipp (nshp)
.PP
Juan Julián Merelo Guervós (JJ)
.PP
Joel Berger (JBERGER)
.PP
Petr Písař (ppisar)
.PP
Lance Wicks (LANCEW)
.PP
Ahmad Fatoum (a3f, ATHREEF)
.PP
José Joaquín Atria (JJATRIA)
.PP
Duke Leto (LETO)
.PP
Shoichi Kaji (SKAJI)
.PP
Shawn Laffan (SLAFFAN)
.PP
Paul Evans (leonerd, PEVANS)
.PP
Håkon Hægland (hakonhagland, HAKONH)
.PP
nick nauwelaerts (INPHOBIA)
.PP
Florian Weimer
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011\-2022 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.