1Dist::Milla(3)        User Contributed Perl Documentation       Dist::Milla(3)
2
3
4

NAME

6       Dist::Milla - Distribution builder, Opinionated but Unobtrusive
7

SYNOPSIS

9         > milla new Dist-Name
10         > cd Dist-Name
11
12         > milla build
13         > milla release
14

DESCRIPTION

16       Milla is a Dist::Zilla profile. It is a collection of Dist::Zilla
17       plugin bundle, minting profile and a command line wrapper. It is
18       designed around the "Convention over Configuration" philosophy
19       (Opinionated), and by default doesn't rewrite module files nor requires
20       you to change your workflow at all (Unobtrusive).
21
22       Experienced CPAN authors who know how to write CPAN distributions can
23       keep writing the code like before, but can remove lots of cruft, then
24       replace Module::Install and ShipIt with Dist::Zilla and Milla profile
25       for authoring, while you don't need to add anything other than a shiny
26       new cpanfile (optional), and a simple "dist.ini" saying:
27
28         [@Milla]
29

CONVENTIONS

31       Milla is opinionated. Milla has a slightly bold assumption and
32       convention like the followings, which are almost compatible to the
33       sister project Minilla.
34
35       Your module is Pure Perl, and files are stored in "lib"
36       Your executable file is in "script" directory, if any
37       Your dist sharedirs must be in "share" directory, if any
38       Your module is maintained with Git and "git ls-files" matches with what
39       you will release
40       Your module has a static list of prerequisites that can be described in
41       "cpanfile"
42       Your module has a Changes file
43
44       If you have a module that doesn't work with these conventions, no
45       worries. Because Milla is just a Dist::Zilla profile, you can just
46       upgrade to Dist::Zilla and enable/disable plugins that match with what
47       you need.
48

GETTING STARTED

50         # First time only
51         > cpanm Dist::Milla
52         > milla setup
53
54         # Make a new distribution
55         > milla new Dist-Name
56         > cd Dist-Name
57
58         # git is already initialized and files are added for you
59         > git commit -m "initial commit"
60
61         # Hack your code!
62         > $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile
63
64         # (Optional; First time only) Make your build: This will get some boilerplate for git
65         > milla build
66         > git add Build.PL META.json README.md && git commit -m "git stuff"
67
68         # Done? Test and release it!
69         > $EDITOR Changes
70         > milla build
71         > milla release
72
73       It's that easy.
74
75       You already have distributions with Module::Install, Module::Build or
76       ShipIt? Migrating is also trivial. See "MIGRATING" in
77       Dist::Milla::Tutorial for more details.
78

WHY

80   WHY Dist::Zilla
81       A lot of you might have heard of Dist::Zilla (dzil). If you already use
82       it and love it, then you can stop reading this, or even using this
83       module at all.
84
85       If you heard of dzil and think it's overkill or doesn't work for your
86       module, this is why Milla exists.
87
88       If you have tried dzil ages ago and thought it was slow, or couldn't
89       find how to configure it to do what you want it to do, Milla will be
90       just for you.
91
92       First, let me tell you what's the reason to like Dist::Zilla.
93
94       Dist::Zilla doesn't do the job of installing of your module. So you can
95       focus on the authoring side of things with dzil, while letting
96       MakeMaker or Module::Build(::Tiny) to do the installation side of
97       things. I like this design. David Golden also has written an excellent
98       blog post <http://www.dagolden.com/index.php/752/why-im-using-
99       distzilla/> explaining more details about what this means.
100
101       That said, I myself have avoided switching to Dist::Zilla for a long
102       time. I actually tried a couple of times, but ended up giving up
103       switching to it. You can google for "Hate Dist::Zilla" and will be able
104       to find rants by similarly frustrated developers.
105
106       In my observation, typical problems/dislikes around Dist::Zilla can be
107       categorized into one of the following thoughts.
108
109       Dist::Zilla is slow
110       Dist::Zilla has too many dependencies
111       Dist::Zilla is obtrusive
112       Dist::Zilla makes contributing difficult
113       Dist::Zilla isn't just worth it
114
115       Let's see how we can address them by using Milla, one at a time.
116
117       Dist::Zilla is slow
118           Moose, the object system Dist::Zilla uses under the hood, has been
119           improved a lot for the past few years, and your development machine
120           has got a much better CPU and SSD as well. For me personally, with
121           all of Milla plugins loaded, "milla nop" takes roughly 1.5 second,
122           which I would say is acceptable since I only need to run it at a
123           distribution creation time and release time. More on that later.
124
125       Dist::Zilla has too many dependencies
126           This is true, and Milla doesn't solve that problem, because it adds
127           more dependencies on top of Dist::Zilla.
128
129           For a quickstart with Milla-like distribution building environment
130           without installing "half of CPAN", see the sister project Minilla.
131
132       Dist::Zilla is obtrusive
133           This was my main motivation for not switching to Dist::Zilla - the
134           thought that using Dist::Zilla would require me to change my
135           workflow.
136
137           The truth is, Dist::Zilla doesn't require you to change your
138           workflow by itself. But a lot of popular plugins and workflow
139           suggests doing so, by using stuff like PodWeaver, which requires
140           you to switch to Dist::Zilla for everything and then generate the
141           boilerplate, or munge your modules from there.
142
143           I don't care about the real boilerplate such as "MANIFEST",
144           "META.json" or "LICENSE" auto-generated, but don't personally like
145           the idea of generating documentation or munging code.
146
147           I want to edit and maintain all the code and docs myself, and let
148           the authoring tool figure out metadata from there, not the other
149           way round.
150
151           With Milla, you don't need to change your workflow, and it won't
152           rewrite your ".pm" files at all. Like Module::Install's "all_from",
153           most of the metadata is figured out from your module and git,
154           automatically.
155
156       Dist::Zilla makes contributing difficult
157           This is true for most Dist::Zilla based distributions.
158
159           Milla copies the plain "META.json" and "Build.PL" into the git
160           repository you automatically bump on every release. And there won't
161           be any code munging process required for the release (except
162           bumping $VERSION automatically).
163
164           This means that the git repository can be installed as a standard
165           CPAN distribution even without Dist::Zilla installed, and
166           collaborators can just hack your modules, run the tests with "prove
167           -l t" and send a pull request just like a normal module without
168           using dzil at all.
169
170           It's just a releaser who has to install and use Milla.
171
172       Dist::Zilla isn't just worth it
173           Dist::Zilla has a lot of plugins to search from, and it's so easy
174           for you to spend a few days until you settle with the configuration
175           you need. That is exactly why Milla exists.
176
177           If you have tried Dist::Zilla before, you might have shared the
178           same experience with me, where the default Basic profile doesn't do
179           much. And when you started wondering or asking what other authors
180           are doing, you would be overwhelmed by the amount of plugins and
181           complexity introduced by the clever workflow.
182
183           Milla provides a sensible set of defaults that will work for 90% of
184           people, and you don't need to waste time configuring your
185           PluginBundle or searching for the plugin you need.
186
187   WHY NOT Module::Install
188       I loved Module::Install. I love how it automatically figures out what I
189       want to do with a single "all_from" line. I liked the cleverness of its
190       bundling itself into "inc". But I know many collaborators hated it
191       because you have no idea what plugins have to be installed when you use
192       some funky plugins, and your users are puzzled when they try to install
193       from the git repository because it says "Can't locate
194       inc/Module/Install.pm". This problem can be fixed, but I was not
195       interested in doing so.
196

FAQ

198       So you basically wrote a simple PluginBundle and some wrapper, and give
199       that a name?
200
201       Yes. That's the whole point. Think Dist::Zilla as a framework (because
202       it is!) and Milla is a (thin) application built on top of that.
203
204       That's so egoistic for you! Why not just
205       Dist::Zilla::PluginBundle::Author::MIYAGAWA?
206
207       Part of the reason might be my egoism. But think about it - if I
208       switched to Dist::Zilla and recommend everyone to use, I have to say,
209       "Hey, the way I use dzil is kind of cool. You can get that by using my
210       @MIYAGAWA bundle".
211
212       Wouldn't that be more egoistic than giving it a different name?
213
214       I wrote my own PSGI implementation, and didn't give it a name
215       PSGI::MIYAGAWA - it's called Plack. I wrote a kick-ass, lightweight
216       CPAN installer, and didn't give it a name CPAN::Installer::MIYAGAWA -
217       it's called cpanm.
218
219       Because I think this can be recommended for many people, and want to
220       make it better by incorporating contributions, I gave it a different
221       name other than my own personal name bundle.
222
223       Dist::Zilla feels overkill. If you don't munge code/docs, what's the
224       point?
225
226       I agree that it is still overkill. But as of this writing, there's no
227       software other than Dist::Zilla that can correctly create a CPAN style
228       distribution other than ExtUtils::MakeMaker and Module::Build, and I
229       think they're wrong tools for authoring distributions.
230
231       Check out Minilla if you think Dist::Zilla is overkill and want a
232       lightweight replacement that achieves the same goal but does less.
233
234       Milla?
235
236       As stated above, I've been loving the cleverness of Module::Install
237       (MI), but felt its limitation. Milla is an attempt to put
238       Module::Install's smartness into Dist::Zilla (without the "inc" mess).
239
240       M::I + Zilla = Milla.
241
242       Milla should also remind you of Milla Jovovich, but I couldn't make up
243       any correlation about it, besides Resident Evil is such a great
244       videogame and movie.
245

AUTHOR

247       Tatsuhiko Miyagawa <miyagawa@bulknews.net>
248

CONTRIBUTORS

250       Ricardo SIGNES wrote Dist::Zilla.
251
252       David Golden wrote Dist::Zilla::PluginBundle::DAGOLDEN, which I cargo
253       culted a lot of configuration from, for Milla bundle.
254
255       Tokuhiro Matsuno has beaten me to writing Minilla, which resulted in me
256       going the Dist::Zilla plugin route. Minilla is a sister project, and we
257       try to make them compatible to each other and make it as trivial as
258       possible to switch from/to each other.
259
261       Copyright 2013- Tatsuhiko Miyagawa
262

LICENSE

264       This library is free software; you can redistribute it and/or modify it
265       under the same terms as Perl itself.
266

SEE ALSO

268       Dist::Zilla, Minilla
269
270
271
272perl v5.32.0                      2020-07-28                    Dist::Milla(3)
Impressum