Alien::Build::Manual::AlienUser(3pm)

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.80
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

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

COPYRIGHT AND LICENSE

258       This software is copyright (c) 2011-2022 by Graham Ollis.
259
260       This is free software; you can redistribute it and/or modify it under
261       the same terms as the Perl 5 programming language system itself.
262
263
264
265perl v5.36.1                      2023-05-15Alien::Build::Manual::AlienUser(3)