/ 
CPAN-Maker-2.0.0 UNAUTHORIZED RELEASE
/ CPAN::Maker

NAME

CPAN::Maker - create a CPAN distribution

SYNOPSIS

cpan-maker -b buildspec.yml
cpan-maker build -b buildspec.yml

Options

-a, --author                author
-A, --abstract              description of the module
-B, --build-requires        build dependencies
-b, --buildspec             buildspec YAML file
    --cleanup, --no-cleanup remove temp dir after build (default: cleanup)
    --create-buildspec      name of a buildspec file to create
-d, --debug                 debug mode
    --destdir               destination directory for the tarball (default: cwd)
    --dryrun                dump parsed buildspec args and exit
    --exe-files             path to the executables list
    --extra-path            path to the extra files list
-h, --help                  help
-l, --log-level             ERROR, WARN, INFO, DEBUG, TRACE
-m, --module                module name
-M, --min-perl-version      minimum perl version to consider core (default: 5.010)
    --no-cleanup            preserve temp dir after build
    --no-require-versions   omit version numbers from dependencies
-P, --pager, --no-pager     use a pager for help (default: use pager)
    --pl-files              path to the PL_FILES list (see perldoc ExtUtils::MakeMaker)
    --postamble             name of the file containing the postamble instructions
    --preserve-makefile     copy Makefile.PL to destdir after build
-p, --project-root          default: current working directory
    --recurse               recurse directories when searching for files
-R, --require-versions      add version numbers to dependencies
    --scripts-path          path to the scripts listing
    --skip-tests            skip C<make test> during build
    --tests-path            path to the tests listing
-V, --verbose               verbose output
-v, --version               version
    --version-from          module that provides the version

Commands

  • build

    Parse a buildspec.yml file and build the CPAN distribution tarball. This is the default command and is invoked automatically when -b buildspec.yml is passed without an explicit command.

    cpan-maker build -b buildspec.yml
cpan-maker -b buildspec.yml

  • validate

    Validate a buildspec.yml file against the JSON Schema. Reports all errors before exiting. Returns a non-zero exit status if validation fails, making it suitable for use in CI pipelines.

    cpan-maker validate
cpan-maker validate path/to/buildspec.yml
cpan-maker -b path/to/buildspec.yml validate

    Note: If your file uses underscore-style keys (pm_module, extra_files, etc.) they are automatically normalized to their canonical hyphenated forms and a corrected copy is written to buildspec.yml.current.

  • write-makefile

    Generate a Makefile.PL to STDOUT from options passed on the command line. Useful for inspecting the generated Makefile.PL without running a full build.

    cpan-maker write-makefile -m Foo::Bar -r requires -a 'A. U. Thor <au@example.com>'

  • version

    Print the installed version of CPAN::Maker and exit.

    cpan-maker version

DESCRIPTION

CPAN::Maker is a utility for creating CPAN distribution tarballs from a declarative YAML build specification. It handles dependency resolution, Makefile.PL generation, file staging, and packaging entirely in Perl — no external bash scripts are required.

The build pipeline, invoked via cpan-maker -b buildspec.yml:

  • parses and validates the build specification

  • stages distribution files (lib, bin, t, extra-files, postamble) into a temporary build directory

  • generates a Makefile.PL in the build directory

  • runs perl Makefile.PL, make manifest, make dist, and optionally make test

  • copies the resulting tarball to the destination directory

Note: Prior to version 2.0.0, the build was delegated to an external bash script (make-cpan-dist). That script is no longer invoked and is retained only as a compatibility shim. All build logic now runs within cpan-maker itself.

OPTION DETAILS

-A, --abstract

A short description of the module purpose.

-a, --author

Author name and email address.

Example: -a 'Rob Lauer <rlauer6@comcast.net>'
-B, --build-requires

Path to a file listing build-time dependencies.

-b, --buildspec

Path to the build specification file in YAML format. See "BUILD SPECIFICATION FORMAT".

--cleanup, --no-cleanup

Remove the temporary build directory after the build completes. The default is to remove it. Use --no-cleanup to preserve the directory for inspection.

-C, --create-buildspec

Write a buildspec file derived from the current options to the named file.

-d, --debug

Enable debug logging.

--destdir

Directory where the finished tarball (and Makefile.PL if --preserve-makefile is set) will be written. Defaults to the current working directory.

--dryrun

Parse the buildspec and dump the resulting argument hash without running the build.

-h, --help

Print the option summary.

-l, --log-level

Log level. Valid values: error, warn, info, debug, trace. Default: error.

-m, --module

Name of the primary Perl module to package.

-M, --min-perl-version

Minimum Perl version used when determining which modules are core. Default: 5.010.

--no-cleanup

Preserve the temporary build directory after the build. Equivalent to --no-cleanup; the directory path is logged at debug level.

-P, --pager, --no-pager

Route help output through a pager. Default: use pager.

--pl-files

Path to a file listing PL_FILES targets. See ExtUtils::MakeMaker for the format.

--postamble

Path to a file containing Makefile postamble instructions to append to the generated Makefile.PL.

--preserve-makefile

Copy the generated Makefile.PL to --destdir after the build. Useful for inspecting the result.

-p, --project-root

Root of the project tree. Paths in the buildspec are resolved relative to this directory. Defaults to the current working directory.

--recurse

Recurse into subdirectories of the pm-module path when collecting modules. Default: yes.

-R, --require-versions, --no-require-versions

Include version numbers in the generated PREREQ_PM section. Default: include versions.

--skip-tests

Skip make test during the build.

--version-from

Module name from which the distribution version is extracted. Defaults to the primary module.

ENVIRONMENT VARIABLES

No environment variables are used by cpan-maker. Options previously controlled by PRESERVE_MAKEFILE, SKIP_TESTS, and DEBUG environment variables (which applied to the now-removed bash script) are now available as --preserve-makefile, --skip-tests, and --debug command-line options.

BUILD SPECIFICATION FORMAT

The preferred way to use cpan-maker is with a buildspec.yml file:

cpan-maker -b buildspec.yml

Minimal example

project:
  description: My awesome module
  author:
    name:   A. U. Thor
    mailto: au@example.com

pm-module: Foo::Bar

dependencies:
  requires:      requires
  test-requires: test-requires

Full key reference

project
description

Short description of the module. Used as ABSTRACT in Makefile.PL.

author
name

Author's full name.

mailto

Author's email address.

git

URI of the project's git repository.

pm-module

The fully-qualified name of the primary module to package (e.g. Foo::Bar).

version-from

Module from which the version number is read. Defaults to pm-module.

min-perl-version

Minimum Perl version to assume when deciding which modules are core. Default: 5.010.

List of name: Module::Name pairs. For each entry a man page symlink is created so that man name resolves to the module's man page.

man-links:
  - foo-bar: Foo::Bar
include-version

Whether to include version numbers in dependency declarations. Set to no to omit. Default: yes.

dependencies
requires

Path to a file listing runtime dependencies. Defaults to a file named requires in the project root.

test-requires

Path to a file listing test dependencies.

build-requires

Path to a file listing build-time dependencies.

recommends

Path to a file listing optional recommended dependencies. These appear under prereqs.runtime.recommends in generated META files and are installed by cpanm --with-recommends.

resolver (optional)

Name of a program that produces a dependency list when passed a module name. Use the special value scandeps to invoke scandeps.pl.

required-modules

Whether the resolver should follow require statements. Default: yes.

path (optional)
pm-module

Directory containing the module files. Default: lib.

recurse (optional)

Whether to recurse into subdirectories. Default: yes.

tests (optional)

Directory containing test files (*.t).

exe-files

Directory containing executable Perl scripts. Only files with executable permissions are included.

Examples:
  src/main/perl/bin
  bin/
scripts

Directory containing non-Perl executable scripts (e.g. bash). Only files with executable permissions are included.

provides (optional)

Explicit list of modules provided by this distribution. By default all .pm files found under the pm-module path are listed.

resources (optional)

Values added to the resources section of META_MERGE in the generated Makefile.PL. See CPAN::Meta::Spec for the format.

extra-files (optional)

List of files to be included in the package.

Examples:

extra-files:
  - ChangeLog
  - README
  - examples:
      - src/examples  <= include all files in this directory

extra-files:
  - ChangeLog
  - README
  - examples:
      - src/examples/foo.pl
      - src/examples/boo.pl

CAUTION: specifying a directory will include ALL of the files in that directory. It is better practice to list the specific files you want to include, or provide a manifest of files via the extra key:

extra: manifest

If you include a share destination in your extra-files specification, those files will be installed as part of the distribution under the share directory. The installed location can be found at runtime with:

perl -MFile::ShareDir=dist_dir -e 'print dist_dir(q{My-Project});'

The specification...

extra-files:
  - share:        <= indicates ../auto/share/dist/My-Project
      - resources/foo.cfg

...would package resources/foo.cfg from your project into the distribution's share directory root. While this specification...

extra-files:
  - share/resources:   <= indicates ../auto/share/dist/My-Project/resources
      - resources/foo.cfg

...would package foo.cfg into the resources subdirectory of the distribution's share directory.

All other files in the extra-files section will be added to the root of the tarball but will not be installed.

extra (optional)

Path to a manifest file listing additional files to include, one per line.

Key Naming

Keys may be written with hyphens (pm-module) or underscores (pm_module). The hyphenated form is canonical. If underscore keys are detected they are normalised before parsing and a corrected copy of the buildspec is written to buildspec.yml.current. The original file is never modified.

DEPENDENCIES

Runtime and test dependencies are read from plain-text files, one module per line with an optional version number:

Amazon::Credentials 1.15
HTTP::Tiny

By default the files are named requires and test-requires. The paths can be overridden in the dependencies section of the buildspec.

If the dependency file is named cpanfile it is parsed in cpanfile format.

VERSION

This documentation refers to version 2.0.0

AUTHOR

Rob Lauer - <rlauer@treasurersbriefcase.com>