In this post I’d like to present the building tools I’m using for my projects. Hopefully after it there will be more contributions :)

I’m using a plugin for Dist::Zilla. Dist::Zilla comes from the severe perl world, where people with strong spirit writes a code which is 10 years backward-compatible (thanks to chromatic thats gradually changing).

Generally, Dist::Zilla is purposed to assist the CPAN authors, but it turned out, that many concepts are language and distribution platform neutral. For example integration with Git – in any language or any distribution platform you definitely want to tag the new release with version number. Then you probably want  to commit the updates. Another example will be `Changes` file – before release it definitely makes sense to check whether it contains the entries for new version. Etc.

All such routine tasks can be automated with the Dist::Zilla. It can create a barebone distribution, generate an appropriate LICENCE file, test the distribution, release it on `npm` and much more!

Setup

Installation of the perl modules is usually scary for people without perl background. So you are welcome to the #joose channel on freenode with any questions. There are also known problems on MacOS, so Mac owners are even more welcome :) Note, that you need to have ‘git’ installed.

I found it much easier to use the recently appeared Miyagawa’s “cpan-minus” tool. So, to install the cpanminus:

> curl -L http://cpanmin.us | perl - --sudo App::cpanminus

then

> cpanm Dist::Zilla::Plugin::JSAN --sudo

After installation, setup the Dist::Zilla in interactive mode (this is required only once):

> dzil setup
What's your name?...

When asked about the default license, here’s the list of available identificators (at the bottom and strip the leading “Software::License::”). The information you provided will be used during creation of new distributions.

Starting a distribution

To start a new distribution:

> dzil new -P JSAN -p joose Sample-Dist

[DZ] making target dir /home/nickolay/Playground/dzil/Sample-Dist
[DZ] writing files to /home/nickolay/Playground/dzil/Sample-Dist
[Git::Init] Initializing a new git repository in /home/nickolay/Playground/dzil/Sample-Dist
[DZ] dist minted in ./Sample-Dist>

This command should create a barebone distribution like this. It will also create a git repository and perform a famous “initial commit”! :) See this page to know how to customize the template.

And thats it! Distribution will contain a single main module with some documentation. After some hacking, you can easily publish the distribution in `npm` (see below).

The distribution will also contain a rudimentary test suite, which you can run in NodeJS (assuming you have test-run installed) with:

> node t/index.js

or, if you’ve completed the 3.1 and 3.2 steps from this document, in browsers. Put the distribution in some web-directory and point the browser to the URL like:

http://localhost/my_workspace/Sample-Dist/t/index.htnml

dist.ini

The whole building process is managed by the `dist.ini` file in the root of distribution. Its a text file which lists the used plugins and their parameters. For example:

; Auto-increment the version number, based on the tags information from git
[Git::NextVersion]
first_version   = 0.0.1

; include the link to git repo and web page (if "origin" points to github)
[GithubMeta]

For the details on the individual plugin, prepend its name with “Dist::Zilla::Plugin” and perform a CPAN search.

See the documentation for the full details on the JSAN plugin, here I’ll briefly describe some of the typical tasks.

Building the distribution

‘build’ command takes your sources as the input, process them (add/remove/change some files) and generate the output (location can be specified with ‘in’ option):

> dzil build [--in /target/dir]

Various plugins participate in this phase. Typical example will be [License] plugin, which adds a LICENSE file with the text of your license.

Releasing the distribution

‘release’ command first build the distribution, then runs plugins which implements the “release” phase. There is a [JSAN::NPM::Publish] plugin, which can publish your dist in npm:

> dzil release

Use case

For example, I’d like to include the version information in the source files, like:

Class('Some.Class', {
    VERSION    : 0.01

    has : { ... },
    methods : { ... }
})

Then before each release, you need to manually update the version information. That quickly becomes PITA. Thankfully, this task can easily automated, especially that Dist::Zilla already can increment the version, based on the information from git tags. So, if we’ll include a version placeholder in the sources:

Class('Some.Class', {
    /*VERSION,*/

    has : { ... },
    methods : { ... }
})

and the plugin to the “dist.ini”, which know how to find that placeholder and replace it with actual version:

[JSAN::PkgVersion]

then during each build dzil will perform all the routine work.

Conclusion

Setting up a proper quality control for your release process is very important. Currently I’m maintaining  ~30 distributions. Under “maintaining” I don’t mean I have that much github repos. I mean all of them have proper versions, tags, docs, test suites, changelogs etc. All of them are released on `npm`. I just can’t imagine how I would do that without Dist::Zilla.

See also

[JSAN] plugin docs and http://dzil.org/