Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update documentation

  • Loading branch information...
commit 76a50f6fbe0bbed5fff0ca9cad701477299204df 1 parent e26b73c
@jberger jberger authored
View
5 Changes
@@ -1,5 +1,10 @@
Revision history for Perl module Alien::Base.
+0.001 Oct 9, 2012
+ - First Beta release!
+ - Documentation updated
+ - Better autogeneration of pkgconfig information (run4flat++)
+
0.000_022 Oct 8, 2012
- Major refactoring
- separate alien_{x}_commands where x = build, test, install
View
12 lib/Alien/Base/Authoring.pod
@@ -8,7 +8,7 @@ Congratulations! You have made the decision to help the Perl community by provid
=head1 STATUS
-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.
+L<Alien::Base> is under active development and is currently beta release. The author hopes that the API has stabilized, but will not promise that it has. 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.
=head1 ECOSYSTEM
@@ -25,7 +25,9 @@ L<Alien::Base::ModuleBuild> provides a base class, utility methods and configura
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>).
-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.
+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 (the commands specified in builder parameter C<alien_build_commands>).
+
+The C<./Build test> command will invoke any library tests specified in C<alien_test_commands>, though none are defined by default. Finally C<./Build install> will invoke whatever C<alien_install_commands> were specified.
=head2 Alien::Base
@@ -75,19 +77,19 @@ Finally, C<Alien::MyLibrary> must also be called by C<Some::Library::MyLibrary>
=head1 EXAMPLES
-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:
+The example code that was housed in this distribution during alpha phase has been moved to two different CPAN distributions. Those are:
=over
=item *
-C<Alien::DontPanic> -- An example C<Alien::> module which provides F<libdontpanic.so>. It provides the C function C<answer> which is simply:
+L<Acme::Alien::DontPanic> -- An example C<Alien::> module which provides F<libdontpanic.so>. It provides the C function C<answer> which is simply:
int answer () { return 42 }
=item *
-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.
+L<Acme::Ford::Prefect> -- An XS module which provides the Perl-level access to C<answer>. It relies on F<libdontpanic.so> and uses L<Acme::Alien::DontPanic> to locate/load it.
=back
View
22 lib/Alien/Base/ModuleBuild/API.pod
@@ -25,13 +25,13 @@ The name of the primary library which will be provided. This should be in the fo
[version 0.001]
-The name of the temporary folder which will house the library when it is downloaded and built. This folder will always be removed by the C<clean> action. The default name is C<_alien>.
+The name of the temporary folder which will house the library when it is downloaded and built. The default name is C<_alien>.
=item alien_share_dir
[version 0.001]
-The name of the folder which will both serve as the "install" directory (i.e. <--prefix>) for C<make install> as well as a share directory via L<Module::Build>'s C<share_dir>/C<dist_dir> parameter. This directory is added in a smart manner which attempts not to interfere with other author-defined C<share_dir>s. The default name is C<_share>.
+The name of the folder which will both serve a stub share directory via L<Module::Build>'s C<share_dir>/C<dist_dir> parameter. This directory is added in a smart manner which attempts not to interfere with other author-defined C<share_dir>s. The default name is C<_share>. This folder will hold a README file which is then installed to the target installed share location. It is THAT location that the library will be installed to.
=item alien_selection_method
@@ -43,7 +43,13 @@ This is intended to choose the mechanism for selecting one file from many. The d
[version 0.001]
-An arrayref of commands used to build the library and install it to the directory specified in C<alien_share_dir>. Each command is first passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">, so those variables may be used. The default is tailored to the Gnu toolchain, i.e. AutoConf and Make; it is C<[ '%pconfigure --prefix=%s', 'make', 'make install' ]>.
+An arrayref of commands used to build the library in the directory specified in C<alien_temp_dir>. Each command is first passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">, so those variables may be used. The default is tailored to the Gnu toolchain, i.e. AutoConf and Make; it is C<[ '%pconfigure --prefix=%s', 'make' ]>.
+
+=item alien_install_commands
+
+[version 0.001]
+
+An arrayref of commands used to install it to the share directory specified by interpolation var C<%s>. Each command is first passed through the L<command interpolation engine|/"COMMAND INTERPOLATION">, so those variables may be used. The default is tailored to the Gnu toolchain, i.e. AutoConf and Make; it is C<[ 'make install' ]>.
=item alien_version_check
@@ -124,7 +130,7 @@ A few global variables are used to set gross behavior. For each pair of variable
=item $ENV{ALIEN_VERBOSE}
-Setting the either to a true value will output a little more info from within the module itself, plus is will not suppress the messages from the library-build phase (i.e. make etc.).
+Setting the either to a true value will output a little more info from within the module itself. At this point L<Alien::Base> is going to be fairly verbose without this enabled.
=item $Alien::Base::ModuleBuild::Force
@@ -142,13 +148,13 @@ Config keys of interest are:
=over
-=item build_share_dir
+=item working_directory
-Holder for the full path to the shared directory specified in C<alien_share_dir> builder object parameter. This is used to munge the pkg-config data later on.
+Holder for the full path to the extracted source of the library. This is used to munge the pkg-config data later on.
=item pkgconfig
-A hashref of Alien::Base::PkgConfig objects created from F<.pc> files found in C<build_share_dir>. One extra object (whose key is C<_manual> is created from the C<alien_provides_*> information.
+A hashref of Alien::Base::PkgConfig objects created from F<.pc> files found in C<working_directory>. One extra object (whose key is C<_manual> is created from the C<alien_provides_*> information.
=item install_type
@@ -172,7 +178,7 @@ Before L<Alien::Base::ModuleBuild> executes system commands, it replaces a few s
=item %s
-The full path to the share directory (C<alien_share_dir>). This is where the library should install itself; for autoconf style installs this will look like
+The full path to the final installed location of the share directory (builder method C<alien_library_destination>). This is where the library should install itself; for autoconf style installs this will look like
--prefix=%s
Please sign in to comment.
Something went wrong with that request. Please try again.