{"id":73,"date":"2011-01-13T17:09:44","date_gmt":"2011-01-13T17:09:44","guid":{"rendered":"http:\/\/joose.it\/blog\/?p=73"},"modified":"2011-01-13T17:09:44","modified_gmt":"2011-01-13T17:09:44","slug":"distzilla-%e2%80%93-the-distributions-king","status":"publish","type":"post","link":"http:\/\/joose.it\/blog\/2011\/01\/13\/distzilla-%e2%80%93-the-distributions-king\/","title":{"rendered":"Dist::Zilla \u2013 the distributions king!"},"content":{"rendered":"

In this post I\u2019d like to present the building tools I\u2019m using for my projects<\/a>. Hopefully after it there will be more contributions :)<\/p>\n

I\u2019m 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<\/a> thats gradually changing).<\/p>\n

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 \u2013 in any language or any distribution platform you definitely want to tag the new release with version number. Then you probably want\u00a0 to commit the updates. Another example will be `Changes` file \u2013 before release it definitely makes sense to check whether it contains the entries for new version. Etc.<\/p>\n

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!<\/p>\n

Setup<\/h1>\n

Installation of the perl modules is usually scary for people without perl background. So you are welcome to the #joose<\/a> 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 \u2018git\u2019 installed.<\/p>\n

I found it much easier to use the recently appeared Miyagawa\u2019s \u201ccpan-minus\u201d tool. So, to install the cpanminus:<\/p>\n

> curl -L http:\/\/cpanmin.us | perl - --sudo App::cpanminus<\/pre>\n
then<\/p>\n
> cpanm Dist::Zilla::Plugin::JSAN --sudo<\/pre>\n
After installation, setup the Dist::Zilla in interactive mode (this is required only once):<\/p>\n
> dzil setup\r\nWhat's your name?...<\/pre>\n
When asked about the default license, here\u2019s the list of available identificators<\/a> (at the bottom and strip the leading \u201cSoftware::License::\u201d). The  information you provided will be used during creation of new  distributions.<\/p>\n
Starting a distribution<\/h1>\n
To start a new distribution:<\/p>\n
> dzil new -P JSAN -p joose Sample-Dist\r\n\r\n[DZ] making target dir \/home\/nickolay\/Playground\/dzil\/Sample-Dist\r\n[DZ] writing files to \/home\/nickolay\/Playground\/dzil\/Sample-Dist\r\n[Git::Init] Initializing a new git repository in \/home\/nickolay\/Playground\/dzil\/Sample-Dist\r\n[DZ] dist minted in .\/Sample-Dist><\/pre>\n
This command should create a barebone distribution like this<\/a>. It will also create a git repository and perform a famous \u201cinitial commit\u201d! :) See this page<\/a> to know how to customize the template.<\/p>\n
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).<\/p>\n
The distribution will also contain a rudimentary test suite, which you can run in NodeJS (assuming you have test-run<\/a> installed) with:<\/p>\n
> node t\/index.js<\/pre>\n
or, if you\u2019ve completed the 3.1 and 3.2 steps from this document<\/a>, in browsers. Put the distribution in some web-directory and point the browser to the URL like:<\/p>\n
http:\/\/localhost\/my_workspace\/Sample-Dist\/t\/index.htnml<\/pre>\n
dist.ini<\/h1>\n
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:<\/p>\n
; Auto-increment the version number, based on the tags information from git\r\n[Git::NextVersion]\r\nfirst_version\u00a0\u00a0 = 0.0.1\r\n\r\n; include the link to git repo and web page (if \"origin\" points to github)\r\n[GithubMeta]<\/pre>\n
For the details on the individual plugin, prepend  its name with \u201cDist::Zilla::Plugin\u201d and perform a CPAN search<\/a>.<\/p>\n
See the documentation<\/a> for the full details on the JSAN plugin, here I\u2019ll briefly describe some of the typical tasks.<\/p>\n
Building the distribution<\/h1>\n
\u2018build\u2019 command takes your sources as the input, process them  (add\/remove\/change some files) and generate the output (location can be  specified with \u2018in\u2019 option):<\/p>\n
> dzil build [--in \/target\/dir]<\/pre>\n
Various plugins participate in this phase. Typical example will be  [License] plugin, which adds a LICENSE file with the text of your  license.<\/p>\n
Releasing the distribution<\/h1>\n
\u2018release\u2019 command first build the distribution, then runs plugins which implements the \u201crelease\u201d phase. There is a [JSAN::NPM::Publish]<\/a> plugin, which can publish your dist in npm:<\/p>\n
> dzil release<\/pre>\n
Use case<\/h1>\n
For example, I\u2019d like to include the version information in the source files, like:<\/p>\n
\n
\n
Class('Some.Class', {\r\n  \u00a0 VERSION    : 0.01\r\n\r\n    has : { ... },\r\n   \u00a0methods : { ... }\r\n})<\/pre>\n<\/div>\n<\/div>\n
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\u2019ll include a  version placeholder in the sources:<\/p>\n
\n
\n
Class('Some.Class', {\r\n    \/*VERSION,*\/\r\n\r\n    has : { ... },\r\n    methods : { ... }\r\n})<\/pre>\n<\/div>\n<\/div>\n
and the plugin to the \u201cdist.ini\u201d, which know how to find that placeholder and replace it with actual version:<\/p>\n
[JSAN::PkgVersion]<\/p>\n
then during each build dzil will perform all the routine work.<\/p>\n
Conclusion<\/h1>\n
Setting up a proper quality control for your release process is very  important. Currently I\u2019m maintaining\u00a0 ~30 distributions. Under  \u201cmaintaining\u201d I don\u2019t 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\u2019t imagine how I would do that  without Dist::Zilla.<\/p>\n
See also<\/h1>\n
[JSAN] plugin docs<\/a> and http:\/\/dzil.org\/<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
In this post I\u2019d like to present the building tools I\u2019m using for my projects. Hopefully after it there will be more contributions :) I\u2019m 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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0},"categories":[4],"tags":[],"_links":{"self":[{"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/posts\/73"}],"collection":[{"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/comments?post=73"}],"version-history":[{"count":7,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/posts\/73\/revisions"}],"predecessor-version":[{"id":88,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/posts\/73\/revisions\/88"}],"wp:attachment":[{"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/media?parent=73"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/categories?post=73"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/joose.it\/blog\/wp-json\/wp\/v2\/tags?post=73"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}