/ 
Module-Build-PDL-0.0.3
River stage zero No dependents
/ Module::Build::PDL

NAME

Module::Build::PDL - A Module::Build class for building PDL projects.

VERSION

This document describes Module::Build::PDL version 0.0.3.

SYNOPSIS

  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();

DESCRIPTION

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.

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:

$ ./Build forcepdlpp

See "CONFIGURATION AND ENVIRONMENT" below for more details on how to set up your distribution.

VERSION SKEW

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.

DIAGNOSTICS

None yet, but surely I need to add some.

CONFIGURATION AND ENVIRONMENT

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.

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:

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.

DEPENDENCIES

PDL, Module::Build

TODO

I have a number of things that I need to add to this module.

1. Typemaps

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.

2. External Dependencies

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.

3. Automatic M::B::PDL Dependence

This module needs to have a build-in dependence on itself, naturally.

4. Better documentation

Obviously.

5. Tests

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.)

BUGS, LIMITATIONS, AND SUPPORT

First see TODO above.

You have a number of avenues in which you can report bugs, submit ideas, or get help. These include:

Make an Annotation

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.

Help via Email

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/

Report a Bug or Feature Request

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.

AUTHOR

David Mertens, with help from Judd Taylor.

LICENCE AND COPYRIGHT

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.

DISCLAIMER OF WARRANTY

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.