Now that we have set up our mbtiny configuration in the previous post, we can actually use it.

Minting a new distribution

Minting a distribution is trivial once you’ve completed the setup. It’s typically just a matter of calling mbtiny mint Foo::Bar. If needed you can override the global configuration at minting time (e.g.  mbtiny mint Foo::Bar --license BSD).

Converting an existing distribution

You can also convert an existing distribution to App::ModuleBuildTiny. In most cases that requires just two things:

1. Delete the pre-existing Makefile.PL / Build.PL

2. run mbtiny config copy, to copy the global configuration into the local project.

Prereqs

Prerequisites can be handled in two ways. If the auto_scan option is enabled, dependencies will be automatically detected, usually that is enough. Alternatively, you can set them explicitly prereqs.yml or a cpanfile. E.g.

# prereqs.yml

runtime:
  requires:
    perl: '5.012'
    Path::Tiny: 0
  recommends:
    Term::ReadLine::Gnu: 0
test:
  requires:
    Test::More: '0.88'

It should be noted that App::ModuleBuild::Tiny will automatically inject a configure dependency on the build tool (usually Module::Build::Tiny).

Main subcommands

App::ModuleBuildTiny mostly tries to stay out of your way. Mostly you can just develop your module the way you’re used to, you just need 2-3 commands to start to become productive:

regenerate

Typically this is run right before the release of a new version. It will regenerate all files that need regeneration. It’s no coincidence that almost all of the previously mentioned configuration is about this subcommand, it truly is the heart of the application. What it does exactly depends on your configuration but in a typical case it would:

• Bump the version in the module files

• Scan for prerequisites

• Scan the pod for the license / author

• Gather all metadata.

• Write Build.PL, META files, LICENSE, MANIFEST, etc…

• Update Changes file for the new version.

• Commit all of the above to git

If new to the tool you might want to do a git show before releasing, to better understand what it does, but in general it shouldn’t do anything surprising.

upload

This will do exactly what it advertises: creates a tarball for the distribution and uploads that to CPAN. Before doing that however it will do a series of preflight checks such as

• Check if the Changes file contains entries for this release.

• Check if the main module has an abstract in its pod.

• Check if your module has a valid version that matches the one in the meta file.

• Check if the desired version isn’t already tagged.

• Check if all tests pass.

After these tests it will ask for final confirmation and then uploads to PAUSE.

test

In simple modules, you don’t actually need this subcommand, you can just use prove -l instead. That said, mbtiny test does two additional things that make it useful:

1. It does a fresh and full distribution build, allowing one to test XS modules or generated modules.

2. It will run author tests (e.g. xt/pod-syntax.t), and with --release will also run release tests.

Secondary subcommands

mbtiny provides much more than just the above three commands. The full list is documented in the mbtiny script but some honorable mentions are:

listdeps

This lists the dependencies. This is particularly useful after a regeneration with auto-scan, to double check if the list of dependencies is what you expect it to be.

config

This allows you to inspect and update the configuration of the local distribution.  You may need this to change your configuration, or to update it if configuration options have been added.

Choosing install tool

By default it will use Module::Build::Tiny, as its name probably had already given away. For the vast majority of people this will be the right choice as it can handle pure-perl and simple xs modules just fine. But if you need to use Dist::Build instead that’s easy: it will automatically switch if it sees a planner/ directory (that is what Dist::Build uses for its build scripts). More about that in the next blogpost!