view release on metacpan or  search on metacpan

lib/Alien/Base/ModuleBuild/API.pod  view on Meta::CPAN

# ABSTRACT: API Reference for Alien:: Authors
# VERSION
# PODNAME: Alien::Base::ModuleBuild::API

__END__

=pod

=encoding UTF-8

=head1 NAME

Alien::Base::ModuleBuild::API - API Reference for Alien:: Authors

=head1 VERSION

version 1.17

=head1 DESCRIPTION

B<NOTE>: Please consider for new development of L<Alien>s that you use
L<Alien::Build> and L<alienfile> instead.  Like L<Alien::Base::ModuleBuild> they work
with L<Alien::Base>.  Unlike L<Alien::Base::ModuleBuild> they are more easily customized
and handle a number of corner cases better.  For a good place to start,
please see L<Alien::Build::Manual::AlienAuthor>.  Although the
Alien-Base / Alien-Build team will continue to maintain this module,
(we will continue to fix bugs where appropriate), we aren't adding any
new features to this module.

A list of extra properties and methods provided by
L<Alien::Base::ModuleBuild> beyond those contained in L<Module::Build::API>.
Note that all property and method names are prefixed with C<alien_> to prevent future
collisions L<Module::Build> builtins.

=head2 CONSTRUCTOR

L<Alien::Base::ModuleBuild> adds several parameters to the L<new|Module::Build::API/CONSTRUCTORS> constructor in L<Module::Build>. Unless otherwise specified all of the parameters listed in L<Module::Build::API> are available and behave identically t...

=over

=item alien_arch

[version 0.019]

Install module into an architecture specific directory.  This is off by default, unless $ENV{ALIEN_ARCH} is true.  Most Alien distributions will be installing binary code.  If you are an integrator where the C<@INC> path is shared by multiple Perls i...

=item alien_autoconf_with_pic

[version 0.005]

Add C<--with-pic> option to autoconf style C<configure> script when called.  This is the default, and normally a good practice.  Normally autoconf will ignore this and any other options that it does not recognize, but some non-autoconf C<configure> s...

=item alien_bin_requires

[version 0.006]

Hash reference of modules (keys) and versions (values) that specifies C<Alien> modules that provide binary tools that are required to build.  Any L<Alien::Base> module that includes binaries should work.  Also supported are L<Alien::MSYS>, L<Alien::C...

[version 0.007]

These only become required for building if L<Alien::Base::ModuleBuild> determines that a source code build is required.

=item alien_build_commands

[version 0.001]

An arrayref of commands used to build the library in the directory specified in C<alien_temp_dir>. Each command is first passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">, so those variables may be used. The default is tailo...

[version 0.009]

Each command may be either a string or an array reference.  If the array reference form is used then the multiple argument form of C<system> is used.  Prior to version 0.009, only the string form was supported.

=item alien_env

[version 0.027]

Environment overrides.  Allows you to set environment variables as a hash
reference that will override environment variables.  You can use the same
interpolated escape sequences and helpers that commands use.  Set to undef
to remove the variable.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_env => {
     PERL => '%X',     # sets the environment variable PERL to the location
                       # of the Perl interpreter.
     PERCENT => '%%',  # evaluates to '%'
     REMOVE => undef,  # remove the environment variable if it is defined
   },
   ...
 );
 ...

Please keep in mind that frequently users have a good reason to have set
environment variables, and you should not override them without a good
reason.  An example of a good justification would be if a project has a
Makefile that interacts badly with common environment variables.  This
can sometimes be a problem since Makefile variables can be overridden with
environment variables.

A useful pattern is to use a helper to only override an environment
variable if it is not already set.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_helper => {
     foo => '$ENV{FOO}||"my preferred value if not already set"'
   },
   alien_env => {

lib/Alien/Base/ModuleBuild/API.pod  view on Meta::CPAN

A hashref of Alien::Base::PkgConfig objects created from F<.pc> files found in C<working_directory>. One extra object (whose key is C<_manual> is created from the C<alien_provides_*> information.

=item version

The version number installed or available.

=item working_directory

Holder for the full path to the extracted source of the library. This is used to munge the pkg-config data later on.

=back

=head2 COMMAND INTERPOLATION

Before L<Alien::Base::ModuleBuild> executes system commands, it replaces a few special escape sequences with useful data. This is needed especially for referencing the full path to the C<alien_share_dir> before this path is known. The available seque...

=over

=item %{I<helper>}

[version 0.020]

Call the given helper, either provided by the C<alien_helper> or C<alien_bin_requires> property.  See L<Alien::Base#alien_helper>.

=item %c

Platform independent incantation for running autoconf C<configure> script.  On *nix systems this is C<./configure>, on Windows this is C<sh configure>.  On windows L<Alien::MSYS> is injected as a dependency and all commands are executed in an C<MSYS>...

=item %n

Shortcut for the name stored in C<alien_name>

 pkg-config --modversion %n

=item %p

B<deprecated>

Platform independent "local command prefix". On *nix systems this is C<./>, on Windows it is an empty string.

 %pconfigure

Please note that this only works to run scripts on Unix, and does not work on Windows.  It is thus, not fit for purpose and should not be used.  As an alternative:

=over 4

=item autoconf "configure"

If you are trying to invoke the autoconf configure script, use C<%c> instead.  This will use the correct incantation on either Unix like systems and on Windows.

=item Some other script

Invoke the interpreter directly.  For example, if you have a Python script use C<python foo.py>, if you have a Perl script use "%X foo.pl", if you have an sh script use "sh foo.sh".  These are all portable.
For sh, be sure to set the C<alien_msys> property so that it will work on Windows.

=back

=item %s

The full path to the installed location of the the share directory (builder method C<alien_library_destination>).
This is where the library should install itself; for autoconf style installs this will look like

 --prefix=%s

This will be the local blib directory location if C<alien_stage_install> is true (which is the default as of 0.17.
This will be the final install location if C<alien_stage_install> is false (which was the default prior to 0.17).
Please see the documentation above on C<alien_stage_install> which includes some caveats before you consider changing
this option.

=item %v

Captured version of the original archive.

=item %x

The current Perl interpreter (aka $^X)

=item %X

[version 0.027]

The current Perl interpreter using the Unix style path separator C</>
instead of the native Windows C<\>.

=item %%

A literal C<%>.

=back

=head1 SEE ALSO

=over

=item *

L<Module::Build::API>

=back

=head1 AUTHOR

Original author: Joel A Berger E<lt>joel.a.berger@gmail.comE<gt>

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

Contributors:

David Mertens (run4flat)

Mark Nunberg (mordy, mnunberg)

Christian Walde (Mithaldu)

Brian Wightman (MidLifeXis)

Graham Ollis (plicease)

Zaki Mughal (zmughal)

mohawk2

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)

Petr Písař (ppisar)

Alberto Simões (ambs)

=head1 COPYRIGHT AND LICENSE