Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 96 lines (55 sloc) 4.673 kB
1521ba1 @jberger Began overview documentation.
jberger authored
1 =head1 NAME
2
3 Alien::Base::Authoring - Authoring an C<Alien::> module
4
5 =head1 DESCRIPTION
6
7 Congratulations! You have made the decision to help the Perl community by providing a C library via CPAN. The L<Alien> namespace has been instrumental in providing C libraries for many years, but authoring those modules has been a commitment that most authors weren't willing to take on. L<Alien::Base> tries to ease that pain by providing most of the needed functionality; usually authors should only need a little boilerplate and configuration!
8
9 =head1 ECOSYSTEM
10
131b5ba @jberger even a little more pod
jberger authored
11 The L<Alien::Base> ecosystem is made up of several elements. Some of these elements are the base classes in the distribution itself. Of course, no ecosystem is complete without inhabitants, therefore, it is also important to consider the users of these base classes. This documentation will assume that you are writing C<Alien::MyLibrary> which provides F<libmylibrary.so>. Further it will assume that you or someone else is going to use this module/library to write C<Some::Module::MyLibrary>. Finally an end user might use that module to write F<myscript.pl>.
1521ba1 @jberger Began overview documentation.
jberger authored
12
13 =head2 Alien::Base::ModuleBuild
14
66be499 @jberger a little pod
jberger authored
15 L<Alien::Base::ModuleBuild> provides a base class, utility methods and configuration handling for the build/install phase of the library. It is itself a subclass of L<Module::Build>, which is what supports the building and installing of the surrouning C<Alien::> module. C<Alien::MyLibrary>'s F<Build.PL> file will use L<Alien::Base::ModuleBuild> to create its builder object.
1521ba1 @jberger Began overview documentation.
jberger authored
16
17 # file: Alien-MyLibrary/Build.PL
18 use Alien::Base::ModuleBuild;
d3435ce @jberger Moved Repository class selection handling to A::B::MB, this allows fo…
jberger authored
19 my $builder = Alien::Base::ModuleBuild->new(...);
1521ba1 @jberger Began overview documentation.
jberger authored
20 $builder->create_build_script;
21
22 This is just like you would do for L<Module::Build>, except that there will be a few additional configuration parameters (see L<Alien::Base::ModuleBuild::API>).
23
24 L<Alien::Base::ModuleBuild> adds the additional build action C<alien>. This action need never be run directly, the usual C<build> action (usually seen as C<./Build>) will call it for you. The C<alien> action is responsible for finding, downloading, extracting and building the external libary. It also prepares it for installation with your C<Alien::> module.
25
26 =head2 Alien::Base
27
66be499 @jberger a little pod
jberger authored
28 L<Alien::Base> is the subclass of C<Alien::MyLibrary>. In this context, L<Alien::Base> has two distinct uses. First it is used by C<Alien::MyLibrary> to provide the build information/flags for building C<Some::Module::MyLibrary>. Secondly it is used (again through C<Alien::MyLibrary>) to allow run-time access to F<libmylibrary.so> to C<Some::Module::MyLibrary>.
1521ba1 @jberger Began overview documentation.
jberger authored
29
30 =head3 Alien::Base for Building
31
32 C<Alien::MyLibrary> is called by C<Some::Library::MyLibrary>'s build script, either F<Build.PL> or F<Makefile.PL>. Most of the functionality can be utilized through class method calls, though creating an object can save a few keystrokes.
33
34 # file: Some-Module-MyLibrary/Build.PL
35 use Module::Build;
36 use Alien::MyLibrary;
37
38 my $alien = Alien::MyLibrary->new;
39 my $builder = Module::Build->new({
40 ...
41 extra_compiler_flags => $alien->cflags(),
42 extra_linker_flags => $alien->libs(),
43 });
44 $builder->create_build_script;
45
46 Additional information can be gotten from the C<config> method.
47
48 =head3 Alien::Base for Run-Time Provision
49
decc0c6 @jberger further improvements to Authoring
jberger authored
50 C<Alien::MyLibrary> must be a subclass of C<Alien::Base>. This provides the C<import> method, which does the run-time provisioning so that when the XS file is loaded, it can find f<libmylibrary.so>. The C<import> method does this by appending to C<$ENV{LD_RUN_PATH}> or your system's equivalent environment variable (PLEASE file a bug if this should fail on your system).
51
52 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
53 package Alien::MyLibrary;
54
55 use parent 'Alien::Base';
56
57 1;
58
59 Finally, C<Alien::MyLibrary> must also be called by C<Some::Library::MyLibrary> before C<DynaLoader::bootstrap> or C<XSLoader::load>. The C<use> directive is recommended, however if you must use C<require> then be sure to call the C<import> method too. Without this C<import> call, the loader doesn't know where to find F<libmylibrary.so>.
1521ba1 @jberger Began overview documentation.
jberger authored
60
61 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
62 package Some::Module::MyLibrary;
63
64 use Alien::MyLibrary;
65
66 require XSLoader;
67 XSLoader::load();
7b2fc76 @jberger added some footer information
jberger authored
68
decc0c6 @jberger further improvements to Authoring
jberger authored
69 # your code
70
71 =head1 EXAMPLES
72
73 For more examples, see the F<examples> directory in the L<Alien::Base> distribution. Also the author intends to convert L<Alien::GSL> to use this system as soon as it is production ready, so see that distribution for a "Code in the Wild" example.
74
7b2fc76 @jberger added some footer information
jberger authored
75 =head1 AUTHOR
76
77 Joel Berger <joel.a.berger@gmail.com>
78
79 =head1 SEE ALSO
80
81 =over
82
decc0c6 @jberger further improvements to Authoring
jberger authored
83 =item *
84
85 L<Module::Build>
86
87 =item *
88
89 L<Alien>
90
91 =item *
7b2fc76 @jberger added some footer information
jberger authored
92
decc0c6 @jberger further improvements to Authoring
jberger authored
93 L<Alien::Base>
7b2fc76 @jberger added some footer information
jberger authored
94
95 =back
Something went wrong with that request. Please try again.