Configuration

Perl setup

"Module::Release" looks at "Config" to get the values it needs for certain operations.

make

The name of the program to run for the "make" steps

Environment variables

PERL

Use this value as the perl interpreter, otherwise use the value in $^X.

RELEASE_DEBUG

Do you want debugging output? Set this to a true value

CPAN_PASS

Your CPAN password. If you don't set this and you want to upload to PAUSE, you should be prompted for it.

".releaserc"

"Module::Release" looks for either ".releaserc" or "releaserc" in the current working directory. It reads that with "ConfigReader::Simple" to get these values:

cpan_user

Your PAUSE user id.

cpan_pass

Your PAUSE password, but don't use this. Put it in the environment variable.

http_proxy

https_proxy

ignore_prereqs

A whitespace separated list of modules for "Test::Prereq" to ignore. But, don't use "Test::Prereq". It was not a good idea.

makefile_PL

The name of the file to run as Makefile.PL. The default is "Makefile.PL", but you can set it to "Build.PL" to use a "Module::Build"-based system.

If this is set to "Build.PL", this his will also cause "Module::Build::Prereqs" to use "Test::Prereqs::Build" instead of "Test::Prereqs".

makefile

The name of the file created by "makefile_PL" above. The default is "Makefile", but you can set it to "Build" for "Module::Build"-based systems.

module_name

"release" tries to guess the module name from the distro name, but if you don't like that, set the module name in the config file.

Methods

new()

Create the "Module::Release" object. It reads the configuration and initializes everything.

init()

Set up the "Module::Release" object. By default, it expects something using MakeMaker, but if it sees a Build.PL it configures itself for "Module::Build".

The values in the configuration file override any settings here, so if you have both a Makefile.PL and a Build.PL then you can override the "Module::Build" preference by setting the "makefile_PL" and "make" configuration values.

load_mixin( MODULE )

EXPERIMENTAL!!

Load MODULE through require (so no importing), without caring what it does. My intent is that MODULE adds methods to the "Module::Release" namespace so a release object can see it. This should probably be some sort of delegation.

Added in 1.21

loaded_mixins

Returns a list of the loaded mixins

Added in 1.21

mixin_loaded( MODULE )

Returns true if the mixin class is loaded

Methods for configuration and settings

config

Get the configuration object. By default this is a "ConfigReader::Simple" object;

local_file( FILENAME )

Returns or sets the name of the local distribution file. You can use the literal argument "undef" to clear the value.

remote_file

Returns the name of the file on the remote side. You can use the literal argument "undef" to clear the value.

Methods for multiple perl testing

set_perl

Set the current path for the perl binary that "Module::Release" should use for general tasks. This is not related to the list of perls used to test multiple binaries unless you use one of those binaries to set a new value.

If PATH looks like a perl binary, "set_perl" uses it as the new setting for perl and returns the previous value.

Added in 1.21.

get_perl

Returns the current path for the perl binary that "Module::Release" should use for general tasks. This is not related to the list of perls used to test multiple binaries.

Added in 1.21.

perls()

Return the list of perl binaries Module::Release will use to test the distribution.

Added in 1.21.

add_a_perl( PATH )

Add a perl binary to the list of perls to use for testing. If PATH is not executable or cannot run "print $]", this method returns nothing and does not add PATH. Otherwise, it returns true. If the same path was already in the list, it returns true but does not create a duplicate.

Added in 1.21.

remove_a_perl( PATH )

Delete PATH from the list of perls used for testing

Added in 1.21.

reset_perls

Reset the list of perl interpreters to just the one running "release".

Added in 1.21.

input_fh

Return the value of input_fh.

output_fh

If quiet is off, return the value of output_fh. If output_fh is not set, return STDOUT. If quiet is on, return the value of null_fh.

null_fh

Return the null filehandle. So far that's something set up in "new" and I haven't provided a way to set it. Any subclass can make their "null_fh" return whatever they like.

quiet

Get the value of quiet mode (true or false).

turn_quiet_on

Turn on quiet mode

turn_quiet_off

Turn off quiet mode

debug

Get the value of the debugging flag (true or false).

turn_debug_on

Turn on debugging

turn_debug_off

Turn off debugging

debug_fh

If debugging is on, return the value of debug_fh. If debug_fh is not set, return STDERR. If debugging is off, return the value of null_fh.

Methods for building

clean

Run `make realclean`

distclean

Run `make distclean`

build_makefile()

Runs `perl Makefile.PL 2>&1`.

This step ensures that we start off fresh and pick up any changes in "Makefile.PL".

make()

Run a plain old `make`.

test()

Run `make test`. If any tests fail, it dies.

dist()

Run `make dist`. As a side effect determines the distribution name if not set on the command line.

disttest

Run `make disttest`. If the tests fail, it dies.

dist_test

This was the old name for the method, but was inconsistent with other method names. It still works, but is deprecated and will give a warning.

dist_version

Return the distribution version ( set in dist() )

dist_version_format

Return the distribution version ( set in dist() )

# XXX make this configurable

module_name

Returns the module name. This either takes it from the config file or tries to guess it from the distro name.

check_manifest

Run `make manifest` and report anything it finds. If it gives output, die. You should check "MANIFEST" to ensure it has the things it needs. If files that shouldn't show up do, put them in MANIFEST.SKIP.

Since `make manifest` takes care of things for you, you might just have to re-run your release script.

manifest_name

Return the name of the manifest file, probably MANIFEST.

manifest

This is the old name for manifest_name. It still works but is deprecated.

files_in_manifest

Return the filenames in the manifest file as a list.

check_vcs

vcs_tag

make_vcs_tag

Note: these methods were formerly "cvs", but are now "vcs" for Version Control System.

This is a placeholder method which should be implemented in a mixin module. Try installing Module::Release::CVS, Module::Release::SVN, or Module::Release::Git and then loading them in your script. The default "release" script does this for you by checking for the special directories for those source systems.

Previous to version 1.24, these methods were implemented in this module to support CVS. They are now in Module::Release::CVS as a separate module.

touch( FILES )

Set the modification times of each file in FILES to the current time. It tries to open the file for writing and immediately closing it, as well as using utime. It checks that the access and modification times were updated.

Returns the number of files which it successfully touched.

touch_all_in_manifest

Runs touch on all of the files in MANIFEST.

Methods for uploading

should_upload_to_pause

Should I upload to PAUSE? If "cpan_user" and "cpan_pass" are set, go for it.

check_for_passwords

Get passwords for CPAN.

get_changes()

Read and parse the Changes file. This is pretty specific, so you may well want to overload it.

show_recent_contributors()

Show recent contributors before creating/extending Changes.

This output relies upon the method "get_recent_contributors()" having been implemented in the relevant mixin for your version control system.

get_release_date()

Return a string representing the current date and time (in UTC) in the CPAN::Changes::Spec format so that it can be added directly to the Changes file.

run

Run a command in the shell.

run_error

Returns true if the command ran successfully, and false otherwise. Use this function in any other method that calls run to figure out what to do when a command doesn't work. You may want to handle that yourself.

get_env_var

Get an environment variable or prompt for it

Methods for developers

_print( LIST )

Send the LIST to whatever is in output_fh, or to STDOUT. If you set output_fh to a null filehandle, output goes nowhere.

_slurp

Read a line from whatever is in input_fh and return it.

_dashes()

Use this for a string representing a line in the output. Since it's a method you can override it if you like.

_debug( LIST )

Send the LIST to whatever is in debug_fh, or to STDERR. If you aren't debugging, debug_fh should return a null filehandle.

_die( LIST )

_warn( LIST )