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 1.55
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   Module::Build
38        use Module::Build;
39        use Alien::Base::Wrapper qw( Alien::Foo !export );
40        use Alien::Foo;
41
42        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
53        $build->create_build_script;
54
55       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
59   ExtUtils::MakeMaker
60        use ExtUtils::MakeMaker;
61        use Alien::Base::Wrapper qw( Alien::Foo !export );
62
63        WriteMakefile(
64          ...
65          CONFIGURE_REQUIRES => {
66            'Alien::Base::Wrapper' => '0',
67            'Alien::Foo'           => '0',
68          },
69          Alien::Base::Wrapper->mm_args
70          ...
71        );
72
73       MakeMaker is similar, make sure that you explicitly make your Alien a
74       configure prerequisite.
75
76   Dist::Zilla
77        [@Filter]
78        -bundle = @Basic
79        -remove = MakeMaker
80
81        [Prereqs / ConfigureRequires]
82        Alien::Foo = 0
83
84        [MakeMaker::Awesome]
85        header = use Alien::Base::Wrapper qw( Alien::Foo !export );
86        WriteMakefile_arg = Alien::Base::Wrapper->mm_args
87
88   FFI::Platypus
89        use FFI::Platypus;
90        use Alien::Foo;
91
92        my $ffi = FFI::Platypus->new(
93          lib => [ Alien::Foo->dynamic_libs ],
94        );
95
96       Not all Aliens provide dynamic libraries, but those that do can be used
97       by FFI::Platypus.  Unlike an XS module, these need to be a regular run
98       time prerequisite.
99
100   Inline::C
101        use Inline with => 'Alien::Foo';
102        use Inline C => <<~'END';
103          #include <foo.h>
104
105          const char *my_foo_wrapper()
106          {
107            foo();
108          }
109          END
110
111        sub exported_foo()
112        {
113          my_foo_wrapper();
114        }
115
116   tool
117        use Alien::Foo;
118        use Env qw( @PATH );
119
120        unshift @ENV, Alien::Foo->bin_dir;
121        system 'foo', '--bar', '--baz';
122
123       Some Aliens provide tools instead of or in addition to a library.  You
124       need to add them to the "PATH" environment variable though.  (Unless
125       the tool is already provided by the system, in which case it is already
126       in the path and the "bin_dir" method will return an empty list).
127

AUTHOR

129       Author: Graham Ollis <plicease@cpan.org>
130
131       Contributors:
132
133       Diab Jerius (DJERIUS)
134
135       Roy Storey
136
137       Ilya Pavlov
138
139       David Mertens (run4flat)
140
141       Mark Nunberg (mordy, mnunberg)
142
143       Christian Walde (Mithaldu)
144
145       Brian Wightman (MidLifeXis)
146
147       Zaki Mughal (zmughal)
148
149       mohawk (mohawk2, ETJ)
150
151       Vikas N Kumar (vikasnkumar)
152
153       Flavio Poletti (polettix)
154
155       Salvador Fandiño (salva)
156
157       Gianni Ceccarelli (dakkar)
158
159       Pavel Shaydo (zwon, trinitum)
160
161       Kang-min Liu (劉康民, gugod)
162
163       Nicholas Shipp (nshp)
164
165       Juan Julián Merelo Guervós (JJ)
166
167       Joel Berger (JBERGER)
168
169       Petr Pisar (ppisar)
170
171       Lance Wicks (LANCEW)
172
173       Ahmad Fatoum (a3f, ATHREEF)
174
175       José Joaquín Atria (JJATRIA)
176
177       Duke Leto (LETO)
178
179       Shoichi Kaji (SKAJI)
180
181       Shawn Laffan (SLAFFAN)
182
183       Paul Evans (leonerd, PEVANS)
184

186       This software is copyright (c) 2011-2018 by Graham Ollis.
187
188       This is free software; you can redistribute it and/or modify it under
189       the same terms as the Perl 5 programming language system itself.
190
191
192
193perl v5.28.1                      2019-02-24Alien::Build::Manual::AlienUser(3)
Impressum