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

DESCRIPTION

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
19       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

STATUS

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

ECOSYSTEM

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
43   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
51        # file: Alien-MyLibrary/Build.PL
52        use Alien::Base::ModuleBuild;
53        my $builder = Alien::Base::ModuleBuild->new(...);
54        $builder->create_build_script;
55
56       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
60       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
69       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
74   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
82       Alien::Base for Building
83
84       "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
89        # file: Some-Module-MyLibrary/Build.PL
90        use Module::Build;
91        use Alien::MyLibrary;
92
93        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
101       Additional information can be gotten from the "config" method.
102
103       Alien::Base for Run-Time Provision
104
105       "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
112        # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
113        package Alien::MyLibrary;
114
115        use parent 'Alien::Base';
116
117        1;
118
119       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
126        # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
127        package Some::Module::MyLibrary;
128
129        use Alien::MyLibrary;
130        our $VERSION = '0.54';
131
132        require XSLoader;
133        XSLoader::load('Some::Module::MyLibrary', $VERSION);
134
135        # your code
136

EXAMPLES

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
141       ·   Acme::Alien::DontPanic -- An example "Alien::" module which
142           provides libdontpanic.so. It provides the C function "answer" which
143           is simply:
144
145            int answer () { return 42 }
146
147       ·   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
151       Additionally, there exist in-production "Alien::" distributions that
152       serve as de-facto tests of Alien::Base's networking components:
153
154       ·   Alien::LibYAML -- Builds and installs libyaml, acquiring the
155           library archive from its hosted location via
156           "Alien::Base::Repository::HTTP".
157
158       ·   Alien::GSL -- Builds and installs libgsl, aquiring the library
159           source archive via "Alien::Base::Repository::FTP".
160
161       ·   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

AUTHOR

168       Joel Berger <joel.a.berger@gmail.com>
169

SEE ALSO

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

SOURCE REPOSITORY

180       <http://github.com/Perl5-Alien/Alien-Base-ModuleBuild>
181

AUTHOR

183       Original author: Joel Berger, <joel.a.berger@gmail.com>
184
185       Current maintainer: Graham Ollis <plicease@cpan.org> and the
186       Alien::Base team
187
189       Copyright (C) 2012-2017 by Joel Berger
190
191       This library is free software; you can redistribute it and/or modify it
192       under the same terms as Perl itself.
193
194
195
196perl v5.28.1                      2018-12A-l1i9en::Base::ModuleBuild::Authoring(3)
Impressum