.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "Alien::Build::Manual::Contributing 3"
.TH Alien::Build::Manual::Contributing 3 "2021-10-28" "perl v5.26.3" "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"
Alien::Build::Manual::Contributing \- Over\-detailed contributing guide
.SH "VERSION"
.IX Header "VERSION"
version 2.45
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& perldoc Alien::Build::Manual::Contributing
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Thank you for considering to contribute to my open source project!  If
you have a small patch please consider just submitting it.  Doing so
through the project GitHub is probably the best way:
.PP
<https://github.com/plicease/Alien\-Build/issues>
.PP
If you have a more invasive enhancement or bugfix to contribute, please
take the time to review these guidelines.  In general it is good idea to
work closely with the Alien::Build developers, and the best way to
contact them is on the \f(CW\*(C`#native\*(C'\fR \s-1IRC\s0 channel on irc.perl.org.
.SS "History"
.IX Subsection "History"
Joel Berger wrote the original Alien::Base.  This distribution
included the runtime code Alien::Base and an installer class
Alien::Base::ModuleBuild.  The significant thing about Alien::Base
was that it provided tools to make it relatively easy for people to roll
their own Alien distributions.  Over time, the PerlAlien (github
organization) or \*(L"Alien::Base team\*(R" has taken over development of
Alien::Base with myself (Graham Ollis) being responsible for
integration and releases.  Joel Berger is still involved in the project.
.PP
Since the original development of Alien::Base, Module::Build, on
which Alien::Base::ModuleBuild is based, has been removed from the
core of Perl.  It seemed worthwhile to write a replacement installer
that works with ExtUtils::MakeMaker which \s-1IS\s0 still bundled with the
Perl core.  Because this is a significant undertaking it is my intention
to integrate the many lessons learned by Joel Berger, myself and the
\&\*(L"Alien::Base team\*(R" as possible.  If the interface seems good then it is
because I've stolen the ideas from some pretty good places.
.SS "Philosophy"
.IX Subsection "Philosophy"
\fIAlien runtime should be as config-only as possible.\fR
.IX Subsection "Alien runtime should be as config-only as possible."
.PP
Ideally the code for an Alien::Base based Alien should simply
inherit from Alien::Base, like so:
.PP
.Vb 1
\& package Alien::libfoo;
\& 
\& use parent qw( Alien::Base );
\& 
\& 1;
.Ve
.PP
The detection logic should be done by the installer code (alienfile
and Alien::Build) and saved into runtime properties (see
\&\*(L"runtime_prop\*(R" in Alien::Build).  And as much as
possible the runtime should be implemented in the base class (Alien::Base).
Where reasonable, the base class should be expanded to meet the needs
of this arrangement.
.PP
\fIwhen downloading a package grab the latest version\fR
.IX Subsection "when downloading a package grab the latest version"
.PP
If the maintainer of an Alien disappears for a while, and if the
version downloaded during a \*(L"share\*(R" install is hardcoded in the
alienfile, it can be problematic for end-users.
.PP
There are exceptions, of course, in particular when a package provides
a very unstable interface from version to version it makes sense
to hard code the version and for the Alien developer and Alien consumer
developer to coordinate closely.
.PP
\fIwhen installing a package the operating system as a whole should not be affected\fR
.IX Subsection "when installing a package the operating system as a whole should not be affected"
.PP
The convenience of using an Alien is that a user of a \s-1CPAN\s0 module
that consumes an Alien doesn't need to know the exact incantation
to install the libraries on which it depends (or indeed it may not be
easily installed through the package manager anyway).
.PP
As a corollary, a user of a \s-1CPAN\s0 module that consumes an Alien
module shouldn't expect operating system level packages to be
installed, or for these packages to be installed in common system
level directories, like \f(CW\*(C`/usr/local\*(C'\fR or \f(CW\*(C`/opt\*(C'\fR.  Instead a \*(L"share\*(R"
directory associated with the Perl install and Alien module
should be used.
.PP
Plugins that require user opt-in could be written to prompt a user
to automatically install operating system packages, but this should
never be done by default or without consent by the user.
.PP
\fIavoid dependencies\fR
.IX Subsection "avoid dependencies"
.PP
One of the challenges with Alien development is that you are by the
nature of the problem, trying to make everyone happy.  Developers
working out of \s-1CPAN\s0 just want stuff to work, and some build environments
can be hostile in terms of tool availability, so for reliability you end
up pulling a lot of dependencies.  On the other hand, operating system
vendors who are building Perl modules usually want to use the system
version of a library so that they do not have to patch libraries in
multiple places.  Such vendors have to package any extra dependencies
and having to do so for packages that the don't even use makes them
understandably unhappy.
.PP
As general policy the Alien::Build core should have as few
dependencies as possible, and should only pull extra dependencies if
they are needed.  Where dependencies cannot be avoidable, popular and
reliable \s-1CPAN\s0 modules, which are already available as packages in the
major Linux vendors (Debian, Red Hat) should be preferred.
.PP
As such Alien::Build is hyper aggressive at using dynamic
prerequisites.
.PP
\fIinterface agnostic\fR
.IX Subsection "interface agnostic"
.PP
One of the challenges with Alien::Buil::ModuleBuild was that
Module::Build was pulled from the core.  In addition, there is a
degree of hostility toward Module::Build in some corners of the Perl
community.  I agree with Joel Berger's rationale for choosing
Module::Build at the time, as I believe its interface more easily
lends itself to building Alien distributions.
.PP
That said, an important feature of Alien::Build is that it is
installer agnostic.  Although it is initially designed to work with
ExtUtils::MakeMaker, it has been designed from the ground up to work
with any installer (Perl, or otherwise).
.PP
As an extension of this, although Alien::Build may have external \s-1CPAN\s0
dependencies, they should not be exposed to developers \s-1USING\s0
Alien::Build.  As an example, Path::Tiny is used heavily
internally because it does what File::Spec does, plus the things that
it doesn't, and uses forward slashes on Windows (backslashes are the
"correct separator on windows, but actually using them tends to break
everything).  However, there aren't any interfaces in Alien::Build
that will return a Path::Tiny object (or if there are, then this is a
bug).
.PP
This means that if we ever need to port Alien::Build to a platform
that doesn't support Path::Tiny (such as \s-1VMS\s0), then it may require
some work to Alien::Build itself, modules that \s-1USE\s0 Alien::Build
shouldn't need to be modified.
.PP
\fIplugable\fR
.IX Subsection "plugable"
.PP
The actual logic that probes the system, downloads source and builds it
should be as pluggable as possible.  One of the challenges with
Alien::Build::ModuleBuild was that it was designed to work well with
software that works with \f(CW\*(C`autoconf\*(C'\fR and \f(CW\*(C`pkg\-config\*(C'\fR.  While you can
build with other tools, you have to know a bit of how the installer
logic works, and which hooks need to be tweaked.
.PP
Alien::Build has plugins for \f(CW\*(C`autoconf\*(C'\fR, \f(CW\*(C`pkgconf\*(C'\fR (successor of
\&\f(CW\*(C`pkg\-config\*(C'\fR), vanilla Makefiles, and CMake.  If your build system
doesn't have a plugin, then all you have to do is write one!  Plugins
that prove their worth may be merged into the Alien::Build core.
Plugins that after a while feel like maybe not such a good idea may be
removed from the core, or even from \s-1CPAN\s0 itself.
.PP
In addition, Alien::Build has a special type of plugin, called a
negotiator which picks the best plugin for the particular environment
that it is running in.  This way, as development of the negotiator and
plugins develop over time modules that use Alien::Build will benefit,
without having to change the way they interface with Alien::Build
.SH "ACKNOWLEDGEMENT"
.IX Header "ACKNOWLEDGEMENT"
I would like to that Joel Berger for getting things running in the first
place.  Also important to thank other members of the \*(L"Alien::Base team\*(R":
.PP
Zaki Mughal (\s-1SIVOAIS\s0)
.PP
Ed J (\s-1ETJ,\s0 mohawk)
.PP
Also kind thanks to all of the developers who have contributed to
Alien::Base over the years:
.PP
<https://metacpan.org/pod/Alien::Base#CONTRIBUTORS>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Diab Jerius (\s-1DJERIUS\s0)
.PP
Roy Storey (\s-1KIWIROY\s0)
.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, \s-1ETJ\s0)
.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 (\s-1JJ\s0)
.PP
Joel Berger (\s-1JBERGER\s0)
.PP
Petr Písař (ppisar)
.PP
Lance Wicks (\s-1LANCEW\s0)
.PP
Ahmad Fatoum (a3f, \s-1ATHREEF\s0)
.PP
José Joaquín Atria (\s-1JJATRIA\s0)
.PP
Duke Leto (\s-1LETO\s0)
.PP
Shoichi Kaji (\s-1SKAJI\s0)
.PP
Shawn Laffan (\s-1SLAFFAN\s0)
.PP
Paul Evans (leonerd, \s-1PEVANS\s0)
.PP
Håkon Hægland (hakonhagland, \s-1HAKONH\s0)
.PP
nick nauwelaerts (\s-1INPHOBIA\s0)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011\-2020 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.