view release on metacpan or  search on metacpan

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

   # 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
using a C<-config> suffixed program.  For example C<libxml2> comes with xml2-config which provides the
existence, compiler and linker flags it needs.  In my experience, however, most packages that provide a
C<-config> suffixed program also provide a C<pkg-config> interface as well.

=item implement C<alien_check_built_version> in your L<Alien::Base::ModuleBuild> subclass

You should also implement C<alien_check_build_version> which will be executed from the package build
root once the package is successfully built.

 # inc/My/ModuleBuild.pm
 package My::ModuleBuild;
 
 ...
 
 sub alien_check_built_version {
   my($self) = @_;
 
   my $version = ...
 
   # (Again, if you cannot determine the version,
   #  it is usually sufficent to return a true value)
   return $version;
 }

=item set C<alien_provides_cflags> and C<alien_provides_libs> in C<Build.PL>.

Add something like this to your C<Build.PL>:

 # Build.PL
 use lib 'inc';
 use My::ModuleBuild;
 
 My::ModuleBuild->new(
   ...
   alien_provides_cflags => '-I/usr/include/foo',
   alien_provides_libs   => '-L/usr/lib/foo -lfoo',
   ...
 );

Note that it is frequently sufficient to provide C<alien_provides_libs> and the appropriate C<-l> flag.
These flags will be used in the event that the system package can be found.  It is a good idea to verify
that these flags do indeed work in C<alien_check_installed_version> above.

=back

For a fully implemented example, see L<Alien::Libbz2>.

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

There are many ways to test Alien modules before (or after) they are installed, but instead
of rolling your own, consider using L<Test::Alien> which is light on dependencies and will
test your module very closely to the way that it will actually be used.  That is to say by
building a mini XS or FFI extension and using it.  It even has tests for tool oriented Alien
distributions (like L<Alien::gmake> and L<Alien::patch>).  Here is a short example, there
are many others included with the L<Test::Alien> documentation:

 use Test2::V0;
 use Test::Alien 0.05;
 use Alien::Editline;
 
 alien_ok 'Alien::Editline';
 my $xs = do { local $/; <DATA> };
 xs_ok $xs, with_subtest {
   my($module) = @_;
   ok $module->version;
 };
 
 done_testing;
 
 __DATA__
 
 #include "EXTERN.h"
 #include "perl.h"
 #include "XSUB.h"
 #include <editline/readline.h>
 
 /* having a string parameter that we ignore
    allows us to call this as a class method */
 const char *
 version(const char *class)
 {
   return rl_library_version;
 }
 
 MODULE = TA_MODULE PACKAGE = TA_MODULE
 
 const char *version(class);
     const char *class;

=head2 How do I patch packages that need minor (or major) alterations?

One approach is to create a unified diff for patches that you want to apply and simply run patch on them.  The
L<Alien::patch> and the C<%{patch}> helper can be used like this:

 # Build.PL
 use Alien::Base::ModuleBuild;
 
 Alien::Base::ModuleBuild->new(
   ...
   alien_bin_requires => {
     'Alien::patch' => 0.06, # needed for %{patch} helper
   },
   alien_build_commands => [
     '%{patch} -p1 < ../../patch/mypackage.patch',
     ...
   ],
   ...
 )->create_build_script;

Create a folder in your distribution root called C<patch> and place the C<mypackage.patch> file in there.  Since
the C<patch> command will be executed in the package root instead of the distribution root, you need to use a
relative path prefixed by C<../..>.  Here we use L<Alien::patch> to provide patch even in environments where it