Creating Packages

[IanW]

Hi

I've created a Perl script to generate "3D" bar graphs using GD. As it is,
it's easy enough to use via the normal "require" method and so have made it
available from my website to that end:

http://www.creationfactor.net/software.htm

However, I'd quite like to stick it up on CPAN so it's available to download
and install as a module. So, I found a "toot" tutorial somewhere and several
hours and a big headache later decided to go and study a pint of beer
instead! I got lost somewhere in the region of.. well - all of it actually -
passing objects around, scoping in general and things like the exporter.

Would someone like to take a quick look at the script and tell me how
difficult it would be to convert into a module, given the way I've written
it? Would it require a huge amount of changing?

Thanks
Ian

 

[Xicheng Jia]

Hi

I've created a Perl script to generate "3D" bar graphs using GD. As it is,
it's easy enough to use via the normal "require" method and so have made it
available from my website to that end:

http://www.creationfactor.net/software.htm

However, I'd quite like to stick it up on CPAN so it's available to download
and install as a module. So, I found a "toot" tutorial somewhere and several
hours and a big headache later decided to go and study a pint of beer
instead! I got lost somewhere in the region of.. well - all of it actually -
passing objects around, scoping in general and things like the exporter.

Would someone like to take a quick look at the script and tell me how
difficult it would be to convert into a module, given the way I've written
it? Would it require a huge amount of changing?

Not sure if I understood you correctly? you want to change a general-
purpose perl file into a Perl module? If so, you probably want to
check 'h2xs'.

man h2xs

it will help you do most of the necessary modular interfaces, you just
need to insert your subroutines into proper (file|locations), and then
make your own documentation. If you want an OO module, then no need to
use Exporter.

Be careful to name your methods if you want 'Exporter'ed things and
make sure no conflicts about the namespaces with your main code.

Regards,
Xicheng

 

[Sisyphus]

..
..

Would someone like to take a quick look at the script and tell me how
difficult it would be to convert into a module, given the way I've written
it? Would it require a huge amount of changing?

Not much changing at all. At the minimum (assuming you want the module to be
named GD::3DBarGrapher) all you need to do is place (at the beginning of the
file) the line:

package GD::3DBarGrapher;

Then if the file was saved as 3DBarGrapher.pm and placed in the GD folder
under one of the @INC directories, it could be accessed by:

use GD::3DBarGrapher;

But the functions contained in the 3DBarGrapher.pm would have to be accessed
by their "fully qualified" name - ie it would not be possible to call the
"creategraph" function by that name. It would have to be called as
GD::3DBarGrapher::creategraph().

Alternatively if you were to also put (near the top of 3DBarGrapher.pm) the
lines:

require Exporter;
@GD::3DBarGrapher::ISA = qw(Exporter);
@GD::3DBarGrapher::EXPORT_OK = qw(creategraph);

The module could then be loaded as:

use GD::3DBarGrapher qw(creategraph);

and the function creategraph() could be used - there would be no need for
the "fully qualified" name. (See 'perldoc Exporter' for full
details/options.)

You don't really need Exporter at all - it's just a convenience that's
usually provided, so that users can call (for example) the creategraph
function as 'creategraph()' instead of having to write
'GD::3DBarGrapher::creategraph()'

And you'll want to designate a version number:

$GD::3DBarGrapher::VERSION = '0.01'; # or whatever number you want

To create a proper CPAN distro, you'll also need a Makefile.PL, a CHANGES
file , a README file , and a test suite (or at least a test.pl) to ensure
that things are working as expected.

Cheers,
Rob

 

[IanW]

[..]

require Exporter;
@GD::3DBarGrapher::ISA = qw(Exporter);
@GD::3DBarGrapher::EXPORT_OK = qw(creategraph);

The module could then be loaded as:

use GD::3DBarGrapher qw(creategraph);

and the function creategraph() could be used - there would be no need for
the "fully qualified" name. (See 'perldoc Exporter' for full
details/options.)

You don't really need Exporter at all - it's just a convenience that's
usually provided, so that users can call (for example) the creategraph
function as 'creategraph()' instead of having to write
'GD::3DBarGrapher::creategraph()'

That's excellent thanks - I think I was getting bogged down thinking I
needed to call a "new" instance of the module and then set the config
options via object handles etc, but I can see I don't need all that.

I set up 3DBarGrapher.pm as you suggested, including the exporter and a
test.pl file, and it works nicely

And you'll want to designate a version number:

$GD::3DBarGrapher::VERSION = '0.01'; # or whatever number you want

Is there any general guide on version numbers? That is, I don't at present
have a to-do list for enhancements to it, so would be inclined to call it
version 1.0. However, I notice alot of modules seem to be 0.xx.

To create a proper CPAN distro, you'll also need a Makefile.PL, a CHANGES
file , a README file , and a test suite (or at least a test.pl) to ensure
that things are working as expected.

I found this page: http://cpan.uwinnipeg.ca/htdocs/perl/perlnewmod.html and
so have requested a Pause account. It mentions using things like
make-starter or hx2s. I tried the latter but it puts alot of complicated
stuff into the .pm template and creates some other similarly mysterious
files. I will try make-starter when I get my Pause account & cpan email. But
if I just created the files you mention manually, then presumably I would
just pack them into a tarball and upload?

Regards
Ian

 

[Sisyphus]

..
..

Is there any general guide on version numbers? That is, I don't at present
have a to-do list for enhancements to it, so would be inclined to call it
version 1.0. However, I notice alot of modules seem to be 0.xx.

I think there was once a convention that while you considered your module to
be "alpha" you would designate 0.xx versions. If that convention still
exists, I think it is fairly widely ignored.

I wouldn't worry about it too much - I've not yet seen an author criticised
for the choice of version number.

I forgot to mention the MANIFEST file.

I found this page: http://cpan.uwinnipeg.ca/htdocs/perl/perlnewmod.html
and so have requested a Pause account. It mentions using things like
make-starter or hx2s. I tried the latter but it puts alot of complicated
stuff into the .pm template and creates some other similarly mysterious
files. I will try make-starter when I get my Pause account & cpan email.
But if I just created the files you mention manually, then presumably I
would just pack them into a tarball and upload?

I've only ever created the files manually. There is quite possibly some work
to be saved if one goes to the trouble of becoming familiar with one of the
automated procedures. I've never bothered doing that.

I just manually create the files in the appropriate directory structure,
tar, gzip, and "Upload a file to CPAN" from the pause menu (
https://pause.perl.org/pause/authenquery ).

Best to first take a look at http://www.cpan.org/modules/04pause.html .

Cheers,
Rob

 

[Michele Dondi]

I found this page: http://cpan.uwinnipeg.ca/htdocs/perl/perlnewmod.html and
so have requested a Pause account. It mentions using things like

Also see

http://perlmonks.org/?node_id=592240


Michele

 

[Michele Dondi]

I wouldn't worry about it too much - I've not yet seen an author criticised
for the choice of version number.

I have seen someone complaining for a 6 in
<http://perlmonks.org/?node_id=614624>.
;-)


Michele

 

[Michele Dondi]

The turials there aren't the newest and don't mention some
newer developments. For anyone starting with Perl module development,

Are you a user there too? You may consider writing a tutorial or a
mini-tutorial yourself, with updated information. Unfortunately I
don't have the expertise to do so. Worse luck those documents are not
wiki-like...


Michele

 

[IanW]

I've only ever created the files manually. There is quite possibly some
work to be saved if one goes to the trouble of becoming familiar with one
of the automated procedures. I've never bothered doing that.

I just manually create the files in the appropriate directory structure,
tar, gzip, and "Upload a file to CPAN" from the pause menu (
https://pause.perl.org/pause/authenquery ).

Best to first take a look at http://www.cpan.org/modules/04pause.html .

Thanks Rob. I've just been having a look at some of the recent (small)
packages uploaded to see what they include. It does look like most people
run at least ExtUtils::MakeMaker because there's a file META.yml that is
apparently generated automatically by it.

Regards
Ian

 

[IanW]

[..]

numbers used should be version objects and make use of "long"
version numbers, i.e. xxx.yyy.zzz or xxx.yyyzzz notation.

As to the question of version numbering schemes (just what I think
is a practicable approach):

- Usually, if it has a leading zero it's considered not hundred
percent error-proof. If you're sure the module has been reasonably
tested and is unlikely to carry errors, it should be > 0.

- The second part is best increased when new features are implemented
or compatibility with other modules or Perl versions can't be assured
anymore. If a second level increment occurs, one best checks the
CHANGES document before installing it.

- Third level numbers are then left to indicate fixes or simple feature
enhancements which should be installable without having to change
the environment or the code that uses the module.

A few of the more recent packages seem to be using the new numbering scheme
(http://search.cpan.org/recent). I am starting to think maybe I ought to
number my package 0.9.0, as while I *think* it's bug free, I haven't tested
it on any other machine and haven't tried particularly hard to break it.

Regards
Ian

 

[Sisyphus]

..
It does look like most people run at least ExtUtils::MakeMaker because
there's a file META.yml that is apparently generated automatically by it.

If I understand the MakeMaker docs correctly, the META.yml gets
automatically created (and automatically added to the MANIFEST) when you run
'make distdir' or 'make dist'. (I've never bothered with it, though clearly
it has merit in the opinions of some.) See the "Distribution Support"
section of 'perldoc ExtUtils::MakeMaker' for that and other make targets
that you might like to use.

Cheers,
Rob