view release on metacpan or  search on metacpan

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

# ABSTRACT: Frequently Asked Questions about Alien::Base::ModuleBuild
# PODNAME: Alien::Base::ModuleBuild::FAQ
# VERSION

__END__

=pod

=encoding UTF-8

=head1 NAME

Alien::Base::ModuleBuild::FAQ - Frequently Asked Questions about Alien::Base::ModuleBuild

=head1 VERSION

version 1.17

=head1 SYNOPSIS

 perldoc Alien::Base::FAQ

=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::Base::ModuleBuild::API>.  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.

This document serves to answer the most frequently asked questions made by L<Alien::Base> authors.

=head2 What is Alien and Alien::Base?

Alien is 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 L<Alien>.  L<Alien::Base> is a base
class and framework for creating Alien distributions.  The idea is to address as many of the common challenges
to developing Alien modules in the base class to simplify the process.

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

The C<alien_version_check> attribute to L<Alien::Base::ModuleBuild> will be executed to determine if
the library is provided by the operating system.  The default for this is C<%{pkg_config} --modversion %n>
which simply checks to see if any version of that package is available, and prints the version
number.  You can use the C<--atleast-version>, C<--exact-version> options to require a specific range of versions,
but these flags do not work with the C<--modversion> flag, so be sure to invoke separately.

 use Alien::Base::ModuleBuild;
 Alien::Base::ModuleBuild->new(
   dist_name           => 'Alien::Foo',
   alien_name          => 'foo',
   configure_requires  => { 'Alien::Base::ModuleBuild' => '0.022' }, # required for %{pkg_config}
   alien_version_check => '%{pkg_config} --atleast-version 1.2.3 %n && %{pkg_config} --modversion %n',
   ...
 )->create_build_script;

It is better to use the built in C<%{pkg_config}> helper as it will use the system provided pkg-config
if it is available and fallback on the pure perl L<PkgConfig> if not.

You can also use C<--exact-version> to specify an exact version.

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

Although L<Alien::Base> and L<Alien::Base::ModuleBuild> assume packages come with a C<pkg-config>
C<.pc> file to determine compiler and linker flags by default, you can implement an Alien module
for packages that do use C<pkg-config> by following these tasks:

=over 4

=item subclass L<Alien::Base::ModuleBuild> and implement C<alien_check_installed_version>

Create a subclass of L<Alien::Base::ModuleBuild> and put it in the C<inc> directory of your distribution so
that it can be used during install but won't I<be installed>.

 # inc/My/ModuleBuild.pm
 package My::ModuleBuild;
 
 use parent 'Alien::Base::ModuleBuild';
 
 sub alien_check_installed_version {
   my($class) = @_;
 
   # determine if your library is already provided by the system
   my $version = ...;
 
   # return false if the library is NOT provided by the system
   return unless defined $version;
 
   # otherwise return the version detected
   # (if you cannot determine the version it
   #  is usually sufficient to return a true value)
   return $version;
 }

There are number of methods you can use to determine if the system provides your library.  From Perl
methods include L<Devel::CheckLib>, L<ExtUtils::CBuilder>, L<ExtUtils::CChecker>, L<Config::AutoConf>,
L<FFI::CheckLib> among others.  It is also frequently possible to determine if a library is installed