Alien-Base-ModuleBuild
3 results

 view release on metacpan or  search on metacpan

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

[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 => {
     FOO => '%{foo}',
   },
   ...
 );
 ...

A common pitfall with environment variables is that setting one to the
empty string (C<''>) is not portable.  On Unix it works fine as you would
expect, but in Windows it actually unsets the environment variable, which
may not be what you intend.

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_env => {
     # is allowed, but may not do what you intend
     # on some platforms!
     FOO => '',
   },
 );
 ...

=item alien_extra_site_config

[version 0.030]

Append extra values to the C<config.site> file when using autoconf.

When <autoconf> is detected, a C<config.site> file is created with values appropriate for
building software that can link against the Perl that you are building with.  This is important
on some platforms, for example 64 bit systems where the compilers generate 32 bit code by
default.  You can also add values to the C<config.site> file using this directive.

For values that are already provided by C<Alien::Base::ModuleBuild>, your value will be
appended after the existing value.  For values that aren't provided, it will simply use
your value by itself.

For example if you needed to add a define to a CFLAGS, you might do something like this:

 ...
 Alien::Base::ModuleBuild->new(
   ...
   alien_extra_site_config => {
     # CFLAGS is usually specified by A::B::MB
     CFLAGS => '-DFOO=1',
     # BAR usually is not.
     BAR => 'baz',
   },
   ...
 );
 ...

And the actual value for CFLAGS in the C<config.site> might have values like this:

 CFLAGS=-O3 -g -DFOO=1
 BAR=baz

=item alien_ffi_name

[version 0.007]

The name of the shared library for use with FFI.  Provided for situations where the shared library name cannot be determined from the C<pkg-config> name specified with C<alien_name>.
For example C<libxml2> has a C<pkg-config> of C<libxml-2.0>, but a shared library name of C<xml2>.
By default alien_name is used with any C<lib> prefix removed.  For example C<libarchive> to be translated into C<archive> which is what you want for that package.

=item alien_helper

[version 0.020]

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

=item alien_msys

[version 0.006]

On windows wrap build and install commands in an C<MSYS> environment using L<Alien::MSYS>.  This option will automatically add L<Alien::MSYS> as a build requirement when building on Windows.

=item alien_name

[version 0.001]

The name of the primary library which will be provided. This should be in the form to be passed to C<pkg-config>. This name is available in the L<command interpolation|/"COMMAND INTERPOLATION"> as C<%n>.

=item alien_provides_cflags

=item alien_provides_libs

[version 0.001]

These parameters, if specified, augment the information found by F<pkg-config>. If no package config data is found, these are used to generate the necessary information. In that case, if these are not specified, they are attempted to be created from ...

=item alien_repository

[version 0.001]

A hashref or arrayref of hashrefs defining the repositories used to find and fetch library tarballs (or zipballs etc.). These attributes are used to create C<Alien::Base::ModuleBuild::Repository> objects (or more likely, subclasses thereof). Which cl...

=over

=item protocol

One of C<ftp>, C<http> C<https> or C<local>. The first three are obvious, C<local> allows packaging a tarball with the Alien:: module.

If your repository is going to need C<https>, make sure that you specify that, because it will inform L<Alien::Base::ModuleBuild> that you will need the prereqs for SSL (namely L<Net::SSLeay> and L<IO::Socket::SSL>).

=item protocol_class

Defines the protocol handler class. Defaults to 'Net::FTP' or 'HTTP::Tiny' as appropriate.

=item host

This is either the root server address for the FTP and HTTP classes (i.e. C<my.server.com>)

=item location

This key is protocol specific. For FTP this contains the name of the folder to search. For HTTP this is the page to be searched for links; this is specified as a path relative to the C<host>. For a local file, this specifies the folder containing the...

=item pattern

This is a C<qr> regex matching acceptable files found in the C<location>. If the pattern contains a capture group, the captured string is interpreted as the version number. N.B. if no versions are found, the files are sorted by filename using version...

=item exact_filename

This key may be specified in place of C<pattern> when the filename of the tarball is known, in which case such a file is downloaded from the given C<host> and C<location>. Note that, in general, specifying a C<pattern> gives more flexibility, but the...

=item exact_version

This key may be specified with the C<exact_filename> key when the version of the tarball is known.

=item platform

This attribute is a string telling the repository validator which platform the repository serves. This may be the string C<src> (the default) for platform-independent source files, or a string which matches the L<Module::Build> method C<os_type> (e.g...

=item c_compiler_required

If true (the default), then a C compiler is required to build from source.

=back

=item alien_repository_class

[version 0.001]

As the repositories in C<alien_repository> are converted to objects, this hash controls the type of object that is created. The keys are the relevant protocol. This allows for easy subclassing any or all protocol classes. The defaults are as follows.

 http    => 'Alien::Base::ModuleBuild::Repository::HTTP',
 ftp     => 'Alien::Base::ModuleBuild::Repository::FTP',
 local   => 'Alien::Base::ModuleBuild::Repository::Local',
 default => 'Alien::Base::ModuleBuild::Repository',

Unlike most L<Module::Build> parameters, authors may specify only those keys which are to be overridden. If any of the above keys are not specified, the above defaults will be used.

=item alien_repository_default

[version 0.001]

This property is a shortcut for specifying multiple repositories with similar attributes. If a repository attribute is not defined in its C<alien_repository> hashref, but that attribute is defined here, then this value will be used. This hashref is e...

=item alien_selection_method

[not yet implemented]

This is intended to choose the mechanism for selecting one file from many. The default name is C<newest>.

=item alien_share_dir

[version 0.001]

The name of the folder which will both serve a stub share directory via L<Module::Build>'s C<share_dir>/C<dist_dir> parameter. This directory is added in a smart manner which attempts not to interfere with other author-defined C<share_dir>s. The defa...

=item alien_stage_install

It might be tempting to use this option if you have a library or tool that hard codes paths from the install location inside the
executable or library code.  However, using this option relies on blib detection which is not very reliable, and can leave your
install in an broken state if the package install step fails.  If you really need this option, please consider instead migrating
to L<Alien::Build>, which has a much more reliable way of staging installs correctly.

[version 0.016]

Alien packages are installed directly into the blib directory by the `./Build' command rather than to the final location during the `./Build install` step.

[version 0.017]

As of 0.017 this is the default.

=item alien_temp_dir

[version 0.001]

The name of the temporary folder which will house the library when it is downloaded and built. The default name is C<_alien>.

=item alien_test_commands

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

=item $ENV{ALIEN_FORCE}

Setting either to a true value will cause the builder to ignore a system-wide installation and build a local version of the library.  This is the equivalent to setting $ENV{ALIEN_INSTALL_TYPE} to 'share'.  $ENV{ALIEN_INSTALL_TYPE} takes precedence.

=item $ENV{ALIEN_INSTALL_TYPE}

Setting to C<share> will ignore a system-wide installation and build a local version of the library.  Setting to C<system> will only use a system-wide installation and die if it cannot be found.

=item $Alien::Base::ModuleBuild::Verbose

=item $ENV{ALIEN_VERBOSE}

Setting the either to a true value will output a little more info from within the module itself. At this point L<Alien::Base> is going to be fairly verbose without this enabled.

=back

=head2 CONFIG DATA

The L<Alien::Base> system needs to store some data to be used in other phases of the build and eventual use. This is done via the mechanism provided by L<Module::Build::ConfigData>. During the build-phase this information is mutable and is available ...

Config keys of interest are:

=over

=item name

Holder for C<alien_name> as needed by pkg-config.

=item install_type

Remembers if the library was found system-wide (value: C<system>) or was installed during build (value: C<share>).

=item pkgconfig

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



( run in 1.135 second using v1.01-cache-2.11-cpan-df04353d9ac )