CPAN::...Config(3pm)

✨ CPAN::...Config 💅 (that's the CPAN::Reporter::Config page, bestie)

okay so this is the manpage for CPAN::Reporter::Config — the config file options for CPAN::Reporter. no cap, it's basically the settings menu for your test reports. let's get into it 🫶

💖 VERSION

version 1.2020 — yes that's the whole vibe, periodt.

🌸 SYNOPSIS

From the CPAN shell:

cpan> o conf init test_report

🦋 DESCRIPTION

Default options for CPAN::Reporter get read from a configuration file called .cpanreporter/config.ini in your home directory. (On Win32 platforms, that directory lives in your Documents directory instead.) You can also point at a different config directory or file with environment variables if you want — your call, main character.

The config file is in ini format, and the option name and value are separated by an = sign, like:

email_from = "John Doe" <johndoe@nowhere.org>
edit_report = no

Interactive configuration of your email address and the common action prompts can be re-run any time you want from the CPAN shell:

cpan> o conf init test_report

If a config file doesn't exist yet, it gets created the first time you do interactive configuration. And every later interactive config run will also include any advanced options you've added manually to the config file — it keeps them, it doesn't ghost them. 👑

---

🎀 INTERACTIVE CONFIGURATION OPTIONS

💌 Email Address (required)

email_from = <email address>

CPAN::Reporter requires you to provide an email address, and it gets used in the header of the report. it's literally required, bestie, no skipping.

The address you give should be in a valid format, e.g.:

email_from = user@domain
email_from = John Doe <user@domain>
email_from = "John Q. Public" <user@domain>

🚀 Transport (required)

transport = <transport class> [transport args]

This sets the transport mechanism that gets passed to the transport() method of Test::Reporter. Normally CPAN::Reporter uses 'Metabase' as the transport class (i.e. Test::Reporter::Transport::Metabase) and hands over a default set of transport arguments. slay.

Metabase transport arguments are two space-separated key/value pairs:

• "uri" — URI for the Metabase API. Defaults to "https://metabase.cpantesters.org/api/v1/"
• "id_file" — path to the user's Metabase profile file. Defaults to "metabase_id.json". (Assumed to be in the ".cpanreporter" directory).

Before sending reports, you gotta have a valid profile file at the path you specified. For Metabase transport, CPAN::Reporter will automatically rewrite a relative "id_file" path as an absolute path located in the ".cpanreporter" directory.

If the profile file you specified doesn't exist, CPAN::Reporter will offer to run metabase-profile to create it. so helpful of it 💖

For other transport types, go read the documentation that comes with your choice of Test::Reporter::Transport subclass for the proper way to set the "transport" configuration option.

🎯 Action Prompts

Several steps in generating a test report are optional. Configuration options control whether an action is taken automatically or whether CPAN::Reporter should prompt you for the action to take. The action can be different for each report grade — for example, you might wanna customize which grades you manually review before sending. very picky, we love that.

Most users should just accept the default settings until they've got some experience as CPAN Testers. fr fr.

Valid actions, and what they mean:

• "yes" — automatic yes
• "no" — automatic no
• "ask/no" or just "ask" — ask each time, but default to no
• "ask/yes" — ask each time, but default to yes

For "ask" prompts, the default gets used if you press return immediately at the prompt, or if the "PERL_MM_USE_DEFAULT" environment variable is set to a true value.

Action prompt options take one or more space-separated grade:action pairs, and they're processed left to right:

edit_report = fail:ask/yes pass:no

An action by itself is taken as a default to be used for any grade that doesn't have a grade-specific action. You can also set a default action by using the word "default" in place of a grade:

edit_report = ask/no
edit_report = default:ask/no

A grade by itself is taken to have the action "yes" for that grade:

edit_report = default:no fail

Multiple grades can be specified together by separating them with a slash:

edit_report = pass:no fail/na/unknown:ask/yes

The action prompt options included in interactive configuration are:

• "edit_report = <grade:action> ..." — edit the test report before sending? (default:ask/no pass/na:no)
• "send_report = <grade:action> ..." — should test reports be sent at all? (default:ask/yes pass/na:yes)

Heads up: if "send_report" is set to "no", CPAN::Reporter will still go through the motions of preparing a report — but it'll discard it instead of sending it. it does the work and then throws it away 😭

A better way to disable CPAN::Reporter temporarily is with the CPAN option "test_report":

cpan> o conf test_report 0

📮 Mail Server (DEPRECATED)

CPAN::Reporter used to send mail directly to perl.org mail servers. The "smtp_server" option is now deprecated and will be ignored if it exists. rip to that option, it's giving legacy 💀

---

🔥 ADVANCED CONFIGURATION OPTIONS

These extra options are only necessary in special cases — like if the default editor can't be found, or if reports shouldn't be sent in certain situations, or for automated testing, and so on. niche but iconic.

• "command_timeout" — if greater than zero and the CPAN config "inactivity_timeout" is not set, then any commands executed by CPAN::Reporter will be halted after this many seconds; useful for unattended smoke testing to stop after some amount of time; generally, this should be large — 900 seconds or more — as some distributions' tests take quite a long time to run. On MSWin32, Win32::Job is needed, and trying to kill a process may actually deadlock in some situations — so use at your own risk.
• "editor = <editor>" — editor to use to edit the test report; if not set, Test::Reporter will use environment variables "VISUAL", "EDITOR" or "EDIT" (in that order) to find an editor
• "retry_submission" — if greater than zero, CPAN::Reporter will try to resend the report after a few seconds in case the first attempt fails.
• "send_duplicates = <grade:action> ..." — should duplicates of previous reports be sent, regardless of "send_report"? (default:no)
• "send_PL_report = <grade:action> ..." — if defined, used in place of "send_report" during the PL phase
• "send_make_report = <grade:action> ..." — if defined, used in place of "send_report" during the make phase
• "send_test_report = <grade:action> ..." — if defined, used in place of "send_report" during the test phase
• "send_skipfile = <skipfile>" — filename containing regular expressions (one per line) to match against the distribution ID (e.g. 'AUTHOR/Dist-Name-0.01.tar.gz'); the report will not be sent if a match is found; non-absolute filename must be in the .cpanreporter config directory;

If these options are manually added to the configuration file, they will be included (and preserved) in subsequent interactive configuration. it remembers your custom stuff, so sweet 🌸

🧚 Skipfile regular expressions

Skip files are expected to have one regular expression per line and will be matched against the distribution ID, composed of the author's CPAN ID and the distribution tarball name.

DAGOLDEN/CPAN-Reporter-1.00.tar.gz

Lines that begin with a sharp (#) are considered comments and will not be matched. All regular expressions will be matched case insensitive and will not be anchored unless you provide one.

As the format of a distribution ID is AUTHOR/tarball, anchoring at the start of the line with a caret (^) will match the author and with a slash (/) will match the distribution.

# any distributions by JOHNDOE
^JOHNDOE
# any distributions starting with Win32
/Win32
# a particular very specific distribution
^JOHNDOE/Foo-Bar-3.14

---

🐛 CONFIGURATION OPTIONS FOR DEBUGGING

These options are useful for debugging only:

• "debug = <boolean>" — turns debugging on/off

---

🌈 ENVIRONMENT

The following environment variables may be set to alter the default locations for CPAN::Reporter files:

• "PERL_CPAN_REPORTER_DIR" — if set, this directory is used in place of the default ".cpanreporter" directory; this will affect not only the location of the default "config.ini", but also the location of the CPAN::Reporter::History database and any other files that live in that directory
• "PERL_CPAN_REPORTER_CONFIG" — if set, this file is used in place of the default "config.ini" file; it may be in any directory, regardless of the choice of configuration directory

---

👀 SEE ALSO

• CPAN::Reporter
• CPAN::Reporter::History
• CPAN::Reporter::FAQ

---

✍️ AUTHOR

David Golden <dagolden@cpan.org>

📜 COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page, bestie 🫶 this was perl v5.40.0, dated 2024-08-17 — go forth and send those test reports, you absolute icon 💅✨