Creating Packages

Discussion in 'Perl Misc' started by IanW, May 13, 2007.

  1. IanW

    IanW Guest

    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
     
    IanW, May 13, 2007
    #1
    1. Advertising

  2. IanW

    Xicheng Jia Guest

    On May 13, 6:34 pm, "IanW" <> wrote:
    > 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
     
    Xicheng Jia, May 14, 2007
    #2
    1. Advertising

  3. IanW

    Sisyphus Guest

    "IanW" <> wrote in message
    news:f283pr$s1g$...
    ..
    ..
    >
    > 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
     
    Sisyphus, May 14, 2007
    #3
  4. IanW

    IanW Guest

    "Sisyphus" <> wrote in message
    news:46487224$0$27448$...
    [..]
    > 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
     
    IanW, May 15, 2007
    #4
  5. IanW

    Sisyphus Guest

    "IanW" <> wrote in message
    news:f2aqf8$2ogh$...
    >

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

    >
    >> 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 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
     
    Sisyphus, May 15, 2007
    #5
  6. On Tue, 15 May 2007 00:13:32 +0100, "IanW" <>
    wrote:

    >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
    --
    {$_=pack'B8'x25,unpack'A8'x32,$a^=sub{pop^pop}->(map substr
    (($a||=join'',map--$|x$_,(unpack'w',unpack'u','G^<R<Y]*YB='
    ..'KYU;*EVH[.FHF2W+#"\Z*5TI/ER<Z`S(G.DZZ9OX0Z')=~/./g)x2,$_,
    256),7,249);s/[^\w,]/ /g;$ \=/^J/?$/:"\r";print,redo}#JAPH,
     
    Michele Dondi, May 15, 2007
    #6
  7. On Tue, 15 May 2007 10:24:16 +1000, "Sisyphus"
    <> wrote:

    >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
    --
    {$_=pack'B8'x25,unpack'A8'x32,$a^=sub{pop^pop}->(map substr
    (($a||=join'',map--$|x$_,(unpack'w',unpack'u','G^<R<Y]*YB='
    ..'KYU;*EVH[.FHF2W+#"\Z*5TI/ER<Z`S(G.DZZ9OX0Z')=~/./g)x2,$_,
    256),7,249);s/[^\w,]/ /g;$ \=/^J/?$/:"\r";print,redo}#JAPH,
     
    Michele Dondi, May 15, 2007
    #7
  8. On Tue, 15 May 2007 14:22:15 +0200, Christian Winter
    <> wrote:

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

    >
    >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
    --
    {$_=pack'B8'x25,unpack'A8'x32,$a^=sub{pop^pop}->(map substr
    (($a||=join'',map--$|x$_,(unpack'w',unpack'u','G^<R<Y]*YB='
    ..'KYU;*EVH[.FHF2W+#"\Z*5TI/ER<Z`S(G.DZZ9OX0Z')=~/./g)x2,$_,
    256),7,249);s/[^\w,]/ /g;$ \=/^J/?$/:"\r";print,redo}#JAPH,
     
    Michele Dondi, May 15, 2007
    #8
  9. IanW

    IanW Guest

    "Sisyphus" <> wrote in message
    news:4648fd9e$0$26514$...

    > 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, May 15, 2007
    #9
  10. IanW

    IanW Guest

    "Christian Winter" <> wrote in message
    news:4649a5f8$0$20283$-online.net...
    [..]
    > 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
     
    IanW, May 15, 2007
    #10
  11. IanW

    Sisyphus Guest

    "IanW" <> wrote in message
    news:f2dang$17it$...
    >

    ..
    > 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
     
    Sisyphus, May 16, 2007
    #11
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Paul  Smith
    Replies:
    0
    Views:
    759
    Paul Smith
    Nov 18, 2003
  2. thufir

    Creating and Using Packages

    thufir, Jan 17, 2005, in forum: Java
    Replies:
    12
    Views:
    696
    thufir
    Jan 25, 2005
  3. C Gillespie
    Replies:
    0
    Views:
    309
    C Gillespie
    May 24, 2005
  4. David Lyon
    Replies:
    19
    Views:
    611
    David Lyon
    Apr 24, 2009
  5. Ian
    Replies:
    3
    Views:
    191
Loading...

Share This Page