/ 
Dist-Zilla-Plugin-Manifest-Write-0.006
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::Manifest::Write::ReadMe

NAME

Dist::Zilla::Plugin::Manifest::Write::ReadMe - Manifest::Write plugin readme

VERSION

Version 0.006, released on 2015-07-23 19:11 UTC.

WHAT?

Manifest::Write is a plugin for Dist::Zilla, a replacement for standard plugin Manifest. Manifest::Write writes annotated MANIFEST: each filename is followed by a comment, explaining origin of the file, whether it is part of software, meta information, or 3rd party file.

This is Manifest::Write readme. It covers general topics like getting source, building, installing, bug reporting and some others.

If you want to have annotated MANIFEST in your distribution, read the manual. If you are going to hack or extend Dist-Zilla-Plugin-Manifest-Write, read the module documentation.

WHY?

MANIFEST is a metainfo file, a part of every distribution. It is a plain list of files included into the distribution. Typical MANIFEST looks like:

Build.PL
COPYING
Changes
MANIFEST
META.yml
README
lib/Foo.pm
t/00-compile.t
xt/author/eol.t
xt/author/no-tabs.t

Format of manifest allows comments, but comments are rarely used.

As it noted before, manifest is a plain list of files. However, files included into a distribution differ:

  1. Some files are created by software author (in the example above, lib/Assa.pm could be such file). Some of these files may be processed by various filters (like PodWeaver).

  2. Some files contain distribution metainformation (META.yml and MANIFEST itself).

  3. Some files may be generated by a tool from third party templates (Dist-Zilla and its plugins can generate a lot of various files, in the example above all the tests could be generated, as well as Build.PL, COPYING, and even Changes).

Sometimes you may want (or have) to trace an origin of a file: whether this file created by author or automatically added, if the file was processed or added as-is. With a typical manifest you have to guess origin of each file, because distribution build tool, Dist-Zilla, throws this information away. Manifest::Write saves this information in comments:

Build.PL            # 3rd party file added by ModuleBuildTiny
COPYING             #       Foo file added by GatherFromManifest
Changes             #       Foo file added by GatherFromManifest
MANIFEST            #  metainfo file built by Manifest::Write
META.yml            #  metainfo file built by MetaYAML
README              #       Foo file added by GatherFromManifest
lib/Foo.pm          #       Foo file added by GatherFromManifest and modified by PkgVersion
t/00-compile.t      # 3rd party file added by Test::Compile
xt/author/eol.t     # 3rd party file added by Test::EOL
xt/author/no-tabs.t # 3rd party file added by Test::NoTabs

(In the example above "Foo" is name of manifested distribution.)

With such annotated manifest there is no need to guess, you just know.

NAMING

perl-Dist-Zilla-Plugin-Manifest-Write is official software name.

However, in Perl world prefix "perl-" is redundant and not used. For example, on meta::cpan this software is named as Dist-Zilla-Plugin-Manifest-Write. In the rest of the documentation shortened name Dist-Zilla-Plugin-Manifest-Write is used as synonym for full name perl-Dist-Zilla-Plugin-Manifest-Write. We are in the Perl world, aren't we?

You may notice that name may be spelled with dashes (Dist-Zilla-Plugin-Manifest-Write) or with double colons (Dist::Zilla::Plugin::Manifest::Write). Strictly speaking, there is difference: the first one is software name, while the second is name of Perl package, but often these names are interchangeable especially if software consists of single package.

FORMS

You may face Dist-Zilla-Plugin-Manifest-Write in source or distribution forms.

If you are going to have annotated MANIFEST in your distribution, you will likely be interested in using Dist-Zilla-Plugin-Manifest-Write distribution. If you are going to develop (or hack) the Dist-Zilla-Plugin-Manifest-Write itself, you will likely need the source, not distribution.

Since Perl is an interpreting language, modules in the distribution look like sources. Actually, they are Perl source files. But they are not actual sources, because they are built (preprocessed or generated) by Dist-Zilla.

How to distinguish source and distribution:

  • Source may contain Mercurial files and directories .hgignore, .hgtags, .hg/, while distribution should not.

  • Source should contain files dist.ini, weaver.ini, while distribution may not.

  • Source should not contain xt/ directory, while distribution should.

  • Name of source directory does not include version (e. g. Dist-Zilla-Plugin-Manifest-Write), while name of distribution does (e. g. Dist-Zilla-Plugin-Manifest-Write-0.007).

SOURCE

Dist-Zilla-Plugin-Manifest-Write source is in Mercurial repository hosted on fedorapeople.org. To clone the entire repository:

$ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Manifest-Write

Source Files

Dist-Zilla-Plugin-Manifest-Write source files usually include a comment near the top of the file:

This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.

Not all source files are included into distribution. Some source files are used at distribution build time only, and not required for installation.

DISTRIBUTION

Dist-Zilla-Plugin-Manifest-Write distributions are published on CPAN.

Generated Files

Distribution may contain files preprocessed or generated by Dist-Zilla and its plugins. Some generated files are made from Dist-Zilla-Plugin-Manifest-Write source, but some are generated from third-party templates. Files generated from third-party templates usually include a comment near the top of the file:

This file was generated with NAME

(where NAME is a name of the plugin generated the file). Such files are not part of Dist-Zilla-Plugin-Manifest-Write source, and Dist-Zilla-Plugin-Manifest-Write copyright and license are not applicable to such files.

INSTALLING

With cpanm

cpanm tool is (probably) the easiest way to install distribution. It automates downloading, building, testing, installing, and uninstalling.

To install the latest version from CPAN:

$ cpanm Dist::Zilla::Plugin::Manifest::Write

To install a specific version (e. g. 0.007) from CPAN:

$ cpanm Dist::Zilla::Plugin::Manifest::Write@0.007

To install locally available distribution (e. g. previously downloaded from CPAN or built from sources):

$ cpanm ./Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz

To uninstall the distribution:

$ cpanm -U Dist::Zilla::Plugin::Manifest::Write

Manually

To install distribution tarball manually (let us assume you have version 0.007 of the distribution):

$ tar xaf Dist-Zilla-Plugin-Manifest-Write-0.007.tar.gz
$ cd Dist-Zilla-Plugin-Manifest-Write-0.007
$ perl Build.PL
$ ./Build build
$ ./Build test
$ ./Build install

See Also

How to install CPAN modules

HACKING

For hacking, you will need Mercurial, Perl interpreter and Dist-Zilla (with some plugins), and likely cpanm to install missed parts.

Clone the repository first:

$ hg clone https://vandebugger.fedorapeople.org/hg/perl-Dist-Zilla-Plugin-Manifest-Write
$ cd perl-Dist-Zilla-Plugin-Manifest-Write

To build a distribution from the source, run:

$ dzil build

If required Dist-Zilla plugins are missed, dzil tool will warn you and show the command to install all the required plugins, e. g.:

Required plugin Dist::Zilla::Plugin::Test::EOL isn't installed.

Run 'dzil authordeps' to see a list of all required plugins.
You can pipe the list to your CPAN client to install or update them:

    dzil authordeps --missing | cpanm

To run the tests:

$ dzil test

To run all the tests, including release tests:

$ dzil test --release

To install the distribution:

$ dzil install

or

$ cpanm ./Dist-Zilla-Plugin-Manifest-Write-VERSION.tar.gz

where VERSION is a version of built distribution.

To clean the directory:

$ dzil clean

DOCUMENTATION

Online

The easiest way is browsing the documentation online at meta::cpan.

Locally Installed

If you have the distribution installed, use perldoc tool to browse locally installed documentation:

$ perldoc Dist::Zilla::Plugin::Manifest::Write::ReadMe
$ perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
$ perldoc Dist::Zilla::Plugin::Manifest::Write

Built from Source

Build Dist-Zilla-Plugin-Manifest-Write first (see "HACKING"), then:

$ cd Dist-Zilla-Plugin-Manifest-Write-VERSION
$ perldoc Dist::Zilla::Plugin::Manifest::Write::ReadMe
$ perldoc Dist::Zilla::Plugin::Manifest::Write::Manual
$ perldoc Dist::Zilla::Plugin::Manifest::Write

where VERSION is a version of built distribution.

FEEDBACK

CPAN Request Tracker

The quickest way to report a bug in Dist-Zilla-Plugin-Manifest-Write is by sending email to bug-Dist-Zilla-Plugin-Manifest-Write [at] rt.cpan.org.

CPAN request tracker can be used via web interface also:

Browse bugs

Browsing bugs does not require authentication.

Report bugs

You need to be a CPAN author, have a BitCard account, or OpenID in order to report bugs via the web interface.

(On 2015-04-27 I have logged in successfully with my LiveJournal OpenID, but my Google OpenID did not work for CPAN. I did not check other OpenID providers.)

Send Email to Author

As a last resort, send email to author: Van de Bugger <van.de.bugger@gmail.com>. Please start message subject with "perl-Dist-Zilla-Plugin-Manifest-Write:".

GLOSSARY

CPAN

Comprehensive Perl Archive Network, a large collection of Perl software and documentation. See cpan.org, What is CPAN?.

Distribution

Tarball, containing Perl modules and accompanying files (documentation, metainfo, tests). Usually distributions are uploaded to CPAN, and can be installed with dedicated tools (cpan, cpanm, and others).

Module

Perl library file, usually with .pm suffix. Usually contains one package. See perlmod.

Package

Perl language construct. See package and perlmod.

SEE ALSO

Dist::Zilla
Dist::Zilla::Plugin::Manifest

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

Copyright © 2015 Van de Bugger

This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.

perl-Dist-Zilla-Plugin-Manifest-Write is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

perl-Dist-Zilla-Plugin-Manifest-Write is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Plugin-Manifest-Write. If not, see <http://www.gnu.org/licenses/>.