Dist::Mgr - Automation for Perl distribution creation, integration, pre-release, release and post-release tasks.
For end-users, please review the documentation for the distmgr program that we've installed for you as part of this distribution.
This software performs a full suite of automated creation, addition, pre-release, release and post release tasks for Perl distributions. It integrates with VCS, automates the configuration of Continuous Integration, manages version numbers and Changes files, amongst a slew of other tasks.
This distribution is essentially a bunch of tools that revolve around a base distribution created with module-starter.
module-starter
At this time, it relies on using Module::Starter for initial distribution creation, Github for repository and bugtracker, and the ExtUtils::MakeMaker build system, which utilizes Makefile.PL files.
Makefile.PL
use Dist::Mgr qw(:all) ...
We do not automatically import anything into your namespace, you must request functionality explicitly. Use the :all tag, or have a peruse through the "FUNCTIONS" section for what's available.
:all
Adds bugtracker information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.
META_MERGE
Currently, only Github is supported.
Use: After "init", or any time.
Parameters:
$author
Mandatory, String: The Github username of the software author. For example, mine is stevieb9.
stevieb9
$repository
Mandatory, String: The name of the repository. For example, the repository name for this distribution is dist-mgr.
dist-mgr
$makefile
Optional, String: The path and name of the Makefile.PL file to use. We default to ./Makefile.PL.
./Makefile.PL
Returns: 0 upon success.
0
Adds repository information to the Makefile.PL file. If the required META_MERGE section doesn't exist, we'll create it.
Creates or updates the initial Module::Starter Changes file to my custom standard format.
Changes
Use: After "init".
$module
Mandatory, String: The name of the module (eg. Acme::STEVEB).
Acme::STEVEB
$file
Optional, String: The path and name of the Changes file to operate on. By default, we operate on the Changes file within the current working directory, ..
.
Returns: The contents that were added into the file.
Prepares the Changes file for a new development cycle after a release.
Use: After "changes_date" and the release has been published.
$version
Mandatory, Version: A valid Perl version number. Must be higher than the previous release version.
Optional, String: The name of the Changes file to operate on. Defaults to the one in the current working directory.
Replaces the UNREL tag with today's date, in preparation of a release.
UNREL
Use: As part of the release cycle, before release and "changes_bump".
Optional, String: The name of the Changes file to operate on. By default, we operate on the one in the current working directory.
Inserts various CI and coverage badges into module files.
Mandatory, String: The repository owner (eg. mine is 'stevieb9').
Mandatory, String: The name of the repository (eg. this one is 'dist-mgr').
$fs_entry
Optional, String: The path and name of a Perl module file, or a directory that contains Perl module files. If a directory is sent in, we'll operate recursively.
Installs a Github Actions configuration file into .github/workflows. We'll create the directory if it doesn't exist.
.github/workflows
Use: Any time.
$os
Optional, Array Reference: A list of the Operating Systems you want to run your tests on.
Valid values: l, w, m, where:
l
w
m
l == Linux (Ubuntu to be specific) w == Windows m == MacOS
Defaults: Test suite will be run on Operating Systems ubuntu-latest, windows-latest, macos-latest. Each OS will run the tests on Perls 5.32, 5.24, 5.18, 5.14 and 5.10.
ubuntu-latest
windows-latest
macos-latest
5.32
5.24
5.18
5.14
5.10
Returns: An array of the contents of the generated file.
Writes out a default configuration file if one doesn't exist, and updates the %args hash within a function.
%args
\%args
Mandatory, Hash reference: Send in a reference to your %args hash, and we'll update it with any directives within the configuration file before you send them off to other various routines.
Optional, String: The name of an alternate configuration file you'd like to write out, or read from. Default is $ENV{USERPROFILE}/dist-mgr.json on Windows systems, and $ENV{HOME}/dist-mgr.json on Unix systems.
$ENV{USERPROFILE}/dist-mgr.json
$ENV{HOME}/dist-mgr.json
Returns: The reference to the %args hash you sent in as the first parameter.
Returns the path and filename of the default configuration file. this is $ENV{USERPROFILE}/dist-mgr.json on Windows systems, and $ENV{HOME}/dist-mgr.json on Unix systems.
Finds and updates the copyright year of a Perl POD or module file, or all Perl files in a directory structure. We operate on all *.pl, *.pm and *.pod files.
*.pl
*.pm
*.pod
Use: Before publishing a release.
Optional, String: The name of a file or directory to work on. If a directory, we'll work on all Perl and POD files. Defaults to ..
Returns: A hash reference with the file name as the key, and the updated year as the value.
Fetches the current copyright year in a file or all files in a directory. We operate on all *.pl, *.pm and *.pod files.
Use: Anytime.
Returns: A hash reference with the file name as the key, and the current copyright year as the value.
Uploads the distribution tarball to PAUSE.
Use: After "make_dist".
$tarball_name
Mandatory, String: The name of the distribution's tarball file.
Optional, Hash: See CPAN::Uploader for full details. A couple of notes:
user
password
CPAN_USERNAME
CPAN_PASSWORD
dry_run => 1
Returns: Copy of %args hash on success.
Adds all files in the current working directory to the repository.
Note: Calls Dist::Mgr::Git::_git_add() internally.
Dist::Mgr::Git::_git_add()
Parameters: $verbose
Optional, Bool: Set to true to display the Git command output. Defaults to false.
Returns: Exit code from the system call.
system
Generates a .gitignore file.
.gitignore
$directory
Optional, String: The directory where we'll create the file. If not specified, we'll create it in the current directory, ..
Returns: An array of the file's contents.
Commits all changes to the repository.
Note: Calls Dist::Mgr::Git::_git_commit() internally.
Dist::Mgr::Git::_git_commit()
$msg
Mandatory, String: The commit message.
$verbose
Returns: Exit code.
Note: Calls Dist::Mgr::Git::_git_clone() internally.
Dist::Mgr::Git::_git_clone()
Mandatory, String: Your Github username.
Mandatory, String: The name of the pre-created Github repository.
Pushes the repository to Github.
Note: Calls Dist::Mgr::Git::_git_push() internally.
Dist::Mgr::Git::_git_push()
Does a git pull to fetch any update from the upstream.
git pull
Note: Calls Dist::Mgr::Git::_git_pull() internally.
Dist::Mgr::Git::_git_pull()
Commits and pushes the repository, and executes the CI test pipeline (if available).
Internally, this method calls "git_pull", "git_commit" then "git_push", all with their respective $verbose flags set to false. If you want to enable verbosity, instead of calling this function, call each one of those in order and set $verbose to true in each one.
Use: After "make_test".
Mandatory, String: The release version of the distribution.
$wait_for_ci
Optional, Bool: Whether to wait for keyboard interaction while CI testing runs. If set, we'll wait for you to press either CTRL-C to signifiy tests were successful and we should continue with the release cycle, or ENTER to signify that we should stop and wait for you to fix any test errors before running again.
CTRL-C
ENTER
Default: 1, Enabled.
1
Returns: 1 on test success (CTRL-C), 0 on test failure (ENTER).
Attempts to retrieve the repository name from the .git directory.
.git
Note: Calls Dist::Mgr::Git::_git_repo() internally.
Dist::Mgr::Git::_git_repo()
Returns: The string repository name on success, the exit code on failure.
Checks whether we need to commit and push.
Note: Calls Dist::Mgr::Git::_git_status_differs() internally.
Dist::Mgr::Git::_git_status_differs()
Returns: 1 if the repository differs and 0 if nothing needs to be done.
Tags the current state of the repository.
$tag
Mandatory, String: The tag for the commit.
Note: Calls Dist::Mgr::Git::_git_tag() internally.
Dist::Mgr::Git::_git_tag()
Initializes a new distribution using Module::Starter. The new directory will be placed into the current working directory (.).
Use: To create a brand new distribution skeleton.
module => "Acme::STEVEB"
Mandatory, String: The name of the main module of the distribution.
author => "Steve Bertrand"
Mandatory, String: The name of the distribution's author.
email => "steveb@cpan.org"
Mandatory, String: The email address of the author.
license => "artistic2"
Optional, String: The license to apply to the new distribution. Defaults to artistic2. See Module::Starter for valid entries.
artistic2
verbose => 1
Optional, Bool: If set, we'll display the progress of module creation.
Perform a make dist that creates a CPAN-ready distribution tarball file in the current working directory.
make dist
Use: After all other release functions have been called.
Optional, Bool: Set to true to display the output from the command.
Default: False
Returns: 0 on success. Anything other than 0 is a failure.
Perform a make distclean on the project directory.
make distclean
Use: After all other post-release functions have been called.
Perform a %^X Makefile.PL and make test.
%^X Makefile.PL
make test
Use: After "changes_date" and before all other release cycle functions.
Note: Do not call this function from within the test suite, or else it'll spin off into an infinite loop.
Note: Always check the return value of this function before proceeding with the rest of the release cycle. Zero 0 is success, everything else is fail.
Perform a make manifest.
make manifest
Use: Before running the release procedures.
Generates a MANIFEST.SKIP file.
MANIFEST.SKIP
Generates a t/manifest.t test file. This overrides the default created with Module::Starter, as some custom MANIFEST.SKIP entries fail with the older version of the file.
t/manifest.t
Optional, String: The directory where we'll create the file. If not specified, we'll create it in the t/ directory within the current directory, ..
t/
After an "init", this method will scoop up all of the files and directories from within the newly created temp module directory into the current working dir, then remove the temp module directory.
Use: Immediately after "init".
Mandatory, String: The name of the module that was created with "init", eg. Acme::STEVEB.
Removes unwanted file system entries. We always operate from the perspective of the current working directory (.).
Use: Immediately after "init" and "move_distribution_files".
Finds and updates the version number of a Perl module file, or all Perl module files in a directory structure.
Use: After publishing a release.
Mandatory, String: The new version to update to.
Optional, String: The name of a file or directory to work on. If a directory, we'll work on all Perl module files. Defaults to lib/.
lib/
The $version parameter can be prepended with an optional dash (-), and if so, we'll operate in "dry-run" mode, where we'll return the results, but won't have written to any files. Eg: version_bump('-1.01').
-
version_bump('-1.01')
Returns: An HoH:
$VAR1 = { 't/data/work/Two.pm' => { 'dry_run' => 0, 'from' => '2.66', 'to' => '2.67', 'content' => '' # Module file code (snipped for brevity) }, 't/data/work/One.pm' => { 'dry_run' => 0, 'from' => '2.66', 'to' => '2.67', 'content' => '' # Module file code (snipped for brevity) }, };
Increments a version number by 0.01, and returns the result.
0.01
Use: Any time
Mandatory, String: A valid version number (eg: 1.03).
1.03
Returns: The supplied version number incremented by 0.01.
Fetches the file version information of Perl module files. Can operate on a single file, or iterate over a directory structure.
Optional, String: The directory or file to operate on. If a directory is sent in, we'll iterate over all files in all directories recursively.
Default: lib/
Returns: Hash reference:
$VAR1 = { 't/data/orig/One.pm' => '2.66' 't/data/orig/Two.pm' => '2.66', 't/data/orig/Three.pm' => '2.66', 't/data/orig/Bad.pm' => undef, # $VERSION can't be parsed 't/data/orig/No.pm' => undef, # No $VERSION defined };
Steve Bertrand, <steveb at cpan.org>
<steveb at cpan.org>
Copyright 2020-2021 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
To install Dist::Mgr, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Mgr
CPAN shell
perl -MCPAN -e shell install Dist::Mgr
For more information on module installation, please visit the detailed CPAN module installation guide.