Module::Build::PDL - A Module::Build class for building PDL projects.
This document describes Module::Build::PDL version 0.0.3.
use strict; use warnings; use Module::Build::PDL; my $builder = Module::Build::PDL->new( dist_name => 'PDL-My-Mod', license => 'perl', dist_author => 'Your Name <yourname@example.com>', dist_version_from => 'lib/PDL/My/Mod.pd', requires => { 'Test::More' => 0, 'PDL' => 0, }, add_to_cleanup => [ 'PDL-My-Mod-*' ], ); $builder->create_build_script();
Module::Build::PDL is to PDL distributions what Module::Build is to most perl distributions. The only difference between the two (at the moment) is that Module::Build::PDL knows how to handle .pd files (files that use PDL::PP to generate compiled PDL functions).
Although I should probably give a basic tutorial here at some point, for now I will simply tell you to refer to Module::Build for an explanation of how to use Build files and Module::Build::Authoring for an explanation of how to use the module itself in your own distributions.
Build
Note that Module::Build::PDL includes an additional action: forcepdlpp. This will force your .pd files to be rebuilt, which is handy if they have an external dependency that has changed. To use this, simpy issue the following command:
Module::Build::PDL
forcepdlpp
$ ./Build forcepdlpp
See "CONFIGURATION AND ENVIRONMENT" below for more details on how to set up your distribution.
I found out the hard way that if you are working on a module and you update the version, you must rerun Build.PL. Experienced programmers probably already knew that, but I didn't and I hope this note will help any new module maintainers as they update their work.
Build.PL
None yet, but surely I need to add some.
To create a M::B::PDL build, you should probably begin with something like Module::Starter. Then edit the Build.PL file so that it uses Module::Build::PDL instead of Module::Build.
Module::Build
The use (by Module::Build) of the lib directory is important. Here is a brief explanation if you are not familiar with how this works. Suppose you want to install a pure-perl module called My::Foo::Bar. You would put the file Bar.pm in the directory lib/My/Foo. Anything you put in lib/ will be processed, so you don't need to tell the builder anything about where to look for your files. This means that if you wanted to distribute multiple modules My::Foo, My::Foo::Base, My::Foo::Bar, and PDL::My::Foo, your directory structure should look something like this:
lib/My/Foo
lib/
My::Foo
My::Foo::Base
My::Foo::Bar
PDL::My::Foo
Build.PL Changes ignore.txt MANIFEST README lib/ My/ Foo.pm Foo/ Base.pm Bar.pm PDL/ My/ Foo.pm
In other words, put the files in lib where you would expect to find them once everything is compiled and installed.
So far, I've only described what Module::Build does. The only new capability provided by Module::Build::PDL (so far) is that if you have a .pd file in your lib/ directory, Module::Build::PDL will properly process it for you.
PDL, Module::Build
I have a number of things that I need to add to this module.
Right now, you must manually include the typemap.pdl file in you lib directory. This could easily be automatically copied over during the object creation process, but I've not yet implemented it.
I need to add some sort of systematized method for checking for external dependencies. This will require some thought and planning. At the moment, I think that we should put a separate directory in the distribution's root directory called ext_dep or some such thing. Any module that depends on an external dependency - and which should not be compiled if that external dependency is not found - should have an identically named test file in ext_dep. For example, to create PDL::My::Foo, you would have the files lib/PDL/My/Foo.pd and ext_dep/PDL/My/Foo.pm. The ext_dep file would be 'used' and its return value would determine if the external dependency could be found. This would also need to have a natural extension for subdirectories, where GSL is a good example.
ext_dep
lib/PDL/My/Foo.pd
ext_dep/PDL/My/Foo.pm
GSL
This module needs to have a build-in dependence on itself, naturally.
Obviously.
I'm not even quite sure how to write tests for this, but they really should be done. (TODO: check the output of various logs.)
First see TODO above.
You have a number of avenues in which you can report bugs, submit ideas, or get help. These include:
If you have any module documentation recommendations or suggestions, you should note them on AnnoCPAN. I intend to check the annotations on a regular basis and incorporate them into my documentation on a regular basis. This module's annotations are located at http://annocpan.org/dist/Module-Build-PDL.
Although this is a free-standing module, it will (hopefully soon) be moved into PDL. As such, you can probably get help from the PDL mailing list, which is explained here: http://pdl.perl.org/maillists/
You can send bugs and feature requests to bug-module-build-pdl@rt.cpan.org, or submit them through the web interface at http://rt.cpan.org.
bug-module-build-pdl@rt.cpan.org
David Mertens, with help from Judd Taylor.
Copyright (c) 2010, David Mertens. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Module::Build::PDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Build::PDL
CPAN shell
perl -MCPAN -e shell install Module::Build::PDL
For more information on module installation, please visit the detailed CPAN module installation guide.