NAME
Module::Release - Automate software releases
SYNOPSIS
use Module::Release;
my $release = Module::Release->new( %params );
# call methods to automate your release process
$release->check_vcs;
...
DESCRIPTION
Module::Release
automates your software release process. It started as a script that automated my release process, so it has bits to talk to PAUSE (CPAN) and SourceForge, and to use Makefile.PL
and CVS
. Other people have extended this in other modules under the same namespace so you can use Module::Build
, svn
, and many other things.
The methods represent a step in the release process. Some of them check a condition (e.g. all tests pass) and die if that doesn't work. Module::Release
doesn't let you continue if something is wrong. Once you have checked everything, use the upload features to send your files to the right places.
The included release
script is a good starting place. Don't be afraid to edit it for your own purposes.
Configuration
Module::Release
looks at several sources for configuration information.
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 useTest::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 aModule::Build
-based system.If this is set to
"Build.PL"
, this his will also causeModule::Build::Prereqs
to useTest::Prereqs::Build
instead ofTest::Prereqs
. - makefile
-
The name of the file created by
makefile_PL
above. The default is"Makefile"
, but you can set it to"Build"
forModule::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
If you don't like what any of these methods do, override them in a subclass.
- 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 forModule::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 themakefile_PL
andmake
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 theirnull_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
andcpan_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 )
TO DO
* What happened to my Changes munging?
CREDITS
Ken Williams turned my initial release(1) script into the present module form.
Andy Lester handled the maintenance while I was on my Big Camping Trip. He applied patches from many authors.
Andreas König suggested changes to make it work better with PAUSE.
Chris Nandor helped with figuring out the broken SourceForge stuff.
H.Merijn Brand has contributed many patches and features.
SOURCE AVAILABILITY
This source is in GitHub
https://github.com/briandfoy/module-release
AUTHOR
brian d foy, <bdfoy@cpan.org>
COPYRIGHT AND LICENSE
Copyright © 2007-2023, brian d foy <bdfoy@cpan.org>
. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the Artistic License 2.0.