1Alien::Base::ModuleBuilUds:e:rAuCtohnotrriinbgu(t3e)d PeArllieDno:c:uBmaesnet:a:tMioodnuleBuild::Authoring(3)
2
6 Alien::Base::ModuleBuild::Authoring - Authoring an "Alien::" module
7 using Alien::Base::ModuleBuild
8
10 version 1.17
11
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 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
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
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 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 # file: Alien-MyLibrary/Build.PL
55 use Alien::Base::ModuleBuild;
56 my $builder = Alien::Base::ModuleBuild->new(...);
57 $builder->create_build_script;
58 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 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 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 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 Alien::Base for Building
86 "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 # file: Some-Module-MyLibrary/Build.PL
93 use Module::Build;
94 use Alien::MyLibrary;
95 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 Additional information can be gotten from the "config" method.
105 Alien::Base for Run-Time Provision
107 "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 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
116 package Alien::MyLibrary;
117 use parent 'Alien::Base';
119 1;
121 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 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
130 package Some::Module::MyLibrary;
131 use Alien::MyLibrary;
133 our $VERSION = '0.54';
134 require XSLoader;
136 XSLoader::load('Some::Module::MyLibrary', $VERSION);
137 # your code
139
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 • Acme::Alien::DontPanic -- An example "Alien::" module which
145 provides libdontpanic.so. It provides the C function "answer" which
146 is simply:
147 int answer () { return 42 }
149 • 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 Additionally, there exist in-production "Alien::" distributions that
155 serve as de-facto tests of Alien::Base's networking components:
156 • Alien::LibYAML -- Builds and installs libyaml, acquiring the
158 library archive from its hosted location via
159 "Alien::Base::Repository::HTTP".
160 • Alien::GSL -- Builds and installs libgsl, acquiring the library
162 source archive via "Alien::Base::Repository::FTP".
163 • 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
171 • Module::Build
172 • Alien
174 • Alien::Base
176 • Alien::Base::FAQ
178
180 Original author: Joel A Berger <joel.a.berger@gmail.com>
181 Current maintainer: Graham Ollis <plicease@cpan.org>
183 Contributors:
185 David Mertens (run4flat)
187 Mark Nunberg (mordy, mnunberg)
189 Christian Walde (Mithaldu)
191 Brian Wightman (MidLifeXis)
193 Graham Ollis (plicease)
195 Zaki Mughal (zmughal)
197 mohawk2
199 Vikas N Kumar (vikasnkumar)
201 Flavio Poletti (polettix)
203 Salvador Fandiño (salva)
205 Gianni Ceccarelli (dakkar)
207 Pavel Shaydo (zwon, trinitum)
209 Kang-min Liu (劉康民, gugod)
211 Nicholas Shipp (nshp)
213 Petr Písař (ppisar)
215 Alberto Simões (ambs)
217
219 This software is copyright (c) 2012-2022 by Joel A Berger.
220 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.
223perl v5.36.0 2023-01A-l1i9en::Base::ModuleBuild::Authoring(3)