Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Dist::Zilla::Tutorial(User Contributed Perl DocumentatDist::Zilla::Tutorial(3)

NAME
       Dist::Zilla::Tutorial - how to use this "Dist::Zilla" thing

VERSION
       version 6.017

SYNOPSIS
       BEFORE YOU GET STARTED:	Maybe you should be looking at the web-based
       tutorial	instead.  It's more complete.
       <http://dzil.org/tutorial/start.html>

       Dist::Zilla builds distributions	to be uploaded to the CPAN.  That
       means that the first thing you'll need is some code.

       Once you've got that, you'll need to configure Dist::Zilla.  Here's a
       simple dist.ini:

	 name	 = Carbon-Dating
	 version = 0.003
	 author	 = Alan	Smithee	<asmithee@example.org>
	 license = Perl_5
	 copyright_holder = Alan Smithee

	 [@Basic]

	 [Prereqs]
	 App::Cmd	   = 0.013
	 Number::Nary	   = 0
	 Sub::Exporter	   = 0.981

       The topmost section configures Dist::Zilla itself.  Here	are some of
       the entries it expects:

	 name	  - (required) the name	of the dist being built
	 version  - (required) the version of the dist
	 abstract - (required) a short description of the dist
	 author	  - (optional) the dist	author (you may	have multiple entries for this)
	 license  - (required) the dist	license; must be a Software::License::*	name

	 copyright_holder - (required) the entity holding copyright on the dist

       Some of the required values above may actually be provided by means
       other than the top-level	section	of the config.	For example,
       VersionProvider plugins can set the version, and	a line like this in
       the "main module" of the	dist will set the abstract:

	 # ABSTRACT: a totally cool way	to do totally great stuff

       The main	modules	is the module that shares the same name	as the dist,
       in general.

       Named sections load plugins, with the following rules:

       If a section name begins	with an	equals sign ("="), the rest of the
       section name is left intact and not expanded.  If the section name
       begins with an at sign ("@"), it	is prepended with
       "Dist::Zilla::PluginBundle::".  Otherwise, it is	prepended with
       "Dist::Zilla::Plugin::".

       The values inside a section are given as	configuration to the plugin.
       Consult each plugin's documentation for more information.

       The "Basic" bundle, seen	above, builds a	fairly normal distribution.
       It rewrites tests from ./xt, adds some information to POD, and builds a
       Makefile.PL.  For more information, you can look	at the docs for	@Basic
       and see the plugins it includes.

BUILDING YOUR DIST
       Maybe we're getting ahead of ourselves, here.  Configuring a bunch of
       plugins won't do	you a lot of good unless you know how to use them to
       build your dist.

       Dist::Zilla ships with a	command	called dzil that will get installed by
       default.	 While it can be extended to offer more	commands, there	are
       two really useful ones:

	 $ dzil	build

       The "build" command will	build the distribution.	 Say you're using the
       configuration in	the SYNOPSIS above.  You'll end	up with	a file called
       Carbon-Dating-0.004.tar.gz.  As long as you've done everything right,
       it will be suitable for uploading to the	CPAN.

       Of course, you should really test it out	first.	You can	test the dist
       you'd be	building by running another dzil command:

	 $ dzil	test

       This will build a new copy of your distribution and run its tests, so
       you'll know whether the dist that "build" would build is	worth
       releasing!

HOW BUILDS GET BUILT
       This is really more of a	sketchy	overview than a	spec.

       First, all the plugins that perform the BeforeBuild perform their
       "before_build" tasks.

       The build root (where the dist is being built) is made.

       The FileGatherers gather	and inject files into the distribution,	then
       the FilePruners remove some of them.

       All the FileMungers get a chance	to muck	about with each	file, possibly
       changing	its name, content, or installability.

       Now that	the distribution is basically set up, it needs an install
       tool, like a Makefile.PL.  All the InstallTool-performing plugins are
       used to do whatever is needed to	make the dist installable.

       Everything is just about	done.  The files are all written out to	disk
       and the AfterBuild plugins do their thing.

RELEASING YOUR DIST
       By running "dzil	release", you'll test your distribution, build a
       tarball of it, and upload it to the CPAN.  Plugins are able to do
       things like check your version control system to	make sure you're
       releasing a new version and that	you tag	the version you've just
       uploaded.  It can also update your Changelog file, too, making sure
       that you	don't need to know what	your next version number will be
       before releasing.

       The final CPAN release process is implemented by	the UploadToCPAN
       plugin. However you can replace it by your own to match your own
       (company?) process.

SEE ALSO
       dzil

AUTHOR
       Ricardo SIGNES dh <rjbs@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020 by Ricardo SIGNES.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2020-11-03	      Dist::Zilla::Tutorial(3)

NAME | VERSION | SYNOPSIS | BUILDING YOUR DIST | HOW BUILDS GET BUILT | RELEASING YOUR DIST | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dist::Zilla::Tutorial&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help