view release on metacpan or  search on metacpan

share/README.md  view on Meta::CPAN

## What Does NOT Belong in `project.mk`

- Modifications to existing targets like `all`, `clean`, `requires`
- Replacing managed variables such as `DEPS` or `CLEANFILES`.

    Use documented extension points such as `CLEANFILES +=` where
    provided rather than redefining the managed value.

- Anything that duplicates logic already in the managed Makefile

## Custom Template Tokens

The build generates each `.pm`/`.pl` from its `.pm.in`/`.pl.in` source
by substituting `@TOKEN@` placeholders through `cmb resolve-vars`.
The standard tokens (`@PACKAGE_VERSION@`, `@MODULE_NAME@`,
`@GIT_SHA@`, and the other git-metadata variables) are always
available, but the mechanism is extensible: a project can define its own
tokens without editing any managed file.

To add a token, declare its name in `TEMPLATE_VARS` (in
`project.mk`) and provide a value -- as a make variable, an exported
environment variable, or through the variables file passed to
`resolve-vars`. For example, to stamp a build timestamp:

    # in project.mk
    BUILD_DATE      := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
    TEMPLATE_VARS   += BUILD_DATE

    # in a .pm.in source
    our $BUILD_DATE = 'E<64>BUILD_DATEE<64>';

`cmb resolve-vars` then fills `@BUILD_DATE@` from the value
when its prerequisites require regeneration. The token grammar is
uppercase-only (`@[A-Z0-9_]+@`), so placeholders never
collide with real Perl such as `@_` or `@ISA`.

By default, substitution is **fail-loud** for placeholders that appear
in live code: if a token has no value, the build stops and names the
offending token rather than silently substituting an empty string.

Placeholders that occur only in POD or comments do not require values.
`--no-strict` may be used to downgrade a missing live-code value to a
warning and leave the placeholder unchanged.

## Keeping the build system up to date

The following targets manage the lifecycle of the build system itself:

- `make check-upgrade` / `make upgrade-check`

    Checks MetaCPAN to see if a newer version of
    `CPAN::Maker::Bootstrapper` is available.

- `make publish`

    Builds the distribution tarball, unpacks it into a temporary directory,
    runs its normal `Makefile.PL`, build, and test sequence, and uploads
    the tarball to PAUSE if all checks succeed.

    Set the PAUSE credentials with:

        make publish PAUSE_USER=username PAUSE_PASSWORD=password

- `make upgrade`

    Checks MetaCPAN, installs the latest version via `cpanm`, then
    automatically runs `make update` to refresh the managed project
    files.

- `make update`

    Copies the managed files from the currently installed bootstrapper
    distribution into your project directory. After running, use
    `git diff` to review what changed.

    The following files are managed and may be updated:

        Makefile
        .includes/bootstrap.mk
        .includes/perl.mk
        .includes/local.mk
        .includes/git.mk
        .includes/help.mk
        .includes/update.mk
        .includes/upgrade.mk
        .includes/version.mk
        .includes/release-notes.mk
        .includes/bash-completion.mk
        .includes/modulino.mk
        .includes/publish.mk

    Your `project.mk`, `buildspec.yml`, `requires`, `VERSION`, source
    files and tests are **never** touched by `make update`.

- `make cpanm`

    Installs `cpanminus` if it is not already available on your
    `PATH`. Required for `make upgrade` to work:

        make cpanm && make upgrade

## Automatic Drift and Update Checks

Every build runs two checks before proceeding, so you don't have to
remember to run `make check-upgrade` yourself:

- Is a newer `CPAN::Maker::Bootstrapper` published on CPAN than the
one installed on this machine?
- Do this project's managed files still match what the _currently
installed_ `CPAN::Maker::Bootstrapper` would produce?

These are independent questions - your installed bootstrapper can be
fully current while a given project has still drifted from it (most
commonly because the project hasn't been through `make update`
since you last upgraded), or your bootstrapper itself can be behind
CPAN while every project stays perfectly in sync with it.

_Drift_ can happen for either of two reasons: your installed
`CPAN::Maker::Bootstrapper` was upgraded since this project last ran
`make update`, or a managed file was hand-edited despite the