App::git::ship::perl - Ship your Perl module
# Set up basic files for a Perl repo # (Not needed if you already have an existing repo) $ git ship start lib/My/Project.pm $ git ship start # Make changes $ $EDITOR lib/My/Project.pm # Build first if you want to investigate the changes $ git ship build # Ship the project to git (and CPAN) $ git ship ship
App::git::ship::perl is a module that can ship your Perl module. This tool differs from other tools like dzil by *NOT* requiring any configuration, except for a file containing the credentials for uploading to CPAN.
See also "DESCRIPTION" in App::git::ship.
Example structure and how App::git::ship works on your files:
my-app/cpanfile and my-app/Makefile.PL
The cpanfile is used to build the "PREREQ_PM" and "BUILD_REQUIRES" structures in the ExtUtils::MakeMaker based Makefile.PL build file. The reason for this is that cpanfile is a more powerful format that can be used by Carton and other tools, so generating cpanfile from Makefile.PL would simply not be possible. Other data used to generate Makefile.PL are:
cpanfile
Makefile.PL
Note that the cpanfile is optional and Makefile.PL will be kept untouched unless cpanfile exists.
"NAME" and "LICENSE" will have values from "GIT_SHIP_PROJECT_NAME" and "GIT_SHIP_LICENSE" in App::git::ship. "AUTHOR" will have the name and email from "GIT_SHIP_AUTHOR" in App::git::ship or the last git committer. "ABSTRACT_FROM" and "VERSION_FROM" are fetched from the "main_module_path" in App::git::ship::perl. "EXE_FILES" will be the files in bin/ and script/ which are executable. "META_MERGE" will use data from "GIT_SHIP_BUGTRACKER" in App::git::ship, "GIT_SHIP_HOMEPAGE" in App::git::ship, and "repository".
bin/
script/
my-app/Changes or my-app/CHANGELOG.md
The Changes file will be updated with the correct "GIT_SHIP_NEW_VERSION_FORMAT", from when you ran the "build" action. The Changes file will also be the source for "GIT_SHIP_NEXT_VERSION". Both CHANGELOG.md and Changes are valid sources. App::git::ship looks for a version-timestamp line with the case-sensitive text "Not Released" as the the timestamp.
CHANGELOG.md
Changes
my-app/lib/My/App.pm
This file will be updated with the version number from the Changes file.
.gitignore and MANIFEST.SKIP
Unless these files exist, they will be generated from a template which skips the most common files. The default content of these two files might change over time if new temp files are created by new editors or some other formats come along.
t/00-basic.t
Unless this file exists, it will be created with a test for checking that your modules can compile and that the POD is correct. The file can be customized afterwards and will not be overwritten.
.git
It is important to commit any uncommitted code to your git repository beforing building and that you have a remote setup in your git repository before shipping.
.pause
You have to have a $HOME/.pause file before shipping. It should look like this:
$HOME/.pause
user yourcpanusername password somethingsupersecret
See "ENVIRONMENT VARIABLES" in App::git::ship for more variables.
This holds the arguments for the test program to use when building the project. The default is to not automatically run the tests. Example value:
GIT_SHIP_BUILD_TEST_OPTIONS="-l -j4"
Defaults to either "CHANGELOG.md" or "Changes".
Path to the main module in your project.
Defaults to the version number in "GIT_SHIP_MAIN_MODULE_PATH" + "0.01".
Use this to specify the version format in your "Changes" file. The example below will result in "## 0.42 (2014-01-28)".
GIT_SHIP_NEW_VERSION_FORMAT="\#\# %v (%F)"
"%v" will be replaced by the version, while the format arguments are passed on to "strftime" in POSIX.
The default is "%v %Y-%m-%dT%H:%M:%S%z".
$ git ship build
Used to build a Perl distribution by running through these steps:
Call "clean" to make sure the repository does not contain old build files.
Run prove if "GIT_SHIP_BUILD_TEST_OPTIONS" is set in "config".
Run "before_build" hook.
Render Makefile.PL
Add timestamp to changes file.
Update version in main module file.
Make MANIFEST
Make dist file (Your-App-0.42.tar.gz)
Run "after_build" hook.
See "can_handle_project" in App::git::ship.
$ git ship clean
Used to clean out build files:
Makefile, Makefile.old, MANIFEST, MYMETA.json, MYMETA.yml, Changes.bak, META.json and META.yml.
$ git ship
Used to ship a Perl distribution by running through these steps:
Find the dist file created by "build" or abort if it could not be found.
Run "before_ship" hook.
Add and commit the files changed in the "build" step.
Use "next_version" in App::git::ship to make a new tag and push all the changes to the "origin" git repository.
Upload the dist file to CPAN.
Run "after_ship" hook.
$ git ship start
Used to create main module file template and generate .travis.yml cpanfile, Changes, MANIFEST.SKIP and t/00-basic.t.
.travis.yml
MANIFEST.SKIP
$ git ship test-coverage
Use Devel::Cover to check test coverage for the distribution.
Set DEVEL_COVER_OPTIONS to pass on options to Devel::Cover. The default value will be set to:
DEVEL_COVER_OPTIONS=+ignore,t
$ git ship update
Action for updating the basic repo files.
App::git::ship
To install App::git::ship, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::git::ship
CPAN shell
perl -MCPAN -e shell install App::git::ship
For more information on module installation, please visit the detailed CPAN module installation guide.