1Alien::Base::ModuleBuilUds:e:rAuCtohnotrriinbgu(t3e)d PeArllieDno:c:uBmaesnet:a:tMioodnuleBuild::Authoring(3)
2
3
4

NAME

6       Alien::Base::ModuleBuild::Authoring - Authoring an "Alien::" module
7       using Alien::Base::ModuleBuild
8

VERSION

10       version 1.17
11

DESCRIPTION

13       NOTE: Please consider for new development of Aliens that you use
14       Alien::Build and alienfile instead.  Like Alien::Base::ModuleBuild they
15       work with Alien::Base.  Unlike Alien::Base::ModuleBuild they are more
16       easily customized and handle a number of corner cases better.  For a
17       good place to start, please see Alien::Build::Manual::AlienAuthor.
18       Although the Alien-Base / Alien-Build team will continue to maintain
19       this module, (we will continue to fix bugs where appropriate), we
20       aren't adding any new features to this module.
21
22       Congratulations! You have made the decision to help the Perl community
23       by providing a C library via CPAN. The Alien namespace has been
24       instrumental in providing C libraries for many years, but authoring
25       those modules has been a commitment that most authors weren't willing
26       to take on. Alien::Base tries to ease that pain by providing most of
27       the needed functionality; usually authors should only need a little
28       boilerplate and configuration!
29

STATUS

31       Alien::Base is under active development.  The API is relatively stable,
32       although breaking changes may be introduced if the rewards are deemed
33       greater than the pains that they produce.
34

ECOSYSTEM

36       The Alien::Base ecosystem is made up of several elements. Some of these
37       elements are the base classes in the distribution itself. Of course, no
38       ecosystem is complete without inhabitants, therefore, it is also
39       important to consider the users of these base classes. This
40       documentation will assume that you are writing "Alien::MyLibrary" which
41       provides libmylibrary.so. Further it will assume that you or someone
42       else is going to use this module/library to write
43       "Some::Module::MyLibrary". Finally an end user might use that module to
44       write myscript.pl.
45
46   Alien::Base::ModuleBuild
47       Alien::Base::ModuleBuild provides a base class, utility methods and
48       configuration handling for the build/install phase of the library. It
49       is itself a subclass of Module::Build, which is what supports the
50       building and installing of the surrounding "Alien::" module.
51       "Alien::MyLibrary"'s Build.PL file will use Alien::Base::ModuleBuild to
52       create its builder object.
53
54        # file: Alien-MyLibrary/Build.PL
55        use Alien::Base::ModuleBuild;
56        my $builder = Alien::Base::ModuleBuild->new(...);
57        $builder->create_build_script;
58
59       This is just like you would do for Module::Build, except that there
60       will be a few additional configuration parameters (see
61       Alien::Base::ModuleBuild::API).
62
63       Alien::Base::ModuleBuild adds the additional build actions "alien_code"
64       and "alien_install". These actions need never be run directly, the
65       usual "build" action (usually seen as "./Build") and "install"
66       ("./Build install") will call them for you. The "alien_code" action is
67       responsible for finding, downloading, extracting and building the
68       external library (the commands specified in builder parameter
69       "alien_build_commands"). The "alien_install" action is responsible for
70       installing the library into its final destination.
71
72       The "./Build test" command will invoke any library tests specified in
73       "alien_test_commands", though none are defined by default. Finally
74       "./Build install" will invoke whatever "alien_install_commands" were
75       specified.
76
77   Alien::Base
78       Alien::Base is the base class of "Alien::MyLibrary". In this context,
79       Alien::Base has two distinct uses. First it is used by
80       "Alien::MyLibrary" to provide the build information/flags for building
81       "Some::Module::MyLibrary". Secondly it is used (again through
82       "Alien::MyLibrary") to provide run-time access to libmylibrary.so to
83       "Some::Module::MyLibrary".
84
85       Alien::Base for Building
86
87       "Alien::MyLibrary" is called by "Some::Library::MyLibrary"'s build
88       script, either Build.PL or Makefile.PL. Most of the functionality can
89       be utilized through class method calls, though creating an object can
90       save a few keystrokes.
91
92        # file: Some-Module-MyLibrary/Build.PL
93        use Module::Build;
94        use Alien::MyLibrary;
95
96        my $alien = Alien::MyLibrary->new;
97        my $builder = Module::Build->new(
98          ...
99          extra_compiler_flags => $alien->cflags(),
100          extra_linker_flags   => $alien->libs(),
101        );
102        $builder->create_build_script;
103
104       Additional information can be gotten from the "config" method.
105
106       Alien::Base for Run-Time Provision
107
108       "Alien::MyLibrary" must be a subclass of Alien::Base. This provides the
109       "import" method, which does the run-time provisioning so that when the
110       XS file is loaded, it can find libmylibrary.so. The "import" method
111       does this by pre-loading the library via "DynaLoader::dl_load_file"
112       which is a platform-independent wrapper for "dlopen" or your system's
113       equivalent. It no longer appends to $ENV{LD_RUN_PATH}.
114
115        # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
116        package Alien::MyLibrary;
117
118        use parent 'Alien::Base';
119
120        1;
121
122       Finally, "Alien::MyLibrary" must also be called by
123       "Some::Library::MyLibrary" before "DynaLoader::bootstrap" or
124       "XSLoader::load". The "use" directive is recommended, however if you
125       must use "require" then be sure to call the "import" method too.
126       Without this "import" call, the loader doesn't know where to find
127       libmylibrary.so.
128
129        # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
130        package Some::Module::MyLibrary;
131
132        use Alien::MyLibrary;
133        our $VERSION = '0.54';
134
135        require XSLoader;
136        XSLoader::load('Some::Module::MyLibrary', $VERSION);
137
138        # your code
139

EXAMPLES

141       The example code that was housed in this distribution during alpha
142       phase has been moved to two different CPAN distributions. Those are:
143
144       •   Acme::Alien::DontPanic -- An example "Alien::" module which
145           provides libdontpanic.so. It provides the C function "answer" which
146           is simply:
147
148            int answer () { return 42 }
149
150       •   Acme::Ford::Prefect -- An XS module which provides the Perl-level
151           access to "answer". It relies on libdontpanic.so and uses
152           Acme::Alien::DontPanic to locate/load it.
153
154       Additionally, there exist in-production "Alien::" distributions that
155       serve as de-facto tests of Alien::Base's networking components:
156
157       •   Alien::LibYAML -- Builds and installs libyaml, acquiring the
158           library archive from its hosted location via
159           "Alien::Base::Repository::HTTP".
160
161       •   Alien::GSL -- Builds and installs libgsl, acquiring the library
162           source archive via "Alien::Base::Repository::FTP".
163
164       •   Alien::gmake -- Builds and installs GNU make.  Rather than being a
165           library, this is a tool used to build other tools and libraries.
166           It is useful for other Alien modules that require the GNU version
167           of make.  It also demonstrates the use of Alien::Base for providing
168           tools rather than libraries.
169

SEE ALSO

171       •   Module::Build
172
173       •   Alien
174
175       •   Alien::Base
176
177       •   Alien::Base::FAQ
178

AUTHOR

180       Original author: Joel A Berger <joel.a.berger@gmail.com>
181
182       Current maintainer: Graham Ollis <plicease@cpan.org>
183
184       Contributors:
185
186       David Mertens (run4flat)
187
188       Mark Nunberg (mordy, mnunberg)
189
190       Christian Walde (Mithaldu)
191
192       Brian Wightman (MidLifeXis)
193
194       Graham Ollis (plicease)
195
196       Zaki Mughal (zmughal)
197
198       mohawk2
199
200       Vikas N Kumar (vikasnkumar)
201
202       Flavio Poletti (polettix)
203
204       Salvador Fandiño (salva)
205
206       Gianni Ceccarelli (dakkar)
207
208       Pavel Shaydo (zwon, trinitum)
209
210       Kang-min Liu (劉康民, gugod)
211
212       Nicholas Shipp (nshp)
213
214       Petr Písař (ppisar)
215
216       Alberto Simões (ambs)
217
219       This software is copyright (c) 2012-2022 by Joel A Berger.
220
221       This is free software; you can redistribute it and/or modify it under
222       the same terms as the Perl 5 programming language system itself.
223
224
225
226perl v5.36.0                      2023-01A-l1i9en::Base::ModuleBuild::Authoring(3)
Impressum