Dist::...utorial(3pm)

💖 Dist::Milla::Tutorial 💖

okay bestie, so this is Dist::Milla::Tutorial — literally the Milla HOW TO — and it lives in the User Contributed Perl Documentation section of the manual, section 3pm. Milla is the build-and-release bestie and this page is the entire getting-started arc. Buckle up, we're going on a journey 🦋

---

✨ NAME ✨

Dist::Milla::Tutorial — the Milla HOW TO. that's it, that's the name, iconic 💅

---

🌈 WORKFLOW 🌈

There's also a screencast that walks you through setting up and creating a brand new distribution with Milla:

http://weblog.bulknews.net/post/46471116934/introducing-milla

watch it if you want the cinematic experience 🎬

🎀 Setup 🎀

First things first: install Milla and set up your profile.

> cpanm Dist::Milla
> milla setup

The setup command asks you one simple question to make a basic profile. And here's the tea: if you already set up dzil before, this is all common ground and you can totally skip the process. ✨

🦋 Making a new distribution 🦋

Now it's time to make a new distribution, no cap.

> milla new Dist-Name
> cd Dist-Name

At this point you've got a really simple Dist-Name directory containing your module file with as minimum boilerplate as possible. living the minimalist dream 🧚

It is recommended to track your repository under git as soon as possible — even before releasing to CPAN. fr fr.

# git is already initialized and files are added for you
> git commit -m "initial commit"

Now start writing your code, edit the docs, tests, and manage CPAN dependencies with cpanfile:

> $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile

You can test your code with a simple prove -l t. easy 💖

For the first time build only, you can make a test build to get some boilerplate you want to keep in the git repository — so your github repo looks great with a README, is installable from git using cpanm, and is testable with Travis CI:

> milla build
> git add Build.PL META.json README.md && git commit -m "git stuff"

👑 Making the first release 👑

When you get confident and it's about time to ship to CPAN, use the test and release command. Before doing so, make sure your git directory is not dirty — i.e. all changes are committed. no stray files bestie, I'm begging 😭

> git commit -a -m "Done initial version"

Milla assumes you have a git remote setup so you can push all your changes to. The recommendation is to use either the hub gem — https://rubygems.org/gems/hub — or App::ph to create a new github repository:

# Use hub rubygem
> hub create

# Use App::ph
> ph import

Now, make sure you have a Changes file ready and have a new entry under {{$NEXT}}, which will be expanded to the next version of your module. ✨

> $EDITOR Changes
> milla test
> milla release

And your first release is done. The release is tagged on git and all the changes atomically made are committed to git as well. slay 💅

🫶 If this is your first conversion to Milla and you want to make sure you're not going to mess CPAN with a bad archive when something goes wrong, you can run the release command with the FAKE_RELEASE environment variable. This runs all the other release process, except the UploadToCPAN step.

> FAKE_RELEASE=1 milla release

Wait for PAUSE to process it and your module to show up on MetaCPAN in a few minutes. Congratulations! 🎉🌸

💜 Making a maintainance release 💜

You've got new features, bugs, pull requests, and you're getting ready to make the next version of your module. Great news: making a new release is equally easy. 😌

First, make sure all your code has been committed to git and there are no dirty files in the working directory.

Then make sure to edit the Changes file and contain entries for the next release under {{$NEXT}}. You don't need to commit the change to the Changes file, yet.

Now, make a release!

> milla test
> milla release

The release command will automatically bump the version for you — if you have 0.10, the next version will be 0.11 by default, but you will be prompted to confirm that version in case you need a major bump.

This will update Changes, META.json and bump $VERSION in your main module. These changes made by Milla will be automatically committed, tagged and pushed to the remote. ate. 🔥

---

🌸 MIGRATING 🌸

This section describes how to migrate your current authoring process to Milla. glow-up time 🦋

⭐ Automatic migration ⭐

Sister project Minilla provides a wonderful conversion tool to migrate your existing distribution to Milla — which happens to be compatible with Milla as well.

As an author of Milla, I use Minilla's migrate command all the time to get the most of conversion done. iykyk 💅

To run the Minilla migration tool, install Minilla from CPAN and run the minil migrate command in the project root:

> cpanm Minilla
> minil migrate && git rm -f minil.toml

The command will output the migration process, and git add all the changed files for you. Once the migrate command is complete, all you have to do is create a dist.ini file and run the build command:

> echo "[@Milla]" > dist.ini
> milla build

😭 If one of the commands has failed, you might need to reset to the original state and run the manual migration. Read on to see how to do that.

🧚 Manually migrating from other build tools 🧚

🍓 Module Dependencies to cpanfile 🍓

First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile.

The easiest way to convert existing dependencies to cpanfile is to use the command line tool mymeta-cpanfile, which is installed with Module::CPANfile. Run the configuration with Makefile.PL for the one last time, then run the mymeta-cpanfile command:

> perl Makefile.PL
> mymeta-cpanfile --no-configure
requires 'DBI', '1.000';

on test => sub {
    requires 'Test::More', '0.86';
}

...

You can redirect the output to cpanfile if you like. It is important to pass the --no-configure option here, since otherwise modules like ExtUtils::MakeMaker will be included. It is not required with Milla setup, since Milla knows which configuration tool (installer) to use and includes them in META files upon the releases. You can leave that out from the cpanfile.

If you decide to manually construct a new cpanfile, the format is mostly compatible to Module::Install's requirement DSL.

# Makefile.PL
test_requires 'Test::More', 0.90;
requires 'Plack', '1.000';

becomes:

# cpanfile
test_requires 'Test::More', 0.90;
requires 'Plack', '1.000';

which is exactly the same. ✨ If you use Module::Build or ExtUtils::MakeMaker, that will be more manual process, but basically the same thing. See cpanfile for the available syntax.

💅 Remove boilerplate 💅

Next, remove unnecessary boilerplate files.

> git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit

🎀 Create a new ini and edit configurations 🎀

Next, create a new dist.ini with the following two lines:

name = Dist-Name
[@Milla]

The name = line is optional.

If your work directory is named Dist-Name, Milla will be able to figure out that is your distribution name, so you can omit that line. ✨

Next, edit .gitignore and add the following lines:

/Dist-Name-*
/.build
!META.json

You're almost done, and your directory will look like:

cpanfile
dist.ini
lib/Dist/Name.pm
t/...

git add the newly created files and commit it. 💖

🦋 Make a new build 🦋

Now you're ready to make the first build.

> milla build

and if it was successful, you get a build in a directory called Dist-Name-v0.1.0 under your current directory. They can be later removed with the milla clean command.

Also, new Build.PL, META.json and README.md are added in your working directory for git-friendliness. git add them and commit it.

> git add Build.PL META.json README.md && git commit -m "git stuff"

Now you're ready to roll a new release with Milla. Before doing so, convert your Changes file format a little bit, and make sure you have a following header in the top:

{{$NEXT}}
        - Change log entry for the next version

The {{$NEXT}} is a template variable that gets replaced with the version and date string, when you make a next release. This is almost the only change you're required to make in your code base. literally one thing bestie 😌

Now, run the release command:

> milla release

to make a new release, in the same way described above for a new Milla setup. You can set the FAKE_RELEASE environment variable if this is your first conversion and want to double check what happens, before uploading to CPAN. 🔥

When this is not your first release, the version number gets automatically bumped by Milla, but you will be prompted if that is exactly the version you want, and if you want a major version up, you can specify to do so.

---

🌈 AUTHOR 🌈

Tatsuhiko Miyagawa — the icon, the moment, the main character 👑

---

💖 SEE ALSO 💖

• Dist::Milla

---

and that's the whole page bestie!! this manual came to you from perl v5.42.0, dated 2025-07-25, sitting pretty in the Dist::...utorial(3pm) slot of the User Contributed Perl Documentation. mwah, go ship something iconic 🫶✨🎀