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


Copyright © Ben Bullock 2009-2023. All rights reserved. For comments, questions, and corrections, please email Ben Bullock (benkasminbullock@gmail.com) or use the discussion group at Google Groups. / Privacy / Disclaimer