NAME

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

VERSION

       version 2.80

SYNOPSIS

        perldoc Alien::Build::Manual::Contributing

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:

       <https://github.com/plicease/Alien-Build/issues>

       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
       irc.perl.org.

   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 "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 project.

       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.

   Philosophy
       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 parent qw( Alien::Base );

        1;

       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 affected

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

       interface agnostic

       One of the challenges with Alien::Base::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.

       plugable

       The actual logic that probes the system, downloads source and builds it should be as
       pluggable as possible.  One of the challenges with Alien::Base::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

ACKNOWLEDGEMENT

       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 team":

       Zaki Mughal (SIVOAIS)

       Ed J (ETJ, mohawk)

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

       <https://metacpan.org/pod/Alien::Base#CONTRIBUTORS>

SEE ALSO

       Alien::Build::Manual
           Other Alien::Build manuals.

AUTHOR

       Author: Graham Ollis <plicease@cpan.org>

       Contributors:

       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 Fandiño (salva)

       Gianni Ceccarelli (dakkar)

       Pavel Shaydo (zwon, trinitum)

       Kang-min Liu (劉康民, gugod)

       Nicholas Shipp (nshp)

       Juan Julián Merelo Guervós (JJ)

       Joel Berger (JBERGER)

       Petr Písař (ppisar)

       Lance Wicks (LANCEW)

       Ahmad Fatoum (a3f, ATHREEF)

       José Joaquín Atria (JJATRIA)

       Duke Leto (LETO)

       Shoichi Kaji (SKAJI)

       Shawn Laffan (SLAFFAN)

       Paul Evans (leonerd, PEVANS)

       Håkon Hægland (hakonhagland, HAKONH)

       nick nauwelaerts (INPHOBIA)

       Florian Weimer

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011-2022 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.