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 NOTE: Please consider for new development of Aliens that you use
11 Alien::Build and alienfile instead. Like Alien::Base::ModuleBuild they
12 work with Alien::Base. Unlike Alien::Base::Module::Build they are more
13 easily customized and handle a number of corner cases better. For a
14 good place to start, please see Alien::Build::Manual::AlienAuthor.
15 Although the Alien-Base / Alien-Build team will continue to maintain
16 this module, (we will continue to fix bugs where appropriate), we
17 aren't adding any new features to this module.
18 Congratulations! You have made the decision to help the Perl community
20 by providing a C library via CPAN. The Alien namespace has been
21 instrumental in providing C libraries for many years, but authoring
22 those modules has been a commitment that most authors weren't willing
23 to take on. Alien::Base tries to ease that pain by providing most of
24 the needed functionality; usually authors should only need a little
25 boilerplate and configuration!
26
28 Alien::Base is under active development. The API is relatively stable,
29 although breaking changes may be introduced if the rewards are deemed
30 greater than the pains that they produce.
31
33 The Alien::Base ecosystem is made up of several elements. Some of these
34 elements are the base classes in the distribution itself. Of course, no
35 ecosystem is complete without inhabitants, therefore, it is also
36 important to consider the users of these base classes. This
37 documentation will assume that you are writing "Alien::MyLibrary" which
38 provides libmylibrary.so. Further it will assume that you or someone
39 else is going to use this module/library to write
40 "Some::Module::MyLibrary". Finally an end user might use that module to
41 write myscript.pl.
42 Alien::Base::ModuleBuild
44 Alien::Base::ModuleBuild provides a base class, utility methods and
45 configuration handling for the build/install phase of the library. It
46 is itself a subclass of Module::Build, which is what supports the
47 building and installing of the surrouning "Alien::" module.
48 "Alien::MyLibrary"'s Build.PL file will use Alien::Base::ModuleBuild to
49 create its builder object.
50 # file: Alien-MyLibrary/Build.PL
52 use Alien::Base::ModuleBuild;
53 my $builder = Alien::Base::ModuleBuild->new(...);
54 $builder->create_build_script;
55 This is just like you would do for Module::Build, except that there
57 will be a few additional configuration parameters (see
58 Alien::Base::ModuleBuild::API).
59 Alien::Base::ModuleBuild adds the additional build actions "alien_code"
61 and "alien_install". These actions need never be run directly, the
62 usual "build" action (usually seen as "./Build") and "install"
63 ("./Build install") will call them for you. The "alien_code" action is
64 responsible for finding, downloading, extracting and building the
65 external libary (the commands specified in builder parameter
66 "alien_build_commands"). The "alien_install" action is responsible for
67 installing the library into its final destination.
68 The "./Build test" command will invoke any library tests specified in
70 "alien_test_commands", though none are defined by default. Finally
71 "./Build install" will invoke whatever "alien_install_commands" were
72 specified.
73 Alien::Base
75 Alien::Base is the base class of "Alien::MyLibrary". In this context,
76 Alien::Base has two distinct uses. First it is used by
77 "Alien::MyLibrary" to provide the build information/flags for building
78 "Some::Module::MyLibrary". Secondly it is used (again through
79 "Alien::MyLibrary") to provide run-time access to libmylibrary.so to
80 "Some::Module::MyLibrary".
81 Alien::Base for Building
83 "Alien::MyLibrary" is called by "Some::Library::MyLibrary"'s build
85 script, either Build.PL or Makefile.PL. Most of the functionality can
86 be utilized through class method calls, though creating an object can
87 save a few keystrokes.
88 # file: Some-Module-MyLibrary/Build.PL
90 use Module::Build;
91 use Alien::MyLibrary;
92 my $alien = Alien::MyLibrary->new;
94 my $builder = Module::Build->new(
95 ...
96 extra_compiler_flags => $alien->cflags(),
97 extra_linker_flags => $alien->libs(),
98 );
99 $builder->create_build_script;
100 Additional information can be gotten from the "config" method.
102 Alien::Base for Run-Time Provision
104 "Alien::MyLibrary" must be a subclass of Alien::Base. This provides the
106 "import" method, which does the run-time provisioning so that when the
107 XS file is loaded, it can find libmylibrary.so. The "import" method
108 does this by pre-loading the library via "DynaLoader::dl_load_file"
109 which is a platform-independent wrapper for "dlopen" or your system's
110 equivalent. It no longer appends to $ENV{LD_RUN_PATH}.
111 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
113 package Alien::MyLibrary;
114 use parent 'Alien::Base';
116 1;
118 Finally, "Alien::MyLibrary" must also be called by
120 "Some::Library::MyLibrary" before "DynaLoader::bootstrap" or
121 "XSLoader::load". The "use" directive is recommended, however if you
122 must use "require" then be sure to call the "import" method too.
123 Without this "import" call, the loader doesn't know where to find
124 libmylibrary.so.
125 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
127 package Some::Module::MyLibrary;
128 use Alien::MyLibrary;
130 our $VERSION = '0.54';
131 require XSLoader;
133 XSLoader::load('Some::Module::MyLibrary', $VERSION);
134 # your code
136
138 The example code that was housed in this distribution during alpha
139 phase has been moved to two different CPAN distributions. Those are:
140 · Acme::Alien::DontPanic -- An example "Alien::" module which
142 provides libdontpanic.so. It provides the C function "answer" which
143 is simply:
144 int answer () { return 42 }
146 · Acme::Ford::Prefect -- An XS module which provides the Perl-level
148 access to "answer". It relies on libdontpanic.so and uses
149 Acme::Alien::DontPanic to locate/load it.
150 Additionally, there exist in-production "Alien::" distributions that
152 serve as de-facto tests of Alien::Base's networking components:
153 · Alien::LibYAML -- Builds and installs libyaml, acquiring the
155 library archive from its hosted location via
156 "Alien::Base::Repository::HTTP".
157 · Alien::GSL -- Builds and installs libgsl, aquiring the library
159 source archive via "Alien::Base::Repository::FTP".
160 · Alien::gmake -- Builds and installs GNU make. Rather than being a
162 library, this is a tool used to build other tools and libraries.
163 It is useful for other Alien modules that require the GNU version
164 of make. It also demonstrates the use of Alien::Base for providing
165 tools rather than libraries.
166
168 Joel Berger <joel.a.berger@gmail.com>
169
171 · Module::Build
172 · Alien
174 · Alien::Base
176 · Alien::Base::FAQ
178
180 <http://github.com/Perl5-Alien/Alien-Base-ModuleBuild>
181
183 Original author: Joel Berger, <joel.a.berger@gmail.com>
184 Current maintainer: Graham Ollis <plicease@cpan.org> and the
186 Alien::Base team
187
189 Copyright (C) 2012-2017 by Joel Berger
190 This library is free software; you can redistribute it and/or modify it
192 under the same terms as Perl itself.
193perl v5.28.1 2018-12A-l1i9en::Base::ModuleBuild::Authoring(3)