1Alien::Build::Manual::CUosnetrriCbounttirnigb(u3t)ed PerAlliDeonc:u:mBeunitladt:i:oMnanual::Contributing(3)
2
3
4

NAME

6       Alien::Build::Manual::Contributing - Over-detailed contributing guide
7

VERSION

9       version 2.45
10

SYNOPSIS

12        perldoc Alien::Build::Manual::Contributing
13

DESCRIPTION

15       Thank you for considering to contribute to my open source project!  If
16       you have a small patch please consider just submitting it.  Doing so
17       through the project GitHub is probably the best way:
18
19       <https://github.com/plicease/Alien-Build/issues>
20
21       If you have a more invasive enhancement or bugfix to contribute, please
22       take the time to review these guidelines.  In general it is good idea
23       to work closely with the Alien::Build developers, and the best way to
24       contact them is on the "#native" IRC channel on irc.perl.org.
25
26   History
27       Joel Berger wrote the original Alien::Base.  This distribution included
28       the runtime code Alien::Base and an installer class
29       Alien::Base::ModuleBuild.  The significant thing about Alien::Base was
30       that it provided tools to make it relatively easy for people to roll
31       their own Alien distributions.  Over time, the PerlAlien (github
32       organization) or "Alien::Base team" has taken over development of
33       Alien::Base with myself (Graham Ollis) being responsible for
34       integration and releases.  Joel Berger is still involved in the
35       project.
36
37       Since the original development of Alien::Base, Module::Build, on which
38       Alien::Base::ModuleBuild is based, has been removed from the core of
39       Perl.  It seemed worthwhile to write a replacement installer that works
40       with ExtUtils::MakeMaker which IS still bundled with the Perl core.
41       Because this is a significant undertaking it is my intention to
42       integrate the many lessons learned by Joel Berger, myself and the
43       "Alien::Base team" as possible.  If the interface seems good then it is
44       because I've stolen the ideas from some pretty good places.
45
46   Philosophy
47       Alien runtime should be as config-only as possible.
48
49       Ideally the code for an Alien::Base based Alien should simply inherit
50       from Alien::Base, like so:
51
52        package Alien::libfoo;
53
54        use parent qw( Alien::Base );
55
56        1;
57
58       The detection logic should be done by the installer code (alienfile and
59       Alien::Build) and saved into runtime properties (see "runtime_prop" in
60       Alien::Build).  And as much as possible the runtime should be
61       implemented in the base class (Alien::Base).  Where reasonable, the
62       base class should be expanded to meet the needs of this arrangement.
63
64       when downloading a package grab the latest version
65
66       If the maintainer of an Alien disappears for a while, and if the
67       version downloaded during a "share" install is hardcoded in the
68       alienfile, it can be problematic for end-users.
69
70       There are exceptions, of course, in particular when a package provides
71       a very unstable interface from version to version it makes sense to
72       hard code the version and for the Alien developer and Alien consumer
73       developer to coordinate closely.
74
75       when installing a package the operating system as a whole should not be
76       affected
77
78       The convenience of using an Alien is that a user of a CPAN module that
79       consumes an Alien doesn't need to know the exact incantation to install
80       the libraries on which it depends (or indeed it may not be easily
81       installed through the package manager anyway).
82
83       As a corollary, a user of a CPAN module that consumes an Alien module
84       shouldn't expect operating system level packages to be installed, or
85       for these packages to be installed in common system level directories,
86       like "/usr/local" or "/opt".  Instead a "share" directory associated
87       with the Perl install and Alien module should be used.
88
89       Plugins that require user opt-in could be written to prompt a user to
90       automatically install operating system packages, but this should never
91       be done by default or without consent by the user.
92
93       avoid dependencies
94
95       One of the challenges with Alien development is that you are by the
96       nature of the problem, trying to make everyone happy.  Developers
97       working out of CPAN just want stuff to work, and some build
98       environments can be hostile in terms of tool availability, so for
99       reliability you end up pulling a lot of dependencies.  On the other
100       hand, operating system vendors who are building Perl modules usually
101       want to use the system version of a library so that they do not have to
102       patch libraries in multiple places.  Such vendors have to package any
103       extra dependencies and having to do so for packages that the don't even
104       use makes them understandably unhappy.
105
106       As general policy the Alien::Build core should have as few dependencies
107       as possible, and should only pull extra dependencies if they are
108       needed.  Where dependencies cannot be avoidable, popular and reliable
109       CPAN modules, which are already available as packages in the major
110       Linux vendors (Debian, Red Hat) should be preferred.
111
112       As such Alien::Build is hyper aggressive at using dynamic
113       prerequisites.
114
115       interface agnostic
116
117       One of the challenges with Alien::Buil::ModuleBuild was that
118       Module::Build was pulled from the core.  In addition, there is a degree
119       of hostility toward Module::Build in some corners of the Perl
120       community.  I agree with Joel Berger's rationale for choosing
121       Module::Build at the time, as I believe its interface more easily lends
122       itself to building Alien distributions.
123
124       That said, an important feature of Alien::Build is that it is installer
125       agnostic.  Although it is initially designed to work with
126       ExtUtils::MakeMaker, it has been designed from the ground up to work
127       with any installer (Perl, or otherwise).
128
129       As an extension of this, although Alien::Build may have external CPAN
130       dependencies, they should not be exposed to developers USING
131       Alien::Build.  As an example, Path::Tiny is used heavily internally
132       because it does what File::Spec does, plus the things that it doesn't,
133       and uses forward slashes on Windows (backslashes are the "correct
134       separator on windows, but actually using them tends to break
135       everything).  However, there aren't any interfaces in Alien::Build that
136       will return a Path::Tiny object (or if there are, then this is a bug).
137
138       This means that if we ever need to port Alien::Build to a platform that
139       doesn't support Path::Tiny (such as VMS), then it may require some work
140       to Alien::Build itself, modules that USE Alien::Build shouldn't need to
141       be modified.
142
143       plugable
144
145       The actual logic that probes the system, downloads source and builds it
146       should be as pluggable as possible.  One of the challenges with
147       Alien::Build::ModuleBuild was that it was designed to work well with
148       software that works with "autoconf" and "pkg-config".  While you can
149       build with other tools, you have to know a bit of how the installer
150       logic works, and which hooks need to be tweaked.
151
152       Alien::Build has plugins for "autoconf", "pkgconf" (successor of
153       "pkg-config"), vanilla Makefiles, and CMake.  If your build system
154       doesn't have a plugin, then all you have to do is write one!  Plugins
155       that prove their worth may be merged into the Alien::Build core.
156       Plugins that after a while feel like maybe not such a good idea may be
157       removed from the core, or even from CPAN itself.
158
159       In addition, Alien::Build has a special type of plugin, called a
160       negotiator which picks the best plugin for the particular environment
161       that it is running in.  This way, as development of the negotiator and
162       plugins develop over time modules that use Alien::Build will benefit,
163       without having to change the way they interface with Alien::Build
164

ACKNOWLEDGEMENT

166       I would like to that Joel Berger for getting things running in the
167       first place.  Also important to thank other members of the "Alien::Base
168       team":
169
170       Zaki Mughal (SIVOAIS)
171
172       Ed J (ETJ, mohawk)
173
174       Also kind thanks to all of the developers who have contributed to
175       Alien::Base over the years:
176
177       <https://metacpan.org/pod/Alien::Base#CONTRIBUTORS>
178

SEE ALSO

180       alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
181

AUTHOR

183       Author: Graham Ollis <plicease@cpan.org>
184
185       Contributors:
186
187       Diab Jerius (DJERIUS)
188
189       Roy Storey (KIWIROY)
190
191       Ilya Pavlov
192
193       David Mertens (run4flat)
194
195       Mark Nunberg (mordy, mnunberg)
196
197       Christian Walde (Mithaldu)
198
199       Brian Wightman (MidLifeXis)
200
201       Zaki Mughal (zmughal)
202
203       mohawk (mohawk2, ETJ)
204
205       Vikas N Kumar (vikasnkumar)
206
207       Flavio Poletti (polettix)
208
209       Salvador Fandiño (salva)
210
211       Gianni Ceccarelli (dakkar)
212
213       Pavel Shaydo (zwon, trinitum)
214
215       Kang-min Liu (劉康民, gugod)
216
217       Nicholas Shipp (nshp)
218
219       Juan Julián Merelo Guervós (JJ)
220
221       Joel Berger (JBERGER)
222
223       Petr Písař (ppisar)
224
225       Lance Wicks (LANCEW)
226
227       Ahmad Fatoum (a3f, ATHREEF)
228
229       José Joaquín Atria (JJATRIA)
230
231       Duke Leto (LETO)
232
233       Shoichi Kaji (SKAJI)
234
235       Shawn Laffan (SLAFFAN)
236
237       Paul Evans (leonerd, PEVANS)
238
239       Håkon Hægland (hakonhagland, HAKONH)
240
241       nick nauwelaerts (INPHOBIA)
242
244       This software is copyright (c) 2011-2020 by Graham Ollis.
245
246       This is free software; you can redistribute it and/or modify it under
247       the same terms as the Perl 5 programming language system itself.
248
249
250
251perl v5.34.0                      2021-10-A2l9ien::Build::Manual::Contributing(3)
Impressum