Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 134 lines (75 sloc) 6.089 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
28a66d4 @jberger Added documentation before 0.000_001 release
jberger authored
9 =head1 STATUS
10
11 L<Alien::Base> is under heavy development and is currently pre-alpha. The author hopes that the API will stabilize soon, but currently there are no promises that ANY PART of the API will remain as-is. Please resist the temptation to use it for production code until the warning is removed. Of course you are welcomed, and in fact encouraged, to test it with for your favorite library; if you do, you are more than welcome to share your experience with me.
12
1521ba1 @jberger Began overview documentation.
jberger authored
13 =head1 ECOSYSTEM
14
131b5ba @jberger even a little more pod
jberger authored
15 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
16
17 =head2 Alien::Base::ModuleBuild
18
66be499 @jberger a little pod
jberger authored
19 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
20
21 # file: Alien-MyLibrary/Build.PL
22 use Alien::Base::ModuleBuild;
d3435ce @jberger Moved Repository class selection handling to A::B::MB, this allows fo…
jberger authored
23 my $builder = Alien::Base::ModuleBuild->new(...);
1521ba1 @jberger Began overview documentation.
jberger authored
24 $builder->create_build_script;
25
26 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>).
27
28 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.
29
30 =head2 Alien::Base
31
69c763e @jberger some pod fixes
jberger authored
32 L<Alien::Base> is the base class 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 provide run-time access to F<libmylibrary.so> to C<Some::Module::MyLibrary>.
1521ba1 @jberger Began overview documentation.
jberger authored
33
34 =head3 Alien::Base for Building
35
36 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.
37
38 # file: Some-Module-MyLibrary/Build.PL
39 use Module::Build;
40 use Alien::MyLibrary;
41
42 my $alien = Alien::MyLibrary->new;
63dfd64 @run4flat Fixed subtle but important typo in Authoring.pod
run4flat authored
43 my $builder = Module::Build->new(
1521ba1 @jberger Began overview documentation.
jberger authored
44 ...
45 extra_compiler_flags => $alien->cflags(),
46 extra_linker_flags => $alien->libs(),
63dfd64 @run4flat Fixed subtle but important typo in Authoring.pod
run4flat authored
47 );
1521ba1 @jberger Began overview documentation.
jberger authored
48 $builder->create_build_script;
49
50 Additional information can be gotten from the C<config> method.
51
52 =head3 Alien::Base for Run-Time Provision
53
d5f1bab @jberger Added builder.t which so far tests the temporary directories, it also…
jberger authored
54 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).
decc0c6 @jberger further improvements to Authoring
jberger authored
55
56 # file: Alien-MyLibrary/lib/Alien/MyLibrary.pm
57 package Alien::MyLibrary;
58
59 use parent 'Alien::Base';
60
61 1;
62
63 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
64
65 # file: Some-Module-MyLibrary/lib/Some/Module/MyLibrary.pm
66 package Some::Module::MyLibrary;
67
68 use Alien::MyLibrary;
c65d63d @run4flat Fixed XSLoader example code
run4flat authored
69 our $VERSION = '0.54';
1521ba1 @jberger Began overview documentation.
jberger authored
70
71 require XSLoader;
c65d63d @run4flat Fixed XSLoader example code
run4flat authored
72 XSLoader::load('Some::Module::MyLibrary', $VERSION);
7b2fc76 @jberger added some footer information
jberger authored
73
decc0c6 @jberger further improvements to Authoring
jberger authored
74 # your code
75
76 =head1 EXAMPLES
77
fb698e7 @jberger oddly Ford::Prefect.xs was missing #include "libdontpanic.h" but stil…
jberger authored
78 For more examples, see the F<examples> directory in the L<Alien::Base> distribution. Two of the example distributions are used in the test suite (see F<t/zz-examples.t>). Those are:
79
80 =over
81
82 =item *
83
84 C<Alien::DontPanic> -- An example C<Alien::> module which provides F<libdontpanic.so>. It provides the C function C<answer> which is simply:
85
86 int answer () { return 42 }
87
88 =item *
89
90 C<Ford::Prefect> -- An XS module which provides the Perl-level access to C<answer>. It relies on F<libdontpanic.so> and uses C<Alien::DontPanic> to locate/load it.
91
92 =back
93
94 Also the author intends to convert L<Alien::GSL> to use this system as soon as it is production ready, so that C<Alien::> authors can see a "Code in the Wild" example. Until then, a pre-release version of this module is provided in the F<examples> directory as well.
decc0c6 @jberger further improvements to Authoring
jberger authored
95
7b2fc76 @jberger added some footer information
jberger authored
96 =head1 AUTHOR
97
98 Joel Berger <joel.a.berger@gmail.com>
99
100 =head1 SEE ALSO
101
102 =over
103
decc0c6 @jberger further improvements to Authoring
jberger authored
104 =item *
105
106 L<Module::Build>
107
108 =item *
109
110 L<Alien>
111
112 =item *
7b2fc76 @jberger added some footer information
jberger authored
113
decc0c6 @jberger further improvements to Authoring
jberger authored
114 L<Alien::Base>
7b2fc76 @jberger added some footer information
jberger authored
115
116 =back
f77671a @jberger a little more pod polishing
jberger authored
117
118 =head1 SOURCE REPOSITORY
119
120 L<http://github.com/jberger/Alien-Base>
121
122 =head1 AUTHOR
123
124 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
125
126 =head1 COPYRIGHT AND LICENSE
127
128 Copyright (C) 2012 by Joel Berger
129
130 This library is free software; you can redistribute it and/or modify
131 it under the same terms as Perl itself.
132
133 =cut
Something went wrong with that request. Please try again.