The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

mbtiny - A standalone authoring script for Module::Build::Tiny

SYNOPSIS

mbtiny listdeps | cpanm
mbtiny test --release
mytiny regenerate
mbtiny upload

DESCRIPTION

mbtiny is a tool to help assemble your CPAN distributions. It's a minimalist tool that tries to come with as few surprises as possible, and thus provide a gentle learning curve for its users.

SUBCOMMANDS

regenerate [--bump] [--version=<version] [--verbose] [--dry-run] [--scan] <files>...

Regenerate the specified files. If no files are given, defaults to all six files it can regenerate. You usually want to do this when bumping the version of a module. Takes the following options:

  • bump

    Bump the version of the distribution before regenerating. The default for this when regenerating all files can be set in the configuration.

  • version = <new-version>

    Set the version of the distribution before regenerating.

  • scan

    Scan for dependencies to include in the metafiles. The default for this can be set in the configuration.

  • trial

    Make the new version a trial version.

  • commit

    Create a git commit for the version bump. The default for this when regenerating all files can be set in the configuration.

  • verbose

    This will make regeneration more verbose.

  • dry-run

    This will cause it to not write anything to disk, this is only ever useful when combined with the verbose option.

The following files can be generated:

  • Build.PL

    The code needed to build the dist using Module::Build::Tiny or Dist::Build.

    It will use the former unless a planner/ directory is present.

  • MANIFEST

    The list of files in this distribution, and optionally descriptions.

  • META.json

    Most meta information about this distributions. Useful for both presenting information to the user as for installing the distribution.

  • META.yml

    The legacy meta file. This is mainly useful for bootstrapping on CPAN clients too old to support META.json but recent enough to support configure_requires.

  • README

    A description of the project, based on the documentation of the main module.

  • LICENSE

    The license of the distribution.

upload [--silent] [--config=<config_file>] [--tag] [--push]

Assemble a tarball and upload it to CPAN.

Using a Config::Identity compatible .pause file in your home directory is recommended, but if it's absent or incomplete your credentials will be asked on the console. Takes the following options:

  • tag

    Tag the current release with the current version. The default for this can be set in the configuration.

  • push

    Push the current commit, and tag it --tag is also specified. The default for this can be set in the configuration.

  • silent

    This will enable silent mode

  • config=<config-file>

    The location of your pause credentials

test [--no-author] [--release]

Run all of the tests of a distribution. Takes two negatable options:

  • release

    Run release tests. Defaults to false.

  • author

    Run author tests. Defaults to true.

scan [--omit-core=<version>] [--omit=<module>]

Scan the lib/, script/ and t/ directories for dependencies and write them to prereqs.json. Accepts the following option:

  • omit_core = version

    Set a minimum perl version (e.g. 5.008001 or v5.8.1) whose core-provided dependencies will not be explicitly included.

  • omit = module

    Omit a specific module from the dependencies. Can be specified multiple times.

mint [--<option>=<value>]... <distribution>

Create a new distribution. Takes one mandatory positional argument, the name of the new distribution, and the following optional named arguments:

  • abstract

    The abstract of this new distribution. Defaults to an empty string.

  • author

    The name of the author of this distribution. The default value is set in the configuration file.

  • dirname

    The directory name for the new distribution. Defaults to the distribution name.

  • email

    The email address of the author. The default value is set in the configuration file.

  • license

    The license of the new distribution. The default value is set in the configuration file, this is usually Perl_5.

  • version

    The initial version of the new distribution. Defaults to 0.001.

  • init-git

    Initialize a git repository on minting.

setup <type>

Create or update your configuration file (at ~/.mbtiny/config). Takes one optional positional argument that can take any of the following values:

  • update

    Ask about all configuration items that are currently empty. This is the default.

  • all

    Ask about all configuration items, even if they currently have a value.

  • list

    List your current configuration.

  • reset

    Remove the current configuration file.

listdeps [--versions] [--json] [--missing] [--omit-core=<version>]

List all dependencies of this distribution. By default it prints just a list of module names.

  • versions

    Print the required versions along with the modules.

  • json

    Output the dependencies in JSON format

  • missing

    List only modules whose requirement isn't met.

  • author

    Include development-time dependencies, such as App::ModuleBuildTiny itself.

  • omit-core=<perl-version>

    Exclude any prerequisites that are provided by that specific perl version.

run [--no-build] <command>

Run the specified command in an assembled distribution. It takes one boolean argument:

  • no-build

    Do not build the distribution (run Build.PL and Build) before running the command.

shell [--build]

Run a shell in the assembled distribution. This is equivalent to mbtiny run --no-build $SHELL. It takes one argument.

  • build

    Build the distribution before running the shell.

dist

Create a distribution tarball.

distdir

Create a directory containing all of the files of the distribution.

version

This prints the version of mbtiny.

INPUTS

The metadata for the distribution is gathered from various sources.

  • The distribution name is taken from the local directory name.

  • The version, abstract and author are taken from the main module of the distribution.

  • The license is extracted from the POD, unless a metamerge file overrides this

  • Prerequisites are mostly taken from prereqs.json, prereqs.yml and (discouraged) cpanfile, except when injected explicitly (e.g. a configure dependency on Module::Build::Tiny).

    # prereqs.yml
    runtime:
      requires:
        perl: '5.012'
        Path::Tiny: 0
      recommends:
        Term::ReadLine::Gnu: 0
    test:
      requires:
        Test::More: '0.88'
  • A metamerge.json or metamerge.yml file can be used to merge any additional meta information you want (including dependencies). It is assumed to be in meta-spec 2 format unless otherwise specified.

    # metamerge.yml
    resources:
      bugtracker:
        web: https://github.com/leont/App-ModuleBuildTiny/issues
      homepage: http://example.org/
      x_IRC: irc://irc.perl.org/#toolchain