Dist::...ompile(3pm)

📦
version 2.059 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

Dist::Zilla::Plugin::Test::Compile — bestie, it's the common tests that vibe-check the syntax of all ur modules, and it only ever needs core modules to do it. No extra deps, no drama. 👑

This lil cutie lives in the perl man pages — the User Contributed Perl Documentation section, to be exact (yes, 3pm, iykyk).

✨ VERSION ✨

version 2.059 🎀

🌸 SYNOPSIS 🌸

In ur dist.ini, bestie:

[Test::Compile]
skip      = Test$
fake_home = 1
needs_display = 1
fail_on_warning = author
bail_out_on_fail = 1
switch = -M-warnings=numeric    ; like "no warnings 'numeric'

like. that's it. that's the whole setup. 💅

🦋 DESCRIPTION 🦋

Okay so listen. This is a Dist::Zilla plugin that runs at the gather files stage, and what it does is hand u a test file — configurable, defaults to t/00-compile.t — for free. Periodt.

That test goes and finds every single module and script in ur distribution, and tries to compile them one by one. Yes, individually. Which means it's a lil slower than just loading them all at once, but bestie, it catches more errors that way. Tradeoff accepted. 🔥

The generated test is guaranteed to only depend on modules that are available in core. Most of the options only need perl 5.6.2; the "bail_out_on_fail" option needs the version of Test::More that shipped with perl 5.12 — but the test itself still runs on perl 5.6. iconic behaviour honestly.

This plugin accepts the following options:

🎀 CONFIGURATION OPTIONS 🎀

💫 "filename"

The name of the generated file. Defaults to t/00-compile.t.

💫 "phase"

The phase u register prerequisites for. Defaults to "test". Set it to a false value and prerequisite registration just… stops. Disabled. Gone. 🙈

💫 "skip"

A regex to skip the compile test for modules that match it. The match runs against the module name (Foo::Bar), not the file path (lib/Foo/Bar.pm). U can repeat this option to stack up multiple regexes. Slay.

💫 "file"

A filename to also test, on top of any files found earlier. It gets tested as a module if it ends with .pm or .PM, and as a script otherwise. Module filenames should be relative to lib; everything else should be relative to the base of the repository. Repeatable, so u can add as many extra files as ur heart desires. 🫶

💫 "fake_home"

A boolean for whether to fake $ENV{HOME}. Why would u want that? Because if ur module unilaterally creates stuff in the user's home directory… bestie. 💀 Some cpantesters will smoke test ur distribution with a read-only home directory, so faking it may genuinely be needed. Defaults to false.

💫 "needs_display"

A boolean for whether to skip the compile test on non-Win32 systems when $ENV{DISPLAY} isn't set. Defaults to false.

💫 "fail_on_warning"

A string that says when to add a test for warnings during the compilation checks. Possible values are:

  • "none" — do not test for warnings
  • "author" — test for warnings only when AUTHOR_TESTING is set (default, and recommended 👑)
  • "all" — always test for warnings (not recommended, because this can prevent installation of modules when upstream dependencies exhibit warnings in a new Perl release 😭)

💫 "bail_out_on_fail"

A boolean for whether the test will BAIL_OUT of all subsequent tests when it hits compilation failures. Defaults to false.

💫 "module_finder"

The name of a FileFinder for finding modules to check. Default value is ":InstallModules"; u can use this option more than once. .pod files are always skipped.

Other predefined finders are listed in "default_finders" in Dist::Zilla::Role::FileFinderUser. And u can define ur own with the [FileFinder::ByName] and [FileFinder::Filter] plugins. main character energy, fr.

💫 "script_finder"

Just like "module_finder", but for finding scripts. The default value is ":PerlExecFiles" (when available; otherwise ":ExecFiles") — also peep Dist::Zilla::Plugin::ExecDir to make sure these files are properly marked as executables for the installer. 💅

💫 "xt_mode"

When true, the default "filename" becomes xt/author/00-compile.t and the default "dependency" phase becomes "develop".

💫 "switch"

Use this to pass a command-line switch (e.g. "-d:Confess", "-M-warnings=numeric") to the command that tests the module or script. Can be used more than once. See perlrun for more on constructing these switches. ✨

🌈 RUNTIME ENVIRONMENT OPTIONS 🌈

If the environment variable $PERL_COMPILE_TEST_DEBUG is set to a true option when the test is run, the command used to test each file gets printed as a "diag". little peek behind the curtain, we love to see it 🔍

⭐ SEE ALSO ⭐

  • Test::NeedsDisplay
  • Test::Script

💜 GIVING THANKS 💜

If u found this module useful, pls show ur appreciation by dropping a +1 in MetaCPAN at https://metacpan.org/dist/Dist-Zilla-Plugin-Test-Compile and a star in GitHub at https://github.com/karenetheridge/Dist-Zilla-Plugin-Test-Compile. it's giving gratitude, it's giving community 🫶

🧚 SUPPORT 🧚

Bugs may be submitted through the RT bug tracker at https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Test-Compile (or by email to bug-Dist-Zilla-Plugin-Test-Compile@rt.cpan.org).

There's also a mailing list for users of this distribution, at http://dzil.org/#mailing-list.

And there's an irc channel for users of this distribution too — "#distzilla" on "irc.perl.org" at irc://irc.perl.org/#distzilla. come hang out 💬

👑 AUTHORS 👑

  • Jérôme Quelin <jquelin@gmail.com>
  • Karen Etheridge <ether@cpan.org>

🌟 CONTRIBUTORS 🌟

  • Ahmad M. Zawawi <ahmad.zawawi@gmail.com>
  • Olivier Mengué <dolmen@cpan.org>
  • Kent Fredric <kentnl@cpan.org>
  • David Golden <dagolden@cpan.org>
  • Graham Knop <haarg@haarg.org>
  • Jesse Luehrs <doy@tozt.net>
  • Randy Stauner <rwstauner@cpan.org>
  • Harley Pig <harleypig@gmail.com>
  • Chris Weyl <cweyl@alumni.drew.edu>
  • fayland <fayland@gmail.com>
  • Marcel Gruenauer <hanekomu@gmail.com>
  • Peter Shangov <pshangov@yahoo.com>
  • Ricardo SIGNES <rjbs@cpan.org>

(the whole squad showed up, we love a collaborative effort 🌈)

This software is copyright (c) 2009 by Jérôme Quelin.

This is free software; u can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

and that's the whole page bestie, no cap. perl v5.40.1, dated 2025-12-21 — mwah 💅✨
📦 where this page comes from