The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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

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

  • bump

    Bump the version of the distribution before regenerating. The default for this 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 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.

It generates the following files:

  • Build.PL

    This contain the code needed to build the dist using Module::Build::Tiny.

  • MANIFEST

    This contains the list of files in this distribution, and optionally descriptions.

  • META.json

    The file containing most meta information about this distributions. Useful for both presenting information to the user as for installing the distribution.

  • META.yml

    This is 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 file containing a description of the project, based on the documentation of the main module.

  • LICENSE

    This contains the license of the distribution.

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

This assembles a tarball and uploads 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.

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

This runs all of the tests of a distribution. It takes two negatable options:

  • release

    Run release tests. Defaults to false.

  • author

    Run author tests. Defaults to true.

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

This will scan the lib/, script/ and t/ directories for dependencies and writes them to prereqs.json. It accepts the following option:

  • omit_core = version

    This allows you to set a minimum perl version (e.g. 5.008001 or v5.8.1) whose core-provided dependencies will not be explicitly included.

  • omit = module

    This will omit a specific from the dependencies, it can be specified multiple times.

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

This creates a new distribution. It takes one mandatory positional argument, the name of the new distribution, and up to six optional named arguments

  • abstract

    The abstract of this new distribution. It 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. It 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. It default is set in the configuration file, this is usually Perl_5.

  • version

    The initial version of the new distribution. This defaults to 0.001.

  • init-git

    Initialize a git repository on minting.

setup <type>

This creates or update your configuration file (at ~/.mbtiny/config). It takes one optional position argument that can take any of the following values:

  • update

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

  • all

    This asks you about all configuration items, even if they currently have a value.

  • list

    This lists your current configuration.

  • reset

    This removes the current configuration file.

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

List all dependencies of this distribution. By default it prints a list of modules. If the json option option is given, it's printed as JSON instead.

  • versions

    This will cause it to print out the required versions along with the modules.

  • json

    This will cause it to output the dependencies in JSON format, instead of a list format

  • missing

    This will cause it to list only modules whose requirement isn't met.

  • author

    This will cause the list to include development-time dependencies, such as App::ModuleBuildTiny itself.

  • omit-core=<perl-version>

    This will cause the list to 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

    This will cause mbtiny not to build the distribution (run Build.PL and Build) before running the command.

shell [--build]

Runs the $SHELL, this is equivalent to mbtiny run --no-build $SHELL. It takes one argument.

  • build

    This will cause mbtiny to build the distribution before running the shell.

dist

This creates a distribution tarball.

distdir

This creates a directory containing all of the files of the distribution.

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