NAME

CPAN::Maker - create a CPAN distribution

SYNOPSIS

cpan-maker -b buildspec.yml
cpan-maker build -b buildspec.yml
cpan-maker create-cpanfile file1 file2 ...

Options

-a, --author                author in 'name <email>' format (default: anonymouse <anonymouse@example.org) 
-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
    --license               License under which the software can be used (default: perl)
-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
-o, --outfile               output file for create-cpanfile (default: cpanfile, - for STDOUT)
-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
    --recommends            path to the file containing the recommended modules and versions
    --recurse               recurse directories when searching for files
-R, --require-versions      add version numbers to dependencies
-r, --requires              path to the file containing the required modules and versions (required for write-makefile)
    --scripts-path          path to the scripts listing
    --skip-tests            skip C<make test> during build
    --suggests              path to the file containing the suggested modules and versions
    --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>'
  

• create-cpanfile

  Generate a cpanfile from one or more dependency list files. Each file contains one dependency per line in the format:

    Module::Name version [dist=name] [url=URL] [mirror=URL]
  

  Lines beginning with # are treated as comments and ignored. A leading + on a module name (as used in CPAN::Maker::Bootstrapper dependency files to pin a version) is stripped before processing. Duplicate entries are removed and the output is sorted alphabetically.

  By default the result is written to cpanfile in the current directory. Use -o - to write to STDOUT instead.

    cpan-maker create-cpanfile requires test-requires
    cpan-maker create-cpanfile -o - requires > cpanfile
    cpan-maker create-cpanfile -o my-cpanfile requires test-requires
  

  The optional dist=, url=, and mirror= qualifiers map to the corresponding cpanfile source directives, allowing you to pin dependencies to a specific distribution, URL, or mirror.

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

• -o, --outfile

  Output file path for the create-cpanfile command. Defaults to cpanfile in the current directory. Pass - to write to STDOUT.

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

• --recommends

  Path to a file listing recommended (but not strictly required) dependencies. Optional - a distribution with no recommended dependencies simply omits this option. See "BUILD SPECIFICATION FORMAT".

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

• -r, --requires

  Path to a file listing required (runtime) dependencies. Unlike --recommends and --suggests, this one is not optional: most CPAN installers (cpanm in particular) only install requires dependencies by default - --with-recommends and --with-suggests both default to off - so a distribution with no requires entries at all has, for practical purposes, no guaranteed dependencies. The write-makefile command enforces this and will refuse to proceed without a --requires file that actually exists. See "BUILD SPECIFICATION FORMAT".

• --skip-tests

  Skip make test during the build.

• --suggests

  Path to a file listing suggested (optional) dependencies - modules that meaningfully enhance the distribution but aren't needed for it to function. Optional - a distribution with no suggested dependencies simply omits this option. See "BUILD SPECIFICATION FORMAT".

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

• license

  License under which the software can be use.

  default: perl

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

• man-links

  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.

  • suggests

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

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

AUTHOR

Rob Lauer - rlauer@treasurersbriefcase.com