NAME

perl_dist_setup – Simple, opinionated tool to set up a Perl distribution directory.

SYNOPSIS

  mkdir project_name
  cd project_name
  git init
  perl_dist_setup
  $(EDITOR) dist_setup.conf
  perl_dist_setup

DESCRIPTION

Overview

This tool has no command line options as of now. You should run it from the root of your project directory, which should be a Git repository. The first time the tool is run (or if the dist_setup.conf file does not exist) the tool will create a template configuration file.

You should then edit this file, following the explanatory comments that it contains. Once the config file is edited, you can run perl_dist_setup again and it will set up the distribution.

Most of the files created by perl_dist_setup have guard comments at the top and bottom of the file. You can customize these files by adding more content after the bottom comment. That content will be kept when the tool is run again to update the files (for example after you update to a newer version of perl_dist_setup).

Some files don’t have these comments (because they are in a format that don’t support them), these files can’t be modified.

You can find below in the "FILES" section a description of all the generated files and how they can be customized.

Features

Make targets

The Makefile generated by the tool has the following custom targets:

- alltest

Runs all the tests of the distribution, including the extended tests. This works by setting the EXTENDED_TESTING environment variable, as specified by the Lancaster Consensus.

- cover

Generate a code coverage report from your test suite.

- critic

Run the code through Perl Critic using the Test2::Tools::PerlCritic module and display the policy violations.

- distupload

Test and then upload the distribution to CPAN. You will be queried on the command line for your PAUSE username and password, unless a ~/.pause file exists following the syntax documented in the cpan-upload manual provides these values.

- exe

Converts each of the scripts specified by exe_files in the dist_setup.conf file into a self-extracting executable using pp from PAR::Packer. This is quite experimental and lack many configuration options that might be needed for advanced usages. In particular this will not work if the programs relies on a shared folder (as specified by the data_dir option). The programs are written in the build directory.

- pod2html

Converts the POD documentation embedded in all the .pm files under lib/ as well as in all the scripts specified by exe_files in the dist_setup.conf file into HTML. The output files are written in the pod2html directory in the project folder.

- rawcritic

Execute your code through perlcritic directly, without the violation grouping done by the Test2::Tools::PerlCritic module as when running make critic.

- spelling

Run aspell interactively to spell-check the distribution. For each misspelled word, you can either fix their spelling, or add them to a local .aspelldict dictionary file, which should be stored in your source version control system.

- tidy

Run the code through perltidy. It is recommended to commit your code to your source version control system first, if you want to be able to use it to show you the diff of the formatting.

FILES

Below is a description of the files created by the tool and how they can be customized.

Changes

The Changes file is special because it is generated only once by the program (if it does not yet exist) and is never touched after that. So you can modify it however you want.

The CPAN::Changes::Spec page has the description of the required format for this file.

cpanfile

This file list all the dependencies of the project. The template file has the dependencies required due to the setup created by perl_dist_setup but you can add any other required dependencies at the end of the file.

The cpanfile page has the description of the required format for this file.

Note that the 001-cpanfile.t test, created by perl_dist_setup, tries to catch missing dependencies from the cpanfile file.

LICENSE

For now the license file is not modifiable and uses an MIT License. If you need support for other licenses, please file a feature-request to the project.

Makefile.PL

This file uses ExtUtils::MakeMaker to create the Makefile for the distribution. The main way to extend it is to add more content to put in the output Makefile. This can be achieved by writing a postamble method at the end of the file, like so:

  sub postamble {
    return <<"MAKE_FRAGMENT";
  my_target: dependencies
  \trecipe
  MAKE_FRAGMENT
  }

MANIFEST.SKIP

This file lists regex matching files that should not be embedded in the distribution tarball that is uploaded to CPAN. You can add more regex at the end.

.gitignore

This file lists regex matching files that should not be stored under the Git version control. You can add more regex at the end.

.perlcriticrc

This file contains the default rules that will be applied by perlcritic. You can override these rules at the end of the file (adding or removing policies and overriding the configuration of other policies).

The default policy is pretty strict. An easy way to make it be less strict is to increase the minimum severity above its default value of 2. For example by adding the following line at the end of the file:

  severity =  2

.perltidyrc

This file has the default formatting rules for perltidy. You can override them at the end of the file.

In the future, there might be different theme supported by perl_dist_setup to provide other styles. If you already have a .perltidyrc file with significantly different style from ours, feel free to send a feature request for this distribution, for inclusion of your style file.

t/

This directory contains various standard tests for the distribution. While it is technically possible to add more content at the end of the file, this is not supported for now. Instead you should just add your own test files.

- 000-load.t

A test that the main module of the distribution can be loaded and correctly returns a true value.

- 001-cpanfile.t

A test that the syntax of the cpanfile is valid and that it contains all the modules that are used by the distribution (not that some of them may be missed). This is based on the Test::CPANfile module.

- 001-perlcritic.t

Checks that all the files validate the Perl Critic policies listed in the .perlcriticrc file. In particular, one of these policies also tests that the files format are coherent with the .perltidyrc Perl Tidy configuration.

You can run make critic to execute this test manually and make tidy to automatically format the code.

- 001-podsyntax.t

Checks that the syntax of the POD embedded in all the Perl sources is correct.

- 001-spelling.t

Spellcheck your code. You can run aspell interactively over your code with make spelling to either fix your spelling and/or build a .aspelldict file containing the words that are not otherwise known to the aspell dictionary.

.devcontainer/

This directory contains the necessary setup to use a GitHub Dev Container development environment (also known as codespace). This directory is created only if the github.use_devcontainer option is set in the dist_setup.conf file.

It contains the following 3 files:

- devcontainer.json

This file can’t be modified and point to the other two files.

- Dockerfile

This file create the initial setup of the container. You can customize it by adding more commands at the end of the file, typically more RUN commands to execute actions at the creation of the container.

By default, the file install some binaries needed by the distribution (like aspell, cpanm, and cpan-upload) as well as some tools commonly needed development tools (perlbrew).

Note that, when this file is run, the environment does not yet have access to the content of your distribution.

- update_content.sh

This script is run after the content of the container is modified (that is, once your code is available). It installs all the dependencies of your distribution.

If the PAUSE_USERNAME and PAUSE_PASSWORD environment variables exist, t also creates a ~/.pause file that can be used by the cpan-upload tool to automatically upload your distribution to CPAN. These environment variables are typically created by setting the username and password as GitHub secrets shared with your repository.

This file can be customized by adding more command lines at the bottom.

.github/

This directory is only created if the github.use_ci option is set in the dist_setup.conf file. It contains a GitHub workflow that will run CI tests for the distribution.

While technically the workflow file can be customized by adding more content at its end, there is probably no scenario to do that.

cpanm Dist::Setup

perl -MCPAN -e shell
install Dist::Setup