Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Alien::Build::Manual::UserrContributed PeAlien::Build::Manual::Contributing(3)

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

       version 2.37

	perldoc	Alien::Build::Manual::Contributing

       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:


       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 "#native"	IRC channel on

       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	"Alien::Base team" has taken over development of
       Alien::Base with	myself (Graham Ollis) being responsible	for
       integration and releases.  Joel Berger is still involved	in the

       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 IS 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
       "Alien::Base team" as possible.	If the interface seems good then it is
       because I've stolen the ideas from some pretty good places.

       Alien runtime should be as config-only as possible.

       Ideally the code	for an Alien::Base based Alien should simply inherit
       from Alien::Base, like so:

	package	Alien::libfoo;

	use base qw( Alien::Base );


       The detection logic should be done by the installer code	(alienfile and
       Alien::Build) and saved into runtime properties (see "runtime_prop" 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.

       when downloading	a package grab the latest version

       If the maintainer of an Alien disappears	for a while, and if the
       version downloaded during a "share" install is hardcoded	in the
       alienfile, it can be problematic	for end-users.

       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.

       when installing a package the operating system as a whole should	not be

       The convenience of using	an Alien is that a user	of a CPAN 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).

       As a corollary, a user of a CPAN	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 "/usr/local" or "/opt".  Instead a "share" directory associated
       with the	Perl install and Alien module should be	used.

       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.

       avoid dependencies

       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 CPAN 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.

       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
       CPAN modules, which are already available as packages in	the major
       Linux vendors (Debian, Red Hat) should be preferred.

       As such Alien::Build is hyper aggressive	at using dynamic

       interface agnostic

       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.

       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).

       As an extension of this,	although Alien::Build may have external	CPAN
       dependencies, they should not be	exposed	to developers USING
       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).

       This means that if we ever need to port Alien::Build to a platform that
       doesn't support Path::Tiny (such	as VMS), then it may require some work
       to Alien::Build itself, modules that USE	Alien::Build shouldn't need to
       be modified.


       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	"autoconf" and "pkg-config".  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.

       Alien::Build has	plugins	for "autoconf",	"pkgconf" (successor of
       "pkg-config"), 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 CPAN	itself.

       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

       I would like to that Joel Berger	for getting things running in the
       first place.  Also important to thank other members of the "Alien::Base

       Zaki Mughal (SIVOAIS)

       Ed J (ETJ, mohawk)

       Also kind thanks	to all of the developers who have contributed to
       Alien::Base over	the years:


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

       Author: Graham Ollis <>


       Diab Jerius (DJERIUS)

       Roy Storey (KIWIROY)

       Ilya Pavlov

       David Mertens (run4flat)

       Mark Nunberg (mordy, mnunberg)

       Christian Walde (Mithaldu)

       Brian Wightman (MidLifeXis)

       Zaki Mughal (zmughal)

       mohawk (mohawk2,	ETJ)

       Vikas N Kumar (vikasnkumar)

       Flavio Poletti (polettix)

       Salvador	FandiA+-o (salva)

       Gianni Ceccarelli (dakkar)

       Pavel Shaydo (zwon, trinitum)

       Kang-min	Liu (<degree>, gugod)

       Nicholas	Shipp (nshp)

       Juan JuliA!n Merelo GuervA^3s (JJ)

       Joel Berger (JBERGER)

       Petr Pisar (ppisar)

       Lance Wicks (LANCEW)

       Ahmad Fatoum (a3f, ATHREEF)

       JosA(C) JoaquAn Atria (JJATRIA)

       Duke Leto (LETO)

       Shoichi Kaji (SKAJI)

       Shawn Laffan (SLAFFAN)

       Paul Evans (leonerd, PEVANS)

       HAYkon HA|gland (hakonhagland, HAKONH)

       This software is	copyright (c) 2011-2020	by Graham Ollis.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2020-11Alien::Build::Manual::Contributing(3)


Want to link to this manual page? Use this URL:

home | help