1Alien::Build::Manual::AUlsieernUCsoenrt(r3i)buted Perl DAolciuemne:n:tBautiilodn::Manual::AlienUser(3)
2
6 Alien::Build::Manual::AlienUser - Alien user documentation
7
9 version 1.93
10
12 perldoc Alien::Build::Manual::AlienUser
13
15 This document is intended for a user of an Alien::Base based Alien
16 module's user. Although specifically geared for Alien::Base
17 subclasses, it may have some useful hints for Alien in general.
18 Full working examples of how to use an Alien module are also bundled
20 with Alien::Build in the distribution's "example/user" directory.
21 Those examples use Alien::xz, which uses alienfile + Alien::Build +
22 Alien::Base.
23 The following documentation will assume you are trying to use an Alien
25 called "Alien::Foo" which provides the library "libfoo" and the command
26 line tool "foo". Many Aliens will only provide one or the other.
27 The best interface to use for using Alien::Base based aliens is
29 Alien::Base::Wrapper. This allows you to combine multiple aliens
30 together and handles a number of corner obscure corner cases that using
31 Aliens directly does not. Also as of 0.64, Alien::Base::Wrapper comes
32 bundled with Alien::Build and Alien::Base anyway, so it is not an extra
33 dependency.
34 What follows are the main use cases.
36 Module::Build
38 use Module::Build;
39 use Alien::Base::Wrapper qw( Alien::Foo !export );
40 use Alien::Foo;
41 my $build = Module::Build->new(
43 ...
44 configure_requires => {
45 'Alien::Base::Wrapper' => '0',
46 'Alien::Foo' => '0',
47 ...
48 },
49 Alien::Base::Wrapper->mb_args,
50 ...
51 );
52 $build->create_build_script;
54 The key gotcha for using Alien from a "Build.PL" for an XS module is
56 remembering to explicitly making the Alien a configuration
57 prerequisite.
58 ExtUtils::MakeMaker
60 use ExtUtils::MakeMaker;
61 use Alien::Base::Wrapper qw( Alien::Foo !export );
62 WriteMakefile(
64 ...
65 CONFIGURE_REQUIRES => {
66 'Alien::Base::Wrapper' => '0',
67 'Alien::Foo' => '0',
68 },
69 Alien::Base::Wrapper->mm_args,
70 ...
71 );
72 MakeMaker is similar, make sure that you explicitly make your Alien a
74 configure prerequisite.
75 Inline::C / Inline::CPP
77 use Inline 0.56 with => 'Alien::Foo';
78 Although not widely used, Inline::C and Inline::CPP can be configured
80 to use an Alien::Base based Alien with the "with" keyword.
81 ExtUtils::Depends
83 use ExtUtils::MakeMaker;
84 use ExtUtils::Depends;
85 my $pkg = ExtUtils::Depends->new("Alien::Foo");
87 WriteMakefile(
89 ...
90 $pkg->get_makefile_vars,
91 ...
92 );
93 ExtUtils::Depends works similar to Alien::Base::Wrapper, but uses the
95 Inline interface under the covers.
96 Dist::Zilla
98 [@Filter]
99 -bundle = @Basic
100 -remove = MakeMaker
101 [Prereqs / ConfigureRequires]
103 Alien::Foo = 0
104 [MakeMaker::Awesome]
106 header = use Alien::Base::Wrapper qw( Alien::Foo !export );
107 WriteMakefile_arg = Alien::Base::Wrapper->mm_args
108 FFI::Platypus
110 use FFI::Platypus;
111 use Alien::Foo;
112 my $ffi = FFI::Platypus->new(
114 lib => [ Alien::Foo->dynamic_libs ],
115 );
116 Not all Aliens provide dynamic libraries, but those that do can be used
118 by FFI::Platypus. Unlike an XS module, these need to be a regular run
119 time prerequisite.
120 Inline::C
122 use Inline with => 'Alien::Foo';
123 use Inline C => <<~'END';
124 #include <foo.h>
125 const char *my_foo_wrapper()
127 {
128 foo();
129 }
130 END
131 sub exported_foo()
133 {
134 my_foo_wrapper();
135 }
136 tool
138 use Alien::Foo;
139 use Env qw( @PATH );
140 unshift @PATH, Alien::Foo->bin_dir;
142 system 'foo', '--bar', '--baz';
143 Some Aliens provide tools instead of or in addition to a library. You
145 need to add them to the "PATH" environment variable though. (Unless
146 the tool is already provided by the system, in which case it is already
147 in the path and the "bin_dir" method will return an empty list).
148
150 ALIEN_INSTALL_TYPE
151 Although the recommended way for a consumer to use an Alien::Base
152 based Alien is to declare it as a static configure and build-time
153 dependency, some consumers may prefer to fallback on using an Alien
154 only when the consumer itself cannot detect the necessary package.
155 In some cases the consumer may want the user to opt-in to using an
156 Alien before requiring it.
157 To keep the interface consistent among Aliens, the consumer of the
159 fallback opt-in Alien may fallback on the Alien if the environment
160 variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is
161 that by setting this environment variable the user is aware that
162 Alien modules may be installed and have indicated consent. The
163 actual implementation of this, by its nature would have to be in
164 the consuming CPAN module.
165 This behavior should be documented in the consumer's POD.
167 See "ENVIRONMENT" in Alien::Build for more details on the usage of
169 this environment variable.
170
172 Author: Graham Ollis <plicease@cpan.org>
173 Contributors:
175 Diab Jerius (DJERIUS)
177 Roy Storey (KIWIROY)
179 Ilya Pavlov
181 David Mertens (run4flat)
183 Mark Nunberg (mordy, mnunberg)
185 Christian Walde (Mithaldu)
187 Brian Wightman (MidLifeXis)
189 Zaki Mughal (zmughal)
191 mohawk (mohawk2, ETJ)
193 Vikas N Kumar (vikasnkumar)
195 Flavio Poletti (polettix)
197 Salvador Fandiño (salva)
199 Gianni Ceccarelli (dakkar)
201 Pavel Shaydo (zwon, trinitum)
203 Kang-min Liu (劉康民, gugod)
205 Nicholas Shipp (nshp)
207 Juan Julián Merelo Guervós (JJ)
209 Joel Berger (JBERGER)
211 Petr Pisar (ppisar)
213 Lance Wicks (LANCEW)
215 Ahmad Fatoum (a3f, ATHREEF)
217 José Joaquín Atria (JJATRIA)
219 Duke Leto (LETO)
221 Shoichi Kaji (SKAJI)
223 Shawn Laffan (SLAFFAN)
225 Paul Evans (leonerd, PEVANS)
227
229 This software is copyright (c) 2011-2019 by Graham Ollis.
230 This is free software; you can redistribute it and/or modify it under
232 the same terms as the Perl 5 programming language system itself.
233perl v5.30.1 2019-12-10Alien::Build::Manual::AlienUser(3)