The files in a Perl module
This page describes the function of the various files and types of files you might find in a Perl module.
blib
(directory)
"Build library", the directory where the modules are compiled.
blib/arch
(directory)
The directory where binary components go, e.g. the output of compiling C files.
blib/lib
(directory)
The directory where modules are temporarily installed.
*.bs, *.bso
(type of file)
These are bootstrap files for DynaLoader, created when using XS files.
Build
(file)
Script to build the module. This is usually created from Build.PL.
Build.PL
(file)
Script to build the module using Module::Build.
*.c
(type of file)
This is a C program file. It may have been generated from an XS file (*.xs).
Changes, CHANGES, Changelog, ChangeLog, CHANGELOG
(file)
Record of changes made to the module. See CPAN::Changes::Spec.
const-c.inc
(file)
This file is to do with XS.
const-xs.inc
(file)
This file contains constants used by an XS file.
CONTRIBUTING
(file)
A file which explains how to contribute to the module.
cpanfile
(file)
See Carton.
CREDITS
(file)
A file which lists contributors.
dist.ini
(file)
This file contains instructions for Dist::Zilla.
eg, examples
(directory:)
This directory contains example scripts which demonstrate the use of the module.
inc
(directory)
The directory which contains installation modules for Module::Install and Devel::CheckLib.
INSTALL
(file)
Installation instructions.
lib
(directory)
Directory where the Perl modules usually go. For example the code for
a module Acme::Nonsense
will be in the file
lib/Acme/Nonsense.pm
LICENSE, Copying
(file)
The licence for the Perl module, e.g. GNU or Artistic.
Makefile
(file)
Instructions to "make" to build/test/install the module. This file is usually generated from Makefile.PL.
Makefile.old
(file)
This file is a backup of Makefile which is made when the command "make clean" is performed.
Makefile.PL
(file)
Script to build the module using ExtUtils::MakeMaker or Module::Install.
MANIFEST
(file)
This file is used when creating a distribution. It contains a list of
files to include in the distribution. Each file occupies one line of
the file. The command make dist
or ./Build
dist
in the top directory will put the files listed in MANIFEST
into the distribution tar file.
When using ExtUtils::MakeMaker, the manifest may be generated
with make manifest
.
MANIFEST.bak
(file)
This is a backup of MANIFEST which is created by
Makefile when make manifest
is run.
MANIFEST.SKIP
(file)
This is a list of regular expressions which match files not to include
in the distribution. This is used when automatically generating
MANIFEST using make manifest
.
Only the module author actually needs this file, but it's usually distributed with CPAN distributions.
META.json
(file)
A file which contains information about the module in JSON format, the same as META.yml.
META.yml
(file)
A file which contains information about the module in YAML format. This information is used to index the module in CPAN. The format of the file is explained in CPAN::Meta::Spec.
META.json contains the same information in the JSON format.
minil.toml
(file)
See Minilla.
MYMETA.json
(file)
Like MYMETA.yml, but in JSON.
MYMETA.yml
(file)
This is like META.yml, but it is created by the user at configuration time. See MYMETA.yml in the wild.
*-{number}.tar.gz
(type of file)
This is a compressed archive file which contains all the files of the distribution.
.pd
(type of file)
These files are related to the Perl Data Language (PDL).
perlcritic.rc
(file)
Instructions to Perl::Critic.
*.pm
(type of file)
Perl library files ("Perl modules"). These might be under the lib directory.
pm_to_blib
(file)
A file automatically generated for installing the modules. See Perl Module Mechanics - pm_to_blib.
*.pod
(type of file)
These are documentation files in Perl's "POD" (Plain Old Documentation) format.
ppport.h
(file)
This is a file used by XS modules to ensure a consistent interface with the various versions of Perl.
README, README.pod, README.md
(file)
File which you are supposed to read. Without an extension, it is in
plain text format. It may also be in the POD (.pod
) or
Markdown (.md
) formats.
script, bin
(directory)
Executable scripts to install into the system "bin" directory. This
directory is specified within Makefile.PL, so it may be called
anything the module author desires. Many authors call it
script
or bin
by convention.
share
(directory)
Files to share using File::ShareDir.
SIGNATURE
(file)
A list of MD5 hashes of the files in the MANIFEST, signed by GPG/PGP.
This is a security feature which contains information you can use to make sure the module has not been tampered with.
t
(directory)
Directory where test files are stored.
t/lib
(directory)
This is a directory to put modules for use in the distribution's tests, so that they won't be installed, and PAUSE won't include them in the CPAN Index.
t/*.t
(type of file)
Test files usually have the form "Something.t". They are Perl scripts but don't have a "shebang" or #!/usr/bin/perl line at the top.
These files are usually found in the t directory.
typemap
(file)
A file which maps C objects from an XS extension to forms which Perl understands.
weaver.ini
(file)
This configures Pod::Weaver, which is a module which generates POD documents from a template.
*.xs
(type of file)
Perl library files written in C ("extension").
xt
(directory)
This directory contains test scripts which are used by the module developers, but not by people who are only using the module.
What is this page?
I wrote this page because I couldn't find an equivalent list elsewhere on the web. This page is meant to answer the question "what does that file do?" about files in a Perl module. It's not meant to be a guide to what you should do when creating a Perl module, so there is no advice here on the rights and wrongs of using various kinds of files or installations.
Web links
-
Perl Module Mechanics & Related Phenomena by Steven W. McDougall
Readable information on Perl modules.
-
Perl Module Mechanics by Steven W. McDougall
The "Perl Module Mechanics" page seems quite similar in intent to this one.
-
What are the files in a CPAN distribution?
A list similar to this one.
-
A spotter's guide to CPAN
A catalogue of the different files and directories you might come across in CPAN distributions.