view release on metacpan or  search on metacpan

lib/Alien/Build/Manual/FAQ.pod  view on Meta::CPAN

 };

=head2 The flags that a plugin produces are wrong!

Sometimes, the compiler or linker flags that the PkgConfig plugin comes up with are not quite
right.  (Frequently this is actually because a package maintainer is providing a broken
C<.pc> file).  (Other plugins may also have problems).  You could replace the plugin's C<gather> step
but a better way is to provide a subroutine callback to be called after the gather stage
is complete.  You can do this with the L<alienfile> C<after> directive:

 use alienfile;
 
 plugin 'PkgConfig' => 'libfoo';
 
 share {
   ...
   after 'gather' => sub {
     my($build) = @_;
     $build->runtime_prop->{libs}        .= " -lbar";        # libfoo also requires libbar
     $build->runtime_prop->{libs_static} .= " -lbar -lbaz";  # libfoo also requires libbaz under static linkage
   };
 };

Sometimes you only need to do this on certain platforms.  You can adjust the logic based on C<$^O>
appropriately.

 use alienfile;
 
 plugin 'PkgConfig' => 'libfoo';
 
 share {
   ...
   after 'gather' => sub {
     my($build) = @_;
     if($^O eq 'MSWin32') {
       $build->runtime_prop->{libs} .= " -lpsapi";
     }
   };
 };

=head2 "cannot open shared object file" trying to load XS

The error looks something like this:

 t/acme_alien_dontpanic2.t ....... 1/?
 # Failed test 'xs'
 # at t/acme_alien_dontpanic2.t line 13.
 #   XSLoader failed
 #     Can't load '/home/cip/.cpanm/work/1581635869.456/Acme-Alien-DontPanic2-2.0401/_alien/tmp/test-alien-lyiQNX/auto/Test/Alien/XS/Mod0/Mod0.so' for module Test::Alien::XS::Mod0: libdontpanic.so.0: cannot open shared object file: No such file or di...
 #  at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
 # Compilation failed in require at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
 # BEGIN failed--compilation aborted at /home/cip/perl5/lib/perl5/Test/Alien.pm line 414.
 t/acme_alien_dontpanic2.t ....... Dubious, test returned 1 (wstat 256, 0x100)
 Failed 1/6 subtests
 t/acme_alien_dontpanic2__ffi.t .. ok

This error happened at test time for the Alien, but depending on your environment and Alien it might
happen later and the actual diagnostic wording might vary.

This is usually because your XS or Alien tries to use dynamic libraries instead of static ones.
Please consult the section about dynamic vs. static libraries in L<Alien::Build::Manual::AlienAuthor>.
The TL;DR is that L<Alien::Build::Plugin::Gather::IsolateDynamic> might help.
If you are the Alien author and the package you are alienizing doesn't have a static option you can
use L<Alien::Role::Dino>, but please note the extended set of caveats!

=head2 599 Internal Exception errors downloading packages from the internet

 Alien::Build::Plugin::Fetch::HTTPTiny> 599 Internal Exception fetching http://dist.libuv.org/dist/v1.15.0
 Alien::Build::Plugin::Fetch::HTTPTiny> exception: IO::Socket::SSL 1.42 must be installed for https support
 Alien::Build::Plugin::Fetch::HTTPTiny> exception: Net::SSLeay 1.49 must be installed for https support
 Alien::Build::Plugin::Fetch::HTTPTiny> An attempt at a SSL URL https was made, but your HTTP::Tiny does not appear to be able to use https.
 Alien::Build::Plugin::Fetch::HTTPTiny> Please see: https://metacpan.org/pod/Alien::Build::Manual::FAQ#599-Internal-Exception-errors-downloading-packages-from-the-internet
 error fetching http://dist.libuv.org/dist/v1.15.0: 599 Internal Exception at /Users/ollisg/.perlbrew/libs/perl-5.26.0@test1/lib/perl5/Alien/Build/Plugin/Fetch/HTTPTiny.pm line 68.

(Older versions of L<Alien::Build> produced a less verbose more confusing version of this diagnostic).

TL;DR, instead of this:

 share {
   start_url => 'http://example.org/dist';
   ...
 };

do this:

 share {
   start_url => 'https://example.org/dist';
 };

If the website is going to redirect to a secure URL anyway.

The "599 Internal Exception" indicates an "internal" exception from L<HTTP::Tiny> and is not a real
HTTP status code or error.  This could mean a number of different problems, but most frequently
indicates that a SSL request was made without the required modules (L<Net::SSLeay> and
L<IO::Socket::SSL>).  Normally the L<Alien::Build::Plugin::Download::Negotiate>
and L<Alien::Build::Plugin::Fetch::HTTPTiny> will make sure that the appropriate modules are added
to your prerequisites for you if you specify a C<https> URL.  Some websites allow an initial request
from C<http> but then redirect to C<https>.  If you can it is better to specify C<https>, if you
cannot, then you can instead use the C<ssl> property on either of those two plugins.

=head2 Does not detect system package even though it is installed

This could just be because the alien requires a more recent package that what is provided by your
operating system.

It could also be because you do not have the development package installed.  Many Linux vendors
in particular separate packages into runtime and development pages.  On RPM based systems these
development packages usually have C<-devel> suffix (example runtime: C<libffi> and development:
C<libffi-devel>).  On Debian based systems these development packages usually have a C<-dev>
suffix (example runtime: C<libffi> and development: C<libffi-dev>).

=head2 Network fetch is turned off

If you get an error like this:

 Alien::Build> install type share requested or detected, but network fetch is turned off
 Alien::Build> see see https://metacpan.org/pod/Alien::Build::Manual::FAQ#Network-fetch-is-turned-off

This is because your environment is setup not to install aliens that require the network.  You
can turn network fetch back on by setting C<ALIEN_INSTALL_NETWORK> to true, or by unsetting it.
This environment variable is designed for environments that don't ever want to install aliens that
require downloading source packages over the internet.

=head2 I would really prefer you not download stuff off the internet

The idea of L<Alien> is to download missing packages and build them automatically to make installing
easier.  Some people may not like this, or may even have security requirements that they not download
random package over the internet (caveat, downloading random stuff off of CPAN may not be any safer,
so make sure you audit all of the open source software that you use appropriately).  Another reason
you may not want to download from the internet is if you are packaging up an alien for an operating
system vendor, which will always want to use the system version of a library.  In that situation you
don't want L<Alien::Build> to go off and download something from the internet because the probe failed
for some reason.

This is easy to take care of, simply set C<ALIEN_INSTALL_TYPE> to C<system> and a build from source
code will never be attempted.  On systems that do not provide system versions of the library or tool
you will get an error, allowing you to install the library, and retry the alien install.  You can
also set the environment variable on just some aliens.

 % export ALIEN_INSTALL_TYPE=system  # for everyone
 
 % env ALIEN_INSTALL_TYPE=system cpanm -v Alien::libfoo

=head2 For testing I would like to test both system and share installs!

You can use the C<ALIEN_INSTALL_TYPE> environment variable.  It will force either a C<share> or
C<system> install depending on how it is set.  For Travis-CI you can do something like this:

 env:
   matrix:
     - ALIEN_INSTALL_TYPE=share
     - ALIEN_INSTALL_TYPE=system

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

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

=head2 Cannot find either a share directory or a ConfigData module

If you see an error like this:

 Cannot find either a share directory or a ConfigData module for Alien::libfoo.
 (Alien::libfoo loaded from lib/Alien/libfoo.pm)
 Please see https://metacpan.org/pod/distribution/Alien-Build/lib/Alien/Build/Manual/FAQ.pod#Cannot-find-either-a-share-directory-or-a-ConfigData-module
 Can't locate Alien/libfoo/ConfigData.pm in @INC (you may need to install the Alien::libfoo::ConfigData module) (@INC contains: ...)

it means you are trying to use an Alien that hasn't been properly installed.  An L<Alien::Base>
based Alien needs to have either the share directory build during the install process or for
older legacy L<Alien::Base::ModuleBuild> based Aliens, a ConfigData module generated by
L<Module::Build>.

This usually happens if you try to use an Alien module from the lib directory as part of the
Alien's distribution.  You need to build the alien and use C<blib/lib> instead of C<lib> or
install the alien and use the installed path.

It is also possible that your Alien installer is not set up correctly.  Make sure your
C<Makefile.PL> is using L<Alien::Build::MM> correctly.

=head2 I have a question not listed here!

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

=over 4

=item C<#native> on irc.perl.org