/ 
App-git-ship-0.37
River stage zero No dependents
/ App::git::ship::perl

NAME

App::git::ship::perl - Ship your Perl module

SYNOPSIS

# 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

DESCRIPTION

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:

    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".

  • 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.

  • 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:

    user yourcpanusername
password somethingsupersecret

ENVIRONMENT VARIABLES

See "ENVIRONMENT VARIABLES" in App::git::ship for more variables.

GIT_SHIP_BUILD_TEST_OPTIONS

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"

GIT_SHIP_CHANGELOG_FILENAME

Defaults to either "CHANGELOG.md" or "Changes".

GIT_SHIP_MAIN_MODULE_PATH

Path to the main module in your project.

GIT_SHIP_NEXT_VERSION

Defaults to the version number in "GIT_SHIP_MAIN_MODULE_PATH" + "0.01".

GIT_SHIP_NEW_VERSION_FORMAT

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".

METHODS

build

$ git ship build

Used to build a Perl distribution by running through these steps:

  1. Call "clean" to make sure the repository does not contain old build files.

  2. Run prove if "GIT_SHIP_BUILD_TEST_OPTIONS" is set in "config".

  3. Run "before_build" hook.

  4. Render Makefile.PL

  5. Add timestamp to changes file.

  6. Update version in main module file.

  7. Make MANIFEST

  8. Make dist file (Your-App-0.42.tar.gz)

  9. Run "after_build" hook.

can_handle_project

See "can_handle_project" in App::git::ship.

clean

$ git ship clean

Used to clean out build files:

Makefile, Makefile.old, MANIFEST, MYMETA.json, MYMETA.yml, Changes.bak, META.json and META.yml.

ship

$ git ship

Used to ship a Perl distribution by running through these steps:

  1. Find the dist file created by "build" or abort if it could not be found.

  2. Run "before_ship" hook.

  3. Add and commit the files changed in the "build" step.

  4. Use "next_version" in App::git::ship to make a new tag and push all the changes to the "origin" git repository.

  5. Upload the dist file to CPAN.

  6. Run "after_ship" hook.

start

$ git ship start

Used to create main module file template and generate .travis.yml cpanfile, Changes, MANIFEST.SKIP and t/00-basic.t.

test_coverage

$ 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

update

$ git ship update

Action for updating the basic repo files.

SEE ALSO

App::git::ship