CPAN::...Smoker(3pm)

💖 CPAN::Reporter::Smoker(3pm) 💖

okay bestie, welcome to the perl manual page for CPAN::Reporter::Smoker — the turnkey CPAN Testers smoking situation. it lives in User Contributed Perl Documentation and it's about to be your whole personality for a bit. 🎀

---

✨ NAME ✨

CPAN::Reporter::Smoker — Turnkey CPAN Testers smoking. that's it, that's the name, she does exactly what she says on the tin. 💅

---

🌸 VERSION 🌸

version 0.30

---

🦋 SYNOPSIS 🦋

the whole vibe, in one line:

$ perl -MCPAN::Reporter::Smoker -e start

literally that's it. iconic.

---

🌈 DESCRIPTION 🌈

so. this is a rudimentary smoke tester for CPAN Testers, built on top of CPAN::Reporter. use at your own risk, bestie — i cannot stress that enough. it needs a recent version of CPAN::Reporter to run, so if yours is ancient, go update her first. 🫶

as of right now, CPAN::Reporter::Smoker needs zero independent configuration. like, none. instead it just borrows the config settings from CPAN.pm and CPAN::Reporter. lowkey genius, highkey convenient.

once you start it, it grabs a list of distributions from the configured CPAN mirror and starts testing them in reverse order of upload. and it will skip any distribution that CPAN::Reporter has already sent a report for. no duplicate effort in this house. 💀

features (or bugs, depending on your point of view, i don't make the rules):

• No configuration needed ✨
• Tests each distribution as a separate CPAN process — each distribution has prerequisites like build_requires satisfied from scratch 🔥
• Automatically checks for new distributions every twelve hours or as otherwise specified ⏰
• Continues until interrupted with CTRL-C 👑
• Checks CPAN.pm distroprefs to see if distributions should be skipped (before handing off to CPAN) 🧚

current limitations, because nobody's perfect:

• Does not attempt to retest distributions that had reports discarded because of prerequisites that could not be satisfied 😭
• Does not test trial version if there is no non-trial version 🙈

---

💀 WARNING -- smoke testing is risky 💀

okay so this is the part where i hold your hand. smoke testing will download and run programs that other people have uploaded to CPAN. and those programs could do anything to your system, including deleting everything on it. like, everything everything.

do not run CPAN::Reporter::Smoker unless you are prepared to take these risks. fr fr. no cap. this is not a drill. 🚨

---

🎀 USAGE 🎀

💅 start()

starts smoke testing using the defaults that are already sitting in CPAN::Config and CPAN::Reporter's .cpanreporter directory. it runs until all distributions are tested, or until the process is halted with CTRL-C or otherwise killed. slay.

start() supports several optional arguments, and yes we're going through every single one:

• clean_cache_after — number of distributions that will be tested before checking to see if the CPAN build cache needs to be cleaned up (not including any prerequisites tested). must be a positive integer. defaults to 100.
• list — if provided, this list of distributions will be tested instead of all of CPAN. may be a reference to an array of distribution names, or may be a filename containing one distribution name per line. distribution names must be of the form 'AUTHOR/Dist-Name-0.00.tar.gz'.
• restart_delay — number of seconds that must elapse before restarting smoke testing. this will reload indices to search for new distributions and restart testing from the most recent distribution. must be a positive integer; defaults to 43200 seconds (12 hours).
• skip_dev_versions — if true, unindexed distributions will not be tested. valid values are 0 or 1. defaults to 0.
• set_term_title — toggle for whether the terminal titlebar will be updated with the distribution being smoke tested and the starting time of the test. helps determine if a test is hung and which distribution might be responsible. valid values are 0 or 1. defaults to 1.
• status_file — during testing, the name of the distribution under test and a timestamp are written to this file. the file is removed after the test is complete. this helps identify a problem distribution if testing hangs or crashes the computer. if the argument includes a path, all directories to the file must exist. defaults to "smoker-status-$$.txt" in File::Spec->tmpdir.
• install — toggle for whether the distribution should be installed after successful testing. can be useful to avoid prerequisite re-building and growing PERL5LIB for the cost of disk space used for installed modules. valid values are 0 or 1. defaults to 0.
• reverse — toggle the order in which releases are tested. when set to 1, testing starts from the older release, not the most recent one (or the last distribution if --list is provided). valid values are 0 or 1. defaults to 0.
• random — toggle whether to randomize distribution test order. when set to 1, the list of releases is shuffled. valid values are 0 or 1. defaults to 0.
• force_trust — toggle whether to override CPAN's "trust_test_report_history" option. when set to 1, "trust_test_report_history" is set to 1. when set to 0, "trust_test_report_history" is left alone and whatever the user has configured for their CPAN client is used. valid values are 0 or 1. defaults to 0.
• reload_history_period — after this period in seconds, history of modules smoked will be reloaded when possible. default value 1800 seconds (30 minutes).

---

and that's part one, bestie — there's more coming, so don't go anywhere 💜

---

✨ HINTS ✨

okay bestie this is the part where i hold your hand through the tricky bits 💖 no gatekeeping here, we're doing this together.

🎀 Selection of distributions to test

so here's the tea: only the most recently uploaded developer and normal releases get tested. and a developer release only gets tested if it's newer than the regular release that PAUSE has indexed. that's the whole vibe check. 👑

fr fr, let's do an example. if Foo-Bar-0.01, Foo-Bar-0.02, Foo-Bar-0.03_01 and Foo-Bar-0.03_02 are all sitting on CPAN, then only Foo-Bar-0.02 and Foo-Bar-0.03_02 get tested — and in reverse order of when they were uploaded. and the second Foo-Bar-0.04 drops and gets indexed? Foo-Bar-0.03_02 is so done being tested. not me, not anymore. 💀

to dodge testing random script tarballs and other chaos, any developer distribution you include has to have a base distribution name that looks like a distribution tarball PAUSE already indexed. so if a distribution's very first upload to PAUSE is a developer release — like Baz-Bam-0.00_01.tar.gz — it will not be tested, because there's no indexed Baz-Bam hanging out in CPAN's 02packages.details.txt file. sorry babe, no index, no smoke test. 🙈

Unauthorized tarballs get treated exactly like developer releases: they'll be tested if they resemble an indexed distribution and are newer than the indexed tarball. we love equal treatment here.

Perl, parrot, kurila, Pugs and similar distributions will not be tested. the skip list comes from CPAN::Mini and matches like this, and yes you're getting it verbatim because i respect you:

     qr{(?:
           /(?:emb|syb|bio)?perl-\d
         | /(?:parrot|ponie|kurila|Perl6-Pugs)-\d
         | /perl-?5\.004
         | /perl_mlb\.zip
     )}xi,

Bundles and mod_perl distributions also don't get tested — even though mod_perl is highkey likely to be requested as a dependency by a ton of modules. 😭 which is why the next section exists: it shows you how to tell CPAN.pm not to test certain dependencies. keep scrolling bestie.

🦋 Skipping additional distributions

if certain distributions hang, crash, or are just generally causing drama, you can use CPAN's distroprefs system to disable them. if a distribution is disabled, it won't be built or tested. and if a distribution's dependency is disabled, a failing test just gets discarded. simple as. ✨

step one: configure a directory for your distroprefs files:

     $ cpan
     cpan> o conf init prefs_dir
     cpan> o conf commit

next, make sure either the YAML or YAML::Syck module is installed. (YAML::Syck is faster, iykyk.) then create a file inside that prefs_dir directory to hold your list of distributions to disable — call it disabled.yml, cute name, iconic file.

in that file you can drop blocks of YAML to disable distributions. the match criteria distribution is a regex that matches against the canonical name of a distribution, like AUTHOR/Foo-Bar-3.14.tar.gz.

here's a sample file showing you the syntax (pls don't actually use these ones though, they're just for the aesthetic):

     ---
     comment: "Tests take too long"
     match:
         distribution: "^DAGOLDEN/CPAN-Reporter-\d"
     disabled: 1
     ---
     comment: "Skip Win32 distributions"
     match:
         distribution: "/Win32"
     disabled: 1
     ---
     comment: "Skip distributions by Andy Lester"
     match:
         distribution: "^PETDANCE"
     disabled: 1

⚠️ heads up bestie: disabling distributions like this will also disable them for normal, non-smoke usage of CPAN.pm. it's not just a smoke-test thing, it's a forever thing. 🫶

one distribution i'd personally recommend either installing up front or else disabling with distroprefs is mod_perl — it's a common requirement for a bunch of Apache:: modules, but it does not (easily) build and test under automation. she's complicated. 💅

     ---
     comment: "Don't build mod_perl if required by some other module"
     match:
         distribution: "/mod_perl-\d"
     disabled: 1

distroprefs are way more powerful than this, jsyk — they can automate responses to prompts in distributions, set environment variables, specify additional dependencies and so on. read the docs for CPAN.pm for more, and go look in the distroprefs directory inside the CPAN distribution tarball for examples. there's a whole world in there. 🌈

🧚 Using a local CPAN::Mini mirror

since distributions have to be retrieved from a CPAN mirror, the smoker can cause heavy network load and will repetitively download common build prerequisites. it's a lot. it's giving bandwidth. 😭

an alternative is using CPAN::Mini to create a local CPAN mirror and point CPAN's urllist at it:

     $ cpan
     cpan> o conf urllist unshift file:///path/to/minicpan
     cpan> o conf commit

however — and this is the plot twist — CPAN::Reporter::Smoker needs the find-ls.gz file, which CPAN::Mini does not mirror by default. add it to a .minicpanrc file in your home directory to include it in your local CPAN mirror:

     also_mirror: indices/find-ls.gz

also note that CPAN::Mini does not mirror developer versions. so a live, network CPAN Mirror will be needed in the urllist to retrieve those. can't skip that step, sorry babe.

and another one: CPAN requires the LWP module to be installed to use a local CPAN mirror. noted. 📝

alternatively, you might experiment with the alpha-quality release of CPAN::Mini::Devel, which subclasses CPAN::Mini to retrieve developer distributions (and find-ls.gz) using the same logic as CPAN::Reporter::Smoker. experimental queen. 🧪

💜 Timing out hanging tests

CPAN::Reporter (since 1.08) supports a command_timeout configuration option. set this option in the CPAN::Reporter configuration file to time out tests that hang up or get stuck at a prompt. set it to a high value to avoid timing out lengthy tests that are still running — 1000 or more seconds is probably enough. she needs room to breathe. ⏳

⚠️ Warning — on Win32, terminating processes via the command_timeout is equivalent to SIGKILL and could cause system instability or later deadlocks. that's not a vibe. 💀

this option is still considered experimental.

🌸 Avoiding repetitive prerequisite testing

because CPAN::Reporter::Smoker satisfies all requirements from scratch, common dependencies (e.g. Class::Accessor) will be unpacked, built and tested repeatedly. like, over and over. groundhog day energy. 🙈

as of version 1.92_56, CPAN supports the trust_test_report_history config option. when it's set, CPAN will check the last test report for a distribution. if one is found, the results of that test are used instead of running tests again. so efficient. so slay. ✨

     $ cpan
     cpan> o conf init trust_test_report_history
     cpan> o conf commit

⭐ Avoiding repetitive prerequisite builds (EXPERIMENTAL)

CPAN has a build_dir_reuse config option. when it's set (and if a YAML module is installed and configured), CPAN will attempt to make build directories persistent. this has the potential to save substantial time and space during smoke testing. CPAN::Reporter::Smoker will recognize if this option is set and make adjustments to the test process to keep PERL5LIB from growing uncontrollably as the number of persistent directories increases. iconic behaviour honestly. 🎀

⚠️ NOTE: Support for build_dir_reuse is highly experimental. wait for at least CPAN version 1.92_62 before trying this option. do not come for me if it's unhinged. 😭

     $ cpan
     cpan> o conf init build_dir_reuse
     cpan> o conf commit

💖 Stopping early if a prerequisite fails

normally, CPAN.pm keeps testing a distribution even if a prerequisite fails to build or fails testing. some distributions may pass their tests even without a listed prerequisite, but most just fail (and CPAN::Reporter discards failures if prerequisites are not met). so, you know. shrug. 🤷

as of version 1.92_57, CPAN supports the halt_on_failure config option. when it's set, a prerequisite failure stops further processing. done. no more. ✋

     $ cpan
     cpan> o conf init halt_on_failure
     cpan> o conf commit

however — a disadvantage of halting early is that no DISCARD grade is recorded in the history. so the next time CPAN::Reporter::Smoker runs, the distribution will be tested again from scratch. 😭 it may be better to let all prerequisites finish so the distribution can fail its test and get flagged with DISCARD, so it'll be skipped in the future. sometimes patience is the move, bestie.

🫶 CPAN cache bloat

CPAN will use a lot of scratch space to download, build and test modules. use CPAN's built-in cache management configuration to let it purge the cache periodically if you don't want to do it manually. when configured, the cache will be purged on start and after a certain number of distributions have been tested, as determined by the clean_cache_after option for the start() function.

     $ cpan
     cpan> o conf init build_cache scan_cache
     cpan> o conf commit

🌈 CPAN verbosity

recent versions of CPAN are verbose by default, but they include some lesser-known configuration settings to minimize that for untarring distributions and for loading support modules. setting the verbosity for these to 'none' will minimize some of the clutter on your screen as distributions get tested. peace and quiet. finally. 🤫

     $ cpan
     cpan> o conf init /verbosity/
     cpan> o conf commit

🍓 Saving reports to files instead of sending directly

in some cases — like when smoke testing using a development or prerelease toolchain module like Test-Harness — it may be preferable to save reports to files in a directory for review before submitting them. to do this, manually set the transport option in your CPAN::Reporter config file to use the Test::Reporter::Transport::File transport:

     transport=File /path/to/directory

after you've reviewed them, send the saved reports using Test::Reporter:

     Test::Reporter->new()->read($filename)->send()

look at you, being all responsible and reviewing before sending. main character energy. 👑

---

🌟 ENVIRONMENT 🌟

while it's running, it automatically sets the following environment variables to true values:

• AUTOMATED_TESTING — signal that tests are being run by an automated smoke testing program (i.e. don't expect interactivity)
• PERL_MM_USE_DEFAULT — accept ExtUtils::MakeMaker prompt() defaults
• PERL_EXTUTILS_AUTOINSTALL — set to '--defaultdeps' for default dependencies

the following environment variables, if set, will modify the behavior of CPAN::Reporter::Smoker. generally, they're only required during the testing of CPAN::Reporter::Smoker itself. iykyk. 🔬

• PERL_CR_SMOKER_RUNONCE — if true, start() will exit after all distributions are tested instead of sleeping for the restart_delay and then continuing
• PERL_CR_SMOKER_SHORTCUT — if true, start() will process arguments (if any) but will return before starting smoke testing; used for testing argument handling by start()

---

🐛 BUGS 🐛

pls pls pls report any bugs or feature requests using the CPAN Request Tracker. bugs can be submitted through the web interface at <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Reporter-Smoker> 🫶

when you submit a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature. help me help you, bestie. 💖

---

👀 SEE ALSO 👀

• CPAN
• CPAN::Reporter
• CPAN::Testers
• CPAN::Mini
• CPAN::Mini::Devel

💖 SUPPORT 💖

🐛 Bugs / Feature Requests 🐛

Okay bestie, if you find a bug or you're lowkey craving a new feature, please report any bugs or feature requests through the issue tracker at https://github.com/cpan-testers/CPAN-Reporter-Smoker/issues. You will be notified automatically of any progress on your issue — like, the tracker will ping you when things move, no cap. 🫶

🦋 Source Code 🦋

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/cpan-testers/CPAN-Reporter-Smoker

git clone https://github.com/cpan-testers/CPAN-Reporter-Smoker.git

✨ AUTHOR ✨

David Golden <dagolden@cpan.org> — iconic behavior, honestly. 👑

🌈 CONTRIBUTORS 🌈

• Alexandr Ciornii <alexchorny@gmail.com>
• Breno G. de Oliveira <garu@cpan.org>
• Christian Walde <walde.christian@googlemail.com>
• gregor herrmann <gregoa@cpan.org>
• gregor herrmann <gregoa@debian.org>

👑 COPYRIGHT AND LICENSE 👑

This software is Copyright (c) 2024 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

This page was cooked with perl v5.38.2, dated 2024-01-20, and it's the CPAN::...Smoker(3pm) page — periodt. 💅✨