1Alien::Build::Manual::CUosnetrriCbounttirnigb(u3t)ed PerAlliDeonc:u:mBeunitladt:i:oMnanual::Contributing(3)
2
6 Alien::Build::Manual::Contributing - Over-detailed contributing guide
7
9 version 2.38
10
12 perldoc Alien::Build::Manual::Contributing
13
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 <https://github.com/plicease/Alien-Build/issues>
20 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 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 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 Philosophy
47 Alien runtime should be as config-only as possible.
48 Ideally the code for an Alien::Base based Alien should simply inherit
50 from Alien::Base, like so:
51 package Alien::libfoo;
53 use base qw( Alien::Base );
55 1;
57 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 when downloading a package grab the latest version
65 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 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 when installing a package the operating system as a whole should not be
76 affected
77 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 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 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 avoid dependencies
94 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 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 As such Alien::Build is hyper aggressive at using dynamic
113 prerequisites.
114 interface agnostic
116 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 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 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 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 plugable
144 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 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 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
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 Zaki Mughal (SIVOAIS)
171 Ed J (ETJ, mohawk)
173 Also kind thanks to all of the developers who have contributed to
175 Alien::Base over the years:
176 <https://metacpan.org/pod/Alien::Base#CONTRIBUTORS>
178
180 alienfile, Alien::Build::MM, Alien::Build::Plugin, Alien::Base, Alien
181
183 Author: Graham Ollis <plicease@cpan.org>
184 Contributors:
186 Diab Jerius (DJERIUS)
188 Roy Storey (KIWIROY)
190 Ilya Pavlov
192 David Mertens (run4flat)
194 Mark Nunberg (mordy, mnunberg)
196 Christian Walde (Mithaldu)
198 Brian Wightman (MidLifeXis)
200 Zaki Mughal (zmughal)
202 mohawk (mohawk2, ETJ)
204 Vikas N Kumar (vikasnkumar)
206 Flavio Poletti (polettix)
208 Salvador Fandiño (salva)
210 Gianni Ceccarelli (dakkar)
212 Pavel Shaydo (zwon, trinitum)
214 Kang-min Liu (劉康民, gugod)
216 Nicholas Shipp (nshp)
218 Juan Julián Merelo Guervós (JJ)
220 Joel Berger (JBERGER)
222 Petr Pisar (ppisar)
224 Lance Wicks (LANCEW)
226 Ahmad Fatoum (a3f, ATHREEF)
228 José Joaquín Atria (JJATRIA)
230 Duke Leto (LETO)
232 Shoichi Kaji (SKAJI)
234 Shawn Laffan (SLAFFAN)
236 Paul Evans (leonerd, PEVANS)
238 Håkon Hægland (hakonhagland, HAKONH)
240
242 This software is copyright (c) 2011-2020 by Graham Ollis.
243 This is free software; you can redistribute it and/or modify it under
245 the same terms as the Perl 5 programming language system itself.
246perl v5.32.0 2021-01-A1l2ien::Build::Manual::Contributing(3)