1Alien::Build::Manual::AUlsieernUCsoenrt(r3i)buted Perl DAolciuemne:n:tBautiilodn::Manual::AlienUser(3)
2
3
4

NAME

6       Alien::Build::Manual::AlienUser - Alien user documentation
7

VERSION

9       version 2.45
10

SYNOPSIS

12        perldoc Alien::Build::Manual::AlienUser
13

DESCRIPTION

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
19       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
24       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
28       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
35       What follows are the main use cases.
36
37   ExtUtils::MakeMaker
38        use ExtUtils::MakeMaker;
39        use Alien::Base::Wrapper ();
40
41        WriteMakefile(
42          Alien::Base::Wrapper->new('Alien::Foo')->mm_args2(
43            NAME => 'FOO::XS',
44            ...
45          ),
46        );
47
48       Alien::Base::Wrapper will take a hash of "WriteMakefile" arguments and
49       insert the appropriate compiler and linker flags for you.  This is
50       recommended over doing this yourself as the exact incantation to get
51       EUMM to work is tricky to get right.
52
53       The "mm_args2" method will also set your "CONFIGURE_REQUIRES" for
54       Alien::Base::Wrapper, ExtUtils::MakeMaker and any aliens that you
55       specify.
56
57   Module::Build
58        use Module::Build;
59        use Alien::Base::Wrapper qw( Alien::Foo !export );
60        use Alien::Foo;
61
62        my $build = Module::Build->new(
63          ...
64          configure_requires => {
65            'Alien::Base::Wrapper' => '0',
66            'Alien::Foo'           => '0',
67            ...
68          },
69          Alien::Base::Wrapper->mb_args,
70          ...
71        );
72
73        $build->create_build_script;
74
75       For Module::Build you can also use Alien::Base::Wrapper, but you will
76       have to specify the "configure_requires" yourself.
77
78   Inline::C / Inline::CPP
79        use Inline 0.56 with => 'Alien::Foo';
80
81       Inline::C and Inline::CPP can be configured to use an Alien::Base based
82       Alien with the "with" keyword.
83
84   ExtUtils::Depends
85        use ExtUtils::MakeMaker;
86        use ExtUtils::Depends;
87
88        my $pkg = ExtUtils::Depends->new("Alien::Foo");
89
90        WriteMakefile(
91          ...
92          $pkg->get_makefile_vars,
93          ...
94        );
95
96       ExtUtils::Depends works similar to Alien::Base::Wrapper, but uses the
97       Inline interface under the covers.
98
99   Dist::Zilla
100        [@Filter]
101        -bundle = @Basic
102        -remove = MakeMaker
103
104        [Prereqs / ConfigureRequires]
105        Alien::Foo = 0
106
107        [MakeMaker::Awesome]
108        header = use Alien::Base::Wrapper qw( Alien::Foo !export );
109        WriteMakefile_arg = Alien::Base::Wrapper->mm_args
110
111   FFI::Platypus
112       Requires "Alien::Foo" always:
113
114        use FFI::Platypus;
115        use Alien::Foo;
116
117        my $ffi = FFI::Platypus->new(
118          lib => [ Alien::Foo->dynamic_libs ],
119        );
120
121       Use "Alien::Foo" in fallback mode:
122
123        use FFI::Platypus;
124        use FFI::CheckLib 0.28 qw( find_lib_or_die );
125        use Alien::Foo;
126
127        my $ffi = FFI::Platypus->new(
128          lib => [ find_lib_or_die lib => 'foo', alien => ['Alien::Foo'] ],
129        );
130
131       If you are going to always require an Alien you can just call
132       "dynamic_libs" and pass it into FFI::Platypus' lib method.  You should
133       consider using FFI::CheckLib to use the Alien in fallback mode instead.
134       This way you only need to install the Alien if the system doesn't
135       provide it.
136
137       For fallback mode to work correctly you need to be using FFI::CheckLib
138       0.28 or better.
139
140   Inline::C
141        use Inline with => 'Alien::Foo';
142        use Inline C => <<~'END';
143          #include <foo.h>
144
145          const char *my_foo_wrapper()
146          {
147            foo();
148          }
149          END
150
151        sub exported_foo()
152        {
153          my_foo_wrapper();
154        }
155
156   tool
157        use Alien::Foo;
158        use Env qw( @PATH );
159
160        unshift @PATH, Alien::Foo->bin_dir;
161        system 'foo', '--bar', '--baz';
162
163       Some Aliens provide tools instead of or in addition to a library.  You
164       need to add them to the "PATH" environment variable though.  (Unless
165       the tool is already provided by the system, in which case it is already
166       in the path and the "bin_dir" method will return an empty list).
167

ENVIRONMENT

169       ALIEN_INSTALL_TYPE
170           Although the recommended way for a consumer to use an Alien::Base
171           based Alien is to declare it as a static configure and build-time
172           dependency, some consumers may prefer to fallback on using an Alien
173           only when the consumer itself cannot detect the necessary package.
174           In some cases the consumer may want the user to opt-in to using an
175           Alien before requiring it.
176
177           To keep the interface consistent among Aliens, the consumer of the
178           fallback opt-in Alien may fallback on the Alien if the environment
179           variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is
180           that by setting this environment variable the user is aware that
181           Alien modules may be installed and have indicated consent.  The
182           actual implementation of this, by its nature would have to be in
183           the consuming CPAN module.
184
185           This behavior should be documented in the consumer's POD.
186
187           See "ENVIRONMENT" in Alien::Build for more details on the usage of
188           this environment variable.
189

AUTHOR

191       Author: Graham Ollis <plicease@cpan.org>
192
193       Contributors:
194
195       Diab Jerius (DJERIUS)
196
197       Roy Storey (KIWIROY)
198
199       Ilya Pavlov
200
201       David Mertens (run4flat)
202
203       Mark Nunberg (mordy, mnunberg)
204
205       Christian Walde (Mithaldu)
206
207       Brian Wightman (MidLifeXis)
208
209       Zaki Mughal (zmughal)
210
211       mohawk (mohawk2, ETJ)
212
213       Vikas N Kumar (vikasnkumar)
214
215       Flavio Poletti (polettix)
216
217       Salvador Fandiño (salva)
218
219       Gianni Ceccarelli (dakkar)
220
221       Pavel Shaydo (zwon, trinitum)
222
223       Kang-min Liu (劉康民, gugod)
224
225       Nicholas Shipp (nshp)
226
227       Juan Julián Merelo Guervós (JJ)
228
229       Joel Berger (JBERGER)
230
231       Petr Písař (ppisar)
232
233       Lance Wicks (LANCEW)
234
235       Ahmad Fatoum (a3f, ATHREEF)
236
237       José Joaquín Atria (JJATRIA)
238
239       Duke Leto (LETO)
240
241       Shoichi Kaji (SKAJI)
242
243       Shawn Laffan (SLAFFAN)
244
245       Paul Evans (leonerd, PEVANS)
246
247       Håkon Hægland (hakonhagland, HAKONH)
248
249       nick nauwelaerts (INPHOBIA)
250

252       This software is copyright (c) 2011-2020 by Graham Ollis.
253
254       This is free software; you can redistribute it and/or modify it under
255       the same terms as the Perl 5 programming language system itself.
256
257
258
259perl v5.34.0                      2021-10-29Alien::Build::Manual::AlienUser(3)
Impressum