The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Alien::Build::Manual::FAQ - Frequently Asked Questions about Alien::Build

VERSION

version 0.90_01

SYNOPSIS

 perldoc Alien::Build::Manual::FAQ

DESCRIPTION

This document serves to answer the most frequently asked questions made by developers creating Alien modules using Alien::Build.

QUESTIONS

What is Alien, Alien::Base and Alien::Build?

Alien in a Perl namespace for defining dependencies in CPAN for libraries and tools which are not "native" to CPAN. For a manifesto style description of the Why, and How see Alien. Alien::Base is a base class for the Alien runtime. Alien::Build is a tool for probing the operating system for existing libraries and tools, and downloading, building and installing packages. alienfile is a recipe format for describing how to probe, download, build and install a package.

How do I specify a minimum or exact version requirement for packages that use pkg-config?

The various pkg-config plugins all support a minimum_version field:

 use alienfile;
 
 plugin 'PkgConfig', pkg_name => foo, minimum_version => '1.2.3';

How to create an Alien module for a packages that do not support pkg-config?

Depends on how you probe for and build for a package. Most things can be done by providing commands. For example if you have a foo package that provides a foo-config program to provide the normal pkg-config fields then you could do something like this:

 use alienfile;
 
 probe [ 'foo-config --version' ];
 
 share {
   ...
 
   build [
     '%{make} PREFIX=%{.runtime.prefix}',
     '%{amek} install PREFIX=%{.runtime.prefix}',
   ];
 };
 
 gather [
   [ 'foo-config', '--version', \'%{.runtime.version}' ],
   [ 'foo-config', '--cflags',  \'%{.runtime.cflags}'  ],
   [ 'foo-config', '--libs',    \'%{.runtime.libs}'    ],
 ];

How do I test my package once it is built (before it is installed)?

Use Test::Alien. It has extensive documentation, and integrates nicely with Alien::Base.

How do I patch packages that need alterations?

If you have a diff file you can use patch:

 use alienfile;
 
 ...
 
 share {
   ...
   patch [ '%{patch} -p1 < %{.install.patch}/mypatch.diff' ];
   build [ ... ] ;
 }
 
 ...

You can also patch using Perl if that is easier:

 use alienfile;
 
 ...
 
 share {
   ...
   patch sub {
     my($build) = @_;
     # make changes to source prior to build
   };
   build [ ... ];
 };

How do I build a package that uses build system

autoconf

Use the autoconf plugin (Alien::Build::Plugin::Build::Autoconf). If your package provides a pkg-config .pc file, then you can also use the PkgConfig plugin (Alien::Build::Plugin::PkgConfig::Negotiate).

 use alienfile
 plugin PkgConfig => 'libfoo';
 share {
   plugin Download => (
     url => 'http://example.org/dist',
     version => qr/libfoo-([0-9\.])\.tar\.gz$/,
   );
   plugin Extract => 'tar.gz';
   plugin 'Build::Autoconf' => ();
 };

If you need to provide custom flags to configure, you can do that too:

 share {
   plugin 'Build::Autoconf' => ();
   build [
     '%{configure} --disable-shared --enable-foo',
     '%{make}',
     '%{make} install',
   ];
 };

If your package requires GNU Make, use %{gmake} instead of %{make}.

autoconf-like

If you see an error like this:

 Unknown option "--with-pic".

It is because the autoconf plugin uses the --with-pic option by default, since it makes sense most of the time, and autoconf usually ignores options that it does not recognize. Some autoconf style build systems fail when they see an option that they do not recognize. You can turn this behavior off for these packages:

 plugin 'Build::Autoconf' => (
   with_pic => 0,
 );

Another thing about the autoconf plugin is that it uses DESTDIR to do a double staged install. If you see an error like "nothing was installed into destdir", that means that your package does not support DESTDIR. You should instead use the MSYS plugin and use a command sequence to do the build like this:

 share {
   plugin 'Build::MSYS' => ();
   build [
     # explicitly running configure with "sh" will make sure that
     # it works on windows as well as UNIX.
     'sh configure --prefix=%{.install.prefix} --disable-shared',
     '%{make}',
     '%{make} install',
   ];
 };

CMAKE

There is an Alien for cmake: Alien::CMake, and a helper %{cmake} which will automatically pull it in as needed. (Help wanted, an actual working example for this FAQ).

vanilla Makefiles

You can use the %{make} or %{gmake} helper (use the latter if your package requires GNU Make. You can also use perl configuration to make sure that position independent code is generated:

 build {
   build [
     [ '%{make}', 'CC=%{perl.config.cc}', 'CFLAGS=%{perl.config.cccdlflags} %{perl.config.optimize}' ],
     [ '%{make}', 'install', 'PREFIX=%{.install.prefix}' ],
   ],
 };

Can/Should I write a tool oriented Alien module?

Certainly. The original intent was to provide libraries, but tools are also quite doable using the Alien::Build toolset. A good example of how to do this is Alien::nasm. You will want to use the 'Probe::CommandLine':

 use alienfile;
 
 plugin 'Probe::CommandLine' => (
   command => 'gzip',
 );

How do I use Alien::Build from Dist::Zilla?

For creating Alien::Base and Alien::Build based dist from Dist::Zilla you can use the dzil plugin Dist::Zilla::Plugin::AlienBuild.

I have a question not listed here!

There are a number of forums available to people working on Alien, Alien::Base and Alien::Build modules:

#native on irc.perl.org

This is intended for native interfaces in general so is a good place for questions about Alien generally or Alien::Base and Alien::Build specifically.

mailing list

The perl5-alien google group is intended for Alien issues generally, including Alien::Base and Alien::Build.

https://groups.google.com/forum/#!forum/perl5-alien

Open a support ticket

If you have an issue with Alie::Build itself, then please open a support ticket on the project's GitHub issue tracker.

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

SEE ALSO

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

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Diab Jerius (DJERIUS)

Roy Storey

Ilya Pavlov

David Mertens (run4flat)

Mark Nunberg (mordy, mnunberg)

Christian Walde (Mithaldu)

Brian Wightman (MidLifeXis)

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)

Juan Julián Merelo Guervós (JJ)

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.