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.17
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        use FFI::Platypus;
113        use Alien::Foo;
114
115        my $ffi = FFI::Platypus->new(
116          lib => [ Alien::Foo->dynamic_libs ],
117        );
118
119       Not all Aliens provide dynamic libraries, but those that do can be used
120       by FFI::Platypus.  Unlike an XS module, these need to be a regular run
121       time prerequisite.
122
123   Inline::C
124        use Inline with => 'Alien::Foo';
125        use Inline C => <<~'END';
126          #include <foo.h>
127
128          const char *my_foo_wrapper()
129          {
130            foo();
131          }
132          END
133
134        sub exported_foo()
135        {
136          my_foo_wrapper();
137        }
138
139   tool
140        use Alien::Foo;
141        use Env qw( @PATH );
142
143        unshift @PATH, Alien::Foo->bin_dir;
144        system 'foo', '--bar', '--baz';
145
146       Some Aliens provide tools instead of or in addition to a library.  You
147       need to add them to the "PATH" environment variable though.  (Unless
148       the tool is already provided by the system, in which case it is already
149       in the path and the "bin_dir" method will return an empty list).
150

ENVIRONMENT

152       ALIEN_INSTALL_TYPE
153           Although the recommended way for a consumer to use an Alien::Base
154           based Alien is to declare it as a static configure and build-time
155           dependency, some consumers may prefer to fallback on using an Alien
156           only when the consumer itself cannot detect the necessary package.
157           In some cases the consumer may want the user to opt-in to using an
158           Alien before requiring it.
159
160           To keep the interface consistent among Aliens, the consumer of the
161           fallback opt-in Alien may fallback on the Alien if the environment
162           variable "ALIEN_INSTALL_TYPE" is set to any value. The rationale is
163           that by setting this environment variable the user is aware that
164           Alien modules may be installed and have indicated consent.  The
165           actual implementation of this, by its nature would have to be in
166           the consuming CPAN module.
167
168           This behavior should be documented in the consumer's POD.
169
170           See "ENVIRONMENT" in Alien::Build for more details on the usage of
171           this environment variable.
172

AUTHOR

174       Author: Graham Ollis <plicease@cpan.org>
175
176       Contributors:
177
178       Diab Jerius (DJERIUS)
179
180       Roy Storey (KIWIROY)
181
182       Ilya Pavlov
183
184       David Mertens (run4flat)
185
186       Mark Nunberg (mordy, mnunberg)
187
188       Christian Walde (Mithaldu)
189
190       Brian Wightman (MidLifeXis)
191
192       Zaki Mughal (zmughal)
193
194       mohawk (mohawk2, ETJ)
195
196       Vikas N Kumar (vikasnkumar)
197
198       Flavio Poletti (polettix)
199
200       Salvador Fandiño (salva)
201
202       Gianni Ceccarelli (dakkar)
203
204       Pavel Shaydo (zwon, trinitum)
205
206       Kang-min Liu (劉康民, gugod)
207
208       Nicholas Shipp (nshp)
209
210       Juan Julián Merelo Guervós (JJ)
211
212       Joel Berger (JBERGER)
213
214       Petr Pisar (ppisar)
215
216       Lance Wicks (LANCEW)
217
218       Ahmad Fatoum (a3f, ATHREEF)
219
220       José Joaquín Atria (JJATRIA)
221
222       Duke Leto (LETO)
223
224       Shoichi Kaji (SKAJI)
225
226       Shawn Laffan (SLAFFAN)
227
228       Paul Evans (leonerd, PEVANS)
229

231       This software is copyright (c) 2011-2020 by Graham Ollis.
232
233       This is free software; you can redistribute it and/or modify it under
234       the same terms as the Perl 5 programming language system itself.
235
236
237
238perl v5.30.2                      2020-03-20Alien::Build::Manual::AlienUser(3)
Impressum