The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Module-MakeDist-1.02
/ Module::MakeDist

NAME

Module::MakeDist - Create Unix and ActiveState distros for a new module.

Synopsis

        use Module::MakeDist;

        # Work in /perl-modules/Module-MakeDist-1.00/.

        Module::MakeDist -> new
        (
                name            => 'Module::MakeDist',
                verbose         => 0,
                version         => '1.00',
                work_dir        => '/perl-modules',
        );

Description

Say we have a new module, KillerApp V 1.00, and in it's directory KillerApp-1.00/ are these files:

  • KillerApp.pm

  • Makefile.PL

  • Other files, such as test.pl, t/*.t, examples/*

Then this module processes the directory KillerApp-1.00/, and generates all files required to create shippable distributions (distros) in both Unix-style and ActiveState-style (ppm) formats.

Files created are:

  • MANIFEST

  • README

    We run pod2text on KillerApp.pm to create README.

  • KillerApp.html

    We run pod2html on KillerApp.pm to create KillerApp.html.

    The fancy *.html docs on my web site are output by fancy-pom2.pl, which is available elsewhere on my web site.

  • KillerApp-1.00.tgz

    The Unix-style distro.

    This can be uploaded to CPAN.

  • KillerApp.ppd

    This can be input to ppm.

  • x86/KillerApp-1.00.tar.gz

    This is a copy of KillerApp-1.00.tgz. The last time I tested it, ppm choked on a file called *.tgz.

  • KillerApp-1.00.zip

    The ActiveState ppm-style distro. This file contains KillerApp.ppd, README, KillerApp.html and x86/KillerApp-1.00.tar.gz.

We do not use any external programs such as tar, gzip or zip.

Distributions

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

Usage

As you can see from the program in the synopsis, which is the code I used to generate the distros for this very module, the class does all its work in the constructor. You do not call any other methods.

Options

Here, in alphabetical order, are the options accepted by the constructor, together with their default values.

  • name => ''

    Name must be set to the name of the module. Eg:

            name => 'Module::MakeDist'

    The '::' token is converted to '-', and combined with the version string, to construct the name of the directory in which the module's files are processed. This directory name is appended to the value of the work_dir option.

  • verbose => 0

    If verbose is set to some value > 0, print statements are activated which show the steps in the flow of control.

  • version => ''

    This is the version string, normally something like '1.00'.

  • work_dir => '.'

    This is the parent directory of the module directory.

Module::MakeDist does a chdir into "work_dir/name-version" in order to start work.

So, the example in the synopsis would mean this module attempts to work in '/perl-modules/Module-MakeDist-1.00/'.

We use File::Spec to join the directory names.

OS-specific Code

There are 2 places where the read-only bit on a file is reset.

The code uses $Config{'osname'} to look for a small selection of known OSes, and uses OS-specific commands for 'MSWin32' and 'linux' to do the reset.

Patches are welcome.

Files Shipped

See the source for subs called _what_to_gzip and _what_to_zip.

Such lists of files which 'ought to be shipped' can be extended indefinitely. Hopefully, no real argument will ensue.

However, if you do believe specific extra files should be included in the Unix-style distro, please let me know.

Slashes 'v' Backslashes

Perl is, and various Perl programs are, a bit of a mess when it comes to processing directory separators:

  • MANIFEST uses /

    A line from this module's MANIFEST file looks like:

            examples/make-MakeDist.pl

    Using a \ in this context means the file is omitted from the distro.

  • *.ppd uses \

    A line from this module's Module-MakeDist.ppd file looks like:

            <CODEBASE HREF="x86\Module-MakeDist-1.00.tar.gz" />

    Using a / in this context actually works.

    Not only that, but to run ppm under MS Windows and install a module from a Linux box, the CODEBASE must use /.

Credits

I gained important information from these sources:

idnopheq

http://www.perlmonks.org/index.pl?node_id=113448

Jenda Krynicky

http://jenda.krynicky.cz/perl/PPM.html

Author

Module::MakeDist was written by Ron Savage <ron@savage.net.au> in 2002.

Home page: http://savage.net.au/index.html

Copyright

Australian copyright (c) 2002, Ron Savage. All rights reserved.

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Artistic License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html