docker-perl-tester

This repo is used to build Perl Docker images with various pre-installed bits:

• the aspell and aspell-en packages
• cpanminus
• App::cpm
  • latest on Perl 5.24 and newer, 0.998003 on Perl 5.22 and older
• Devel::Cover
• various testing modules
• Dist::Zilla with some common plugins (for Perl >= 5.20)

At this points images are refreshed daily, which could change overtime if it becomes an issue. This should guarantee you to test uptodate CPAN stack.

Note: if one dependency fails to install, this should not impact you as the image would not be published on failures.

List of Perl modules

See also the cpanfile in this repo for an up to date list of available modules.

Available on all Perl Versions

• Code::TidyAll::Plugin::SortLines::Naturally
• Code::TidyAll::Plugin::UniqueLines
• Devel::Cover
• Devel::Cover::Report::Codecov
• Devel::Cover::Report::Coveralls
• ExtUtils::MakeMaker
• File::Temp
• List::MoreUtils
• Module::Build
• Pod::Coverage::TrustPod
• Test2::Bundle::Extended
• Test2::Plugin::NoWarnings
• Test2::Suite
• Test2::Tools::Explain
• Test::Builder
• Test::CPAN::Meta
• Test::Deep
• Test::Differences
• Test::EOL
• Test::Fatal
• Test::MinimumVersion
• Test::MockModule
• Test::Mojibake
• Test::More
• Test::Needs
• Test::Notabs
• Test::Pod
• Test::Pod::Coverage
• Test::Portability::Files
• Test::RequiresInternet
• Test::Simple
• Test::Spelling
• Test::Synopsis
• Test::Version
• Test::Warnings

Only on Perl 5.10 and later

• Code::TidyAll::Plugin::Test::Vars
• Test::Vars

Only on Perl 5.12 and later

• Pod::Readme

Only on Perl 5.20 and later

• Dist::Zilla & friends
• Dist::Zilla::PluginBundle::Author::ETHER

Using Docker Images for your projects

The images can be found at https://hub.docker.com/repository/docker/perldocker/perl-tester/

The following tags are available from the repository perldocker/perl-tester

devel
5.40
5.38
5.36
5.34
5.32
5.30
5.28
5.26
5.24
5.22
5.20
5.18
5.16
5.14
5.12
5.10

devel build

Note that the devel build was added to test on the current Perl development version. (example: 5.37.8, ) This is tracking the last Perl devel version released.

OS flavor

Images are built for both Debian buster and Debian bookworm. The versions without an explicit Debian version are buster.

Continuous Integrations

Using the images with GitHub Workflow

Here is a sample workflow for Linux running on all Perl version 5.10 to 5.40 You can save the content in .github/workflow/linux.yml.

Note: this example is using cpm to install the dependencies from a cpanfile. You can comment this line or use Dist::Zilla instead for supported Perl versions.

name: linux

on:
  push:
    branches:
      - '*'
    tags-ignore:
      - '*'
  pull_request:

jobs:
  perl:
    env:
      # some plugins still needs this to run their tests...
      PERL_USE_UNSAFE_INC: 0
      AUTHOR_TESTING: 1
      AUTOMATED_TESTING: 1
      RELEASE_TESTING: 1

    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        perl-version:
          - '5.40'
          - '5.38'
          - '5.36'
          - '5.34'
          - '5.32'
          - '5.30'
          - '5.28'
          - '5.26'
          - '5.24'
          - '5.22'
          - '5.20'
          - '5.18'
          - '5.16'
          - '5.14'
          - '5.12'
          - '5.10'

    container:
      image: perldocker/perl-tester:${{ matrix.perl-version }}

    steps:
      - uses: actions/checkout@v4
      - name: perl -V
        run: perl -V
      - name: Install Dependencies
        run: cpm install -g --no-test --show-build-log-on-failure --cpanfile cpanfile
      - name: Makefile.PL
        run: perl Makefile.PL
      - name: make test
        run: make test

Using Helper scripts

The scripts from perl-actions/ci-perl-tester-helpers are available in the path of each container. These scripts can build and test dists for you in various scenarios. See https://github.com/Perl-Critic/PPI/blob/master/.github/workflows/dzil-build-and-test.yml for an example of how to use the helpers to build and tests a Perl distribution.

More Examples

You can find more details on how to setup GitHub workflow to smoke Perl projects by reading skaji/perl-github-actions-sample GitHub repository.

Using GitHub actions

You can also consider using GitHub actions:

• perl-actions/install-with-cpanm
• perl-actions/install-with-cpm

Building Docker images

When pushing to GitHub, it's using a GitHub action .github/workflows/publish-to-docker.yml to automagically build and publish the docker images for you.

If you consider cloning this repository, you would have to set in your GitHub repository the following secret variables, with some example values.

DOCKER_REPO=perldocker/perl-tester
DOCKER_USERNAME=username
DOCKER_GITHUB_TOKEN=a-token-or-password

Developer Notes:

The main branch is named main and not master.

In order to build the image locally you can run the following command:

docker build . -t tempo --build-arg BASE=5.28-buster --build-arg CPANOUTDATED=1

This will create and image called tempo based on perl 5.28.

Then you can start a container based on this image using the following command:

docker run -it -w /opt --rm -v$(pwd):/opt tempo  bash

In the container you can try to install a new module using cpm:

cpm install -v -g --show-build-log-on-failure Dancer2

You can try it on different versions of Perl.

Once you are happy with the results, add name of the module to cpanfile.

What are the moving parts here?

When the build fails we need to know what changed that caused the failure. To make it easier here is a list of things that might have changed.

• The change we make to this repository. This is the only visible change.
• The content (or the availability) of the BASE perl distributions.
• The GitHub Action runner.
• The GitHub Actions. We use tags for the various actions and they might point to a different commit.
• The CPAN modules. By default we install the most recent release of everything.

Author

@oalders initiated the project and @atoomic tried to give it more public visibility volunteers/ideas are welcome to improve the project.