| 1 | package Dist::Zilla::Tutorial 6.040; | ||
| 2 | # ABSTRACT: how to use this "Dist::Zilla" thing | ||
| 3 | |||
| 4 | use Dist::Zilla::Pragmas; | ||
| 5 | |||
| 6 | use Carp (); | ||
| 7 | Carp::confess "you're not meant to use the tutorial, just read it!"; | ||
| 8 | 1; | ||
| 9 | |||
| 10 | #pod =head1 SYNOPSIS | ||
| 11 | #pod | ||
| 12 | #pod B<BEFORE YOU GET STARTED>: Maybe you should be looking at the web-based | ||
| 13 | #pod tutorial instead. It's more complete. L<https://dzil.org/tutorial/start.html> | ||
| 14 | #pod | ||
| 15 | #pod Dist::Zilla builds distributions to be uploaded to the CPAN. That means that | ||
| 16 | #pod the first thing you'll need is some code. | ||
| 17 | #pod | ||
| 18 | #pod Once you've got that, you'll need to configure Dist::Zilla. Here's a simple | ||
| 19 | #pod F<dist.ini>: | ||
| 20 | #pod | ||
| 21 | #pod name = Carbon-Dating | ||
| 22 | #pod version = 0.003 | ||
| 23 | #pod author = Alan Smithee <asmithee@example.org> | ||
| 24 | #pod license = Perl_5 | ||
| 25 | #pod copyright_holder = Alan Smithee | ||
| 26 | #pod | ||
| 27 | #pod [@Basic] | ||
| 28 | #pod ; options to @Basic could go here | ||
| 29 | #pod | ||
| 30 | #pod [Prereqs] | ||
| 31 | #pod App::Cmd = 0.013 | ||
| 32 | #pod Number::Nary = 0 | ||
| 33 | #pod Sub::Exporter = 0.981 | ||
| 34 | #pod | ||
| 35 | #pod It's a plain old L<INI file|https://en.wikipedia.org/wiki/INI_file>, following | ||
| 36 | #pod the L<grammar in Config::INI|https://metacpan.org/pod/Config::INI#GRAMMAR>. | ||
| 37 | #pod | ||
| 38 | #pod The topmost section configures Dist::Zilla itself. Here are some of the | ||
| 39 | #pod entries it expects: | ||
| 40 | #pod | ||
| 41 | #pod name - (required) the name of the dist being built | ||
| 42 | #pod version - (required) the version of the dist | ||
| 43 | #pod abstract - (required) a short description of the dist | ||
| 44 | #pod author - (optional) the dist author (you may have multiple entries for this) | ||
| 45 | #pod license - (required) the dist license; must be a Software::License::* name | ||
| 46 | #pod | ||
| 47 | #pod copyright_holder - (required) the entity holding copyright on the dist | ||
| 48 | #pod | ||
| 49 | #pod Some of the required values above may actually be provided by means other than | ||
| 50 | #pod the top-level section of the config. For example, | ||
| 51 | #pod L<VersionProvider|Dist::Zilla::Role::VersionProvider> plugins can | ||
| 52 | #pod set the version, and a line like this in the "main module" of the dist will set | ||
| 53 | #pod the abstract: | ||
| 54 | #pod | ||
| 55 | #pod # ABSTRACT: a totally cool way to do totally great stuff | ||
| 56 | #pod | ||
| 57 | #pod The main modules is the module that shares the same name as the dist, in | ||
| 58 | #pod general. | ||
| 59 | #pod | ||
| 60 | #pod Named sections load plugins, with the following rules: | ||
| 61 | #pod | ||
| 62 | #pod If a section name begins with an equals sign (C<=>), the rest of the section | ||
| 63 | #pod name is left intact and not expanded. If the section name begins with an at | ||
| 64 | #pod sign (C<@>), it is prepended with C<Dist::Zilla::PluginBundle::>. Otherwise, | ||
| 65 | #pod it is prepended with C<Dist::Zilla::Plugin::>. | ||
| 66 | #pod | ||
| 67 | #pod The values inside a section are given as configuration to the plugin. Consult | ||
| 68 | #pod each plugin's documentation for more information. | ||
| 69 | #pod | ||
| 70 | #pod The "Basic" bundle, seen above, builds a fairly normal distribution. It | ||
| 71 | #pod rewrites tests from F<./xt>, adds some information to POD, and builds a | ||
| 72 | #pod F<Makefile.PL>. For more information, you can look at the docs for | ||
| 73 | #pod L<@Basic|Dist::Zilla::PluginBundle::Basic> and see the plugins it includes. | ||
| 74 | #pod | ||
| 75 | #pod =head1 BUILDING YOUR DIST | ||
| 76 | #pod | ||
| 77 | #pod Maybe we're getting ahead of ourselves, here. Configuring a bunch of plugins | ||
| 78 | #pod won't do you a lot of good unless you know how to use them to build your dist. | ||
| 79 | #pod | ||
| 80 | #pod Dist::Zilla ships with a command called F<dzil> that will get installed by | ||
| 81 | #pod default. While it can be extended to offer more commands, there are two really | ||
| 82 | #pod useful ones: | ||
| 83 | #pod | ||
| 84 | #pod $ dzil build | ||
| 85 | #pod | ||
| 86 | #pod The C<build> command will build the distribution. Say you're using the | ||
| 87 | #pod configuration in the SYNOPSIS above. You'll end up with a file called | ||
| 88 | #pod F<Carbon-Dating-0.004.tar.gz>. As long as you've done everything right, it | ||
| 89 | #pod will be suitable for uploading to the CPAN. | ||
| 90 | #pod | ||
| 91 | #pod Of course, you should really test it out first. You can test the dist you'd be | ||
| 92 | #pod building by running another F<dzil> command: | ||
| 93 | #pod | ||
| 94 | #pod $ dzil test | ||
| 95 | #pod | ||
| 96 | #pod This will build a new copy of your distribution and run its tests, so you'll | ||
| 97 | #pod know whether the dist that C<build> would build is worth releasing! | ||
| 98 | #pod | ||
| 99 | #pod =head1 HOW BUILDS GET BUILT | ||
| 100 | #pod | ||
| 101 | #pod This is really more of a sketchy overview than a spec. | ||
| 102 | #pod | ||
| 103 | #pod First, all the plugins that perform the | ||
| 104 | #pod L<BeforeBuild|Dist::Zilla::Role::BeforeBuild> perform their C<before_build> | ||
| 105 | #pod tasks. | ||
| 106 | #pod | ||
| 107 | #pod The build root (where the dist is being built) is made. | ||
| 108 | #pod | ||
| 109 | #pod The L<FileGatherer|Dist::Zilla::Role::FileGatherer>s gather and inject files | ||
| 110 | #pod into the distribution, then the L<FilePruner|Dist::Zilla::Role::FilePruner>s | ||
| 111 | #pod remove some of them. | ||
| 112 | #pod | ||
| 113 | #pod All the L<FileMunger|Dist::Zilla::Role::FileMunger>s get a chance to muck about | ||
| 114 | #pod with each file, possibly changing its name, content, or installability. | ||
| 115 | #pod | ||
| 116 | #pod Now that the distribution is basically set up, it needs an install tool, like a | ||
| 117 | #pod F<Makefile.PL>. All the | ||
| 118 | #pod L<InstallTool|Dist::Zilla::Role::InstallTool>-performing plugins are used to | ||
| 119 | #pod do whatever is needed to make the dist installable. | ||
| 120 | #pod | ||
| 121 | #pod Everything is just about done. The files are all written out to disk and the | ||
| 122 | #pod L<AfterBuild|Dist::Zilla::Role::AfterBuild> plugins do their thing. | ||
| 123 | #pod | ||
| 124 | #pod =head1 RELEASING YOUR DIST | ||
| 125 | #pod | ||
| 126 | #pod By running C<dzil release>, you'll test your | ||
| 127 | #pod distribution, build a tarball of it, and upload it to the CPAN. Plugins are | ||
| 128 | #pod able to do things like check your version control system to make sure you're | ||
| 129 | #pod releasing a new version and that you tag the version you've just uploaded. It | ||
| 130 | #pod can also update your Changelog file, too, making sure that you don't need to | ||
| 131 | #pod know what your next version number will be before releasing. | ||
| 132 | #pod | ||
| 133 | #pod The final CPAN release process is implemented by the | ||
| 134 | #pod L<UploadToCPAN|Dist::Zilla::Plugin::UploadToCPAN> plugin. However you can | ||
| 135 | #pod replace it by your own to match your own (company?) process. | ||
| 136 | #pod | ||
| 137 | #pod =head1 SEE ALSO | ||
| 138 | #pod | ||
| 139 | #pod L<dzil> | ||
| 140 | #pod | ||
| 141 | #pod =cut | ||
| 142 | |||
| 143 | __END__ |