Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 75 lines (44 sloc) 3.872 kb
1521ba12 »
2012-03-06 Began overview documentation.
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
11 The L<Alien::Base> ecosystem is made up of several elements. Of course, no ecosystem is complete without inhabitants. It is also important to consider the users of the 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>.
12
13 =head2 Alien::Base::ModuleBuild
14
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>. C<Alien::MyLibrary>'s F<Build.PL> file will use L<Alien::Base::ModuleBuild> to create its builder object.
16
17 # file: Alien-MyLibrary/Build.PL
18 use Alien::Base::ModuleBuild;
19 my $builder = Alien::Base::ModuleBuild->new({...});
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
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 use (again through C<Alien::MyLibrary>) to allow run-time access to F<libmylibrary.so> to C<Some::Module::MyLibrary>.
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
78fb75a3 »
2012-03-06 a couple little fixes to pod
50 C<Alien::MyLibrary> must also be called by C<Some::Library::MyLibrary> before C<DynaLoader::bootstrap> or C<XSLoader::load>. This does the run-time provisioning so that when the XS file is loaded, it can find f<libmylibrary.so>. It 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).
1521ba12 »
2012-03-06 Began overview documentation.
51
52 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
53 package Some::Module::MyLibrary;
54
55 use Alien::MyLibrary;
56
57 require XSLoader;
58 XSLoader::load();
59
60 The C<use> directive is recommended, however if you must use C<require> then be sure to call the C<import> method too.
7b2fc768 »
2012-03-06 added some footer information
61
62 =head1 AUTHOR
63
64 Joel Berger <joel.a.berger@gmail.com>
65
66 =head1 SEE ALSO
67
68 =over
69
70 =item L<Module::Build>
71
72 =item L<Alien>
73
74 =back
Something went wrong with that request. Please try again.