# PODNAME: Alien::Build::Manual::Contributing
# ABSTRACT: Over-detailed contributing guide
# VERSION

__END__

=pod

=encoding UTF-8

=head1 NAME

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

=head1 VERSION

version 1.39

=head1 SYNOPSIS

 perldoc Alien::Build::Manual::Contributing

=head1 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:

L<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 L<Alien::Build> developers, and the best way to 
contact them is on the C<#native> IRC channel on irc.perl.org.

=head2 History

Joel Berger wrote the original L<Alien::Base>.  This distribution 
included the runtime code L<Alien::Base> and an installer class 
L<Alien::Base::ModuleBuild>.  The significant thing about L<Alien::Base> 
was that it provided tools to make it relatively easy for people to roll 
their own L<Alien> distributions.  Over time, the Perl5-Alien (github 
organization) or "Alien::Base team" has taken over development of 
L<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 L<Alien::Base>, L<Module::Build>, on 
which L<Alien::Base::ModuleBuild> is based, has been removed from the 
core of Perl.  It seemed worthwhile to write a replacement installer 
that works with L<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.

=head2 Philosophy

=head3 avoid dependencies

One of the challenges with L<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 L<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 L<Alien::Build> is hyper aggressive at using dynamic 
prerequisites.

=head3 interface agnostic

One of the challenges with L<Alien::Buil::ModuleBuild> was that 
L<Module::Build> was pulled from the core.  In addition, there is a 
degree of hostility toward L<Module::Build> in some corners of the Perl 
community.  I agree with Joel Berger's rationale for choosing 
L<Module::Build> at the time, as I believe its interface more easily 
lends itself to building L<Alien> distributions.

That said, an important feature of L<Alien::Build> is that it is 
installer agnostic.  Although it is initially designed to work with 
L<ExtUtils::MakeMaker>, it has been designed from the ground up to work 
with any installer (Perl, or otherwise).

As an extension of this, although L<Alien::Build> may have external CPAN 
dependencies, they should not be exposed to developers USING 
L<Alien::Build>.  As an example, L<Path::Tiny> is used heavily 
internally because it does what L<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 L<Alien::Build> 
that will return a L<Path::Tiny> object (or if there are, then this is a 
bug).

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

=head3 plugable

The actual logic that probes the system, downloads source and builds it 
should be as pluggable as possible.  One of the challenges with 
L<Alien::Build::ModuleBuild> was that it was designed to work well with 
software that works with C<autoconf> and C<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.

L<Alien::Build> has plugins for C<autoconf>, C<pkgconf> (successor of 
C<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 L<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, L<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 L<Alien::Build> will benefit, 
without having to change the way they interface with L<Alien::Build>

=head1 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 
L<Alien::Base> over the years:

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

=head1 SEE ALSO

L<alienfile>, L<Alien::Build::MM>, L<Alien::Build::Plugin>, L<Alien::Base>, L<Alien>

=head1 AUTHOR

Author: Graham Ollis E<lt>plicease@cpan.orgE<gt>

Contributors:

Diab Jerius (DJERIUS)

Roy Storey

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 Pisar (ppisar)

Lance Wicks (LANCEW)

Ahmad Fatoum (a3f, ATHREEF)

José Joaquín Atria (JJATRIA)

Duke Leto (LETO)

Shoichi Kaji (SKAJI)

=head1 COPYRIGHT AND LICENSE

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

=cut
