CPAN::FirstTime(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 CPAN::FirstTime — the manual page, but make it make sense 💖

okay bestie, welcome to CPAN::FirstTime(3perl), straight out of the Perl Programmers Reference Guide. this is the lil' helper that holds your hand while you set up your CPAN config for the very first time 🫶

✨ NAME ✨

CPAN::FirstTime — utility for CPAN::Config file initialization 💅

🦋 SYNOPSIS 🦋

CPAN::FirstTime::init()

🌸 DESCRIPTION 🌸

so the init routine just... asks you a few questions 🎀 and then writes a CPAN/Config.pm or CPAN/MyConfig.pm file for you — whichever one it's currently using, no cap.

and below, literally every single question and explanation about the config variables is collected for you. we're not skipping a single one, periodt. 👑

🍓 allow_installing_module_downgrades

your CPAN shell can be a lil' nosy 👀 — it can watch the blib/ directories that get built up before make test runs, to figure out whether the current distribution is gonna end up overwriting your modules with decreasing module version numbers. and if it catches a downgrade, it can let the build of that distro fail.

so: do you wanna allow installing distros with decreasing module versions compared to what you already have installed? your options are yes, no, ask/yes, or ask/no. 💀

🌈 allow_installing_outdated_dists

same nosy energy, different vibe ✨ — the CPAN shell can watch those blib/ directories (built up before make test) to figure out whether the current distribution contains modules that are indexed with a distro that has a higher distro-version number than the current one. and then it can let the build fail when it wouldn't represent the most up-to-date version of the distro.

ngl bestie, note this: choosing anything but yes for this option means you'll need CPAN::DistnameInfo installed for it to actually take effect. 🚨

so: do you wanna allow installing distros that are not indexed as the highest distro-version for all contained modules? (yes, no, ask/yes, ask/no)?

💅 auto_commit

so normally CPAN.pm keeps config variables in memory, and any changes need to be saved with a separate o conf commit command to make them permanent between sessions. but if you set auto_commit to true, then changes to a config variable are always automatically committed to disk. iconic, honestly.

always commit changes to config variables to disk? 💾

🎀 build_cache

CPAN.pm can limit the size of the disk area where it keeps the build directories plus all the intermediate files.

so... cache size for build directory (in MB)? 📦

🦋 build_dir

directory where the build process takes place? 📂

✨ build_dir_reuse

okay so until version 1.88, CPAN.pm never trusted the contents of the build_dir directory between sessions. but since 1.88_58, CPAN.pm has a YAML-based mechanism that makes it possible to share the contents of the build_dir/ directory between different sessions — as long as it's the same version of perl. people who like to test things for several days before installing are gonna be obsessed with this feature, because it saves sooo much time. ⏰

if you say yes to the question below, CPAN will try to store enough info about the build process so it can pick up in future sessions at the exact same state of affairs it left a previous session in. main character energy fr fr.

store and re-use state information about distributions between CPAN.pm sessions? 🌟

💜 build_requires_install_policy

when a module declares another one as a 'build_requires' prerequisite, that means the other module is only needed for building or testing the module — it doesn't need to be installed permanently. in that case you might still wanna install that other module anyway 🥰, or just keep it in the 'build_dir' directory so it's only available temporarily. installing saves time on future installations but makes the perl installation bigger.

you can choose if you wanna always install (yes), never install (no), or always be asked. and if you pick the asking route, you can set the default answer for the question to yes (ask/yes) or no (ask/no).

policy on installing 'build_requires' modules (yes, no, ask/yes, ask/no)? 🤔

🧚 cache_metadata

to considerably speed up the initial CPAN shell startup, it's possible to use Storable to create a cache of metadata. if Storable isn't available, the normal index mechanism will be used instead. slay.

note bestie: this mechanism is not used when use_sqlite is on and SQLite is running. 🚫

cache metadata (yes/no)? 🗂️

🔥 check_sigs

CPAN packages can be digitally signed by authors ✍️ and thus verified with the security that strong cryptography provides. the exact mechanism is defined in the Module::Signature module. while this is generally considered a good thing, it's not always convenient for the end user to install modules that are signed incorrectly, or where the author's key isn't available, or where some prerequisite for Module::Signature has a bug, and so on. 🙈

with the check_sigs parameter you can turn signature checking on and off. the default is off for now, because the whole tool chain for this functionality isn't yet considered mature by some people. the author of CPAN.pm would recommend setting it to true most of the time, and only turning it off if it turns out to be annoying.

also note: if you don't have Module::Signature installed, no signature checks will be performed at all. 💀

always try to check and verify signatures if a SIGNATURE file is in the package and Module::Signature is installed (yes/no)?

🌸 cleanup_after_install

if you're the type of user who installs modules and never looks back, you can free up disk space quickly by letting CPAN.pm clean up each build directory immediately after a successful install. 🧹

remove build directory after a successful install? (yes/no)?

🌈 colorize_output

when you have Term::ANSIColor installed, you can turn on colorized output to get some visual differences between normal CPAN.pm output, warnings, debugging output, and the output of the modules being installed. set your favorite colors after some experimenting with the Term::ANSIColor module. 💖

please note that on Windows platforms, colorized output also requires the Win32::Console::ANSI module. 🪟

do you wanna turn on colored output? 🎨

💅 colorize_print

color for normal output? 🌟

🎀 colorize_warn

color for warnings? ⚠️

🦋 colorize_debug

color for debugging messages? 🐛

✨ commandnumber_in_prompt

the prompt of the cpan shell can contain the current command number (for easier tracking of your session) or just be a plain string.

do you want the command number in the prompt (yes/no)? 🔢

💜 connect_to_internet_ok

if you've never defined your own urllist in your configuration, then CPAN.pm is gonna be hesitant to use the built-in default sites for downloading. it'll ask you once per session whether a connection to the internet is OK, and only if you say yes will it try to connect. but to avoid this question, you can just choose your favorite download sites once and get away with it. or, if you have no favorite download sites, just answer yes to the question below. 🫶

if no urllist has been chosen yet, would you prefer CPAN.pm to connect to the built-in default sites without asking? (yes/no)? 🌐

🧚 ftp_passive

shall we always set the FTP_PASSIVE environment variable when dealing with ftp download? (yes/no)? 📥

🔥 ftpstats_period

statistics about downloads are truncated by size and period simultaneously, jsyk.

how many days shall we keep statistics about downloads? 📅

🌸 ftpstats_size

statistics about downloads are truncated by size and period simultaneously. setting this to zero or negative disables download statistics entirely.

how many items shall we keep in the statistics about downloads? 📊

🌈 getcwd

CPAN.pm changes the current working directory a lot, so it needs to determine its own current working directory. by default it uses Cwd::cwd, but if that doesn't work on your system for some reason, you can configure alternatives according to this table:

cwd         Cwd::cwd
getcwd      Cwd::getcwd
fastcwd     Cwd::fastcwd
getdcwd     Cwd::getdcwd
backtickcwd external command cwd

preferred method for determining the current working directory? 📍

💅 halt_on_failure

normally, CPAN.pm keeps processing the full list of targets and dependencies, even if one of them fails. but you can specify that CPAN should halt after the first failure instead. 🛑

(note that optional recommended or suggested modules that fail will not cause a halt. 🫶)

do you want to halt on failure (yes/no)?

🎀 histfile

if you have one of the readline packages installed (Term::ReadLine::Perl, Term::ReadLine::Gnu, possibly others), the interactive CPAN shell will have history support. the next two questions deal with the filename of the history file and its size. and if you don't wanna set this variable, just hit SPACE ENTER to the question below. 💫

file to save your history? 📜

🦋 histsize

number of lines to save? 🔢

✨ inactivity_timeout

sometimes you may wanna just leave the processes run by CPAN alone without caring about them. because Makefile.PL or Build.PL sometimes contains a question you're expected to answer, you can set a timer that will kill a 'perl Makefile.PL' process after the specified time in seconds. ⏱️

if you set this value to 0, these processes will wait forever. this is the default and recommended setting. 💖

timeout for inactivity during {Makefile,Build}.PL? ⏳

💜 index_expire

the CPAN indexes are usually rebuilt once or twice per hour, but the typical CPAN mirror only mirrors once or twice per day. depending on the quality of your mirror and how badly you wanna be on the bleeding edge, you might wanna set the value below to more or less than one day (which is the default). it determines after how many days CPAN.pm downloads new indexes. 🗓️

let the index expire after how many days?

🌸 inhibit_startup_message

when the CPAN shell is started, it normally displays a greeting message that contains the running version and the status of readline support. 👋

do you want to turn this message off? 🤐

🌈 keep_source_where

unless you're accessing the CPAN on your filesystem via a file: URL, CPAN.pm needs to keep the source files it downloads somewhere. please supply a directory where the downloaded files are to be kept. 📁

download target directory?

💅 load_module_verbosity

when CPAN.pm loads a module it needs for some optional feature, it usually reports the module name and version. choose 'v' to get this message, 'none' to suppress it. 🤫

verbosity level for loading modules (none or v)?

🎀 makepl_arg

every Makefile.PL is run by perl in a separate process. likewise, we run 'make' and 'make install' in separate processes. if you have any parameters (e.g. PREFIX, UNINST or the like) that you wanna pass to the calls, please specify them here. 📝

if you don't understand this question, just press ENTER. 🫶

typical frequently used settings:

PREFIX=~/perl    # non-root users (please see manual for more hints)

…and the prompt it hits you with is literally this: Parameters for the 'perl Makefile.PL' command? 🫶

  • make_arg — the flags you wanna hand to the make command. The classic go-to people type here is:
-j3              # dual processor system (on GNU make)

And then it's all Your choice: ✨

  • make_install_arg — flags for the make install command. The popular pick is:
UNINST=1         # to always uninstall potentially conflicting files
                 # (but do NOT use with local::lib or INSTALL_BASE)

Your choice: 💅

  • make_install_make_command — okay so do you wanna use a different make command just for make install? People who are cautious (read: smart) usually go for one of:
su root -c make

or

sudo make

or

/path1/to/sudo -u admin_account /path2/to/make

or some vibe like that. Your choice: 🎀

  • mbuildpl_arg — heads up bestie, a Build.PL is run by perl in its own separate process. Same deal: we run ./Build and ./Build install in separate processes too. So if you've got parameters you wanna pass into those calls, put them here, okay?

The typical frequently-used setting is:

--install_base /home/xxx             # different installation directory

Parameters for the 'perl Build.PL' command? 🌸

  • mbuild_arg — parameters for the ./Build command? A setting might be:
--extra_linker_flags -L/usr/foo/lib  # non-standard library location

Your choice: 🦋

  • mbuild_install_arg — parameters for ./Build install? The typical frequently-used setting is:
--uninst 1       # uninstall conflicting files
                 # (but do NOT use with local::lib or INSTALL_BASE)

Your choice: 💖

  • mbuild_install_build_command — you want a different command for ./Build install? The sudo girlies probably prefer:
su root -c ./Build

or

sudo ./Build

or

/path1/to/sudo -u admin_account ./Build

or some such. Your choice: 👑

  • pager — so what's your fave pager program? It literally just asks: What is your favorite pager program? 🙈
  • prefer_installer — okay so picture this: you've got Module::Build installed, and a module ships both a Makefile.PL and a Build.PL. Which one wins? 👀

The two main standard installer modules are: the old-and-well-established ExtUtils::MakeMaker (nicknamed EUMM) which works with the Makefile.PL. And the next-gen installer Module::Build (MB) which works with the Build.PL (and honestly it often ships a Makefile.PL too). If a module comes with only one of the two, we just use that one, no drama. But if both show up, a decision has to be made between EUMM and MB. There's also a whole discussion about the right default at http://rt.cpan.org/Ticket/Display.html?id=29235 if you wanna fall down that rabbit hole.

Or, third option: you can pick RAND, which makes it a random call every time (regular CPAN testers will enjoy this one, it's giving chaos 🎲).

So: In case you can choose between running a Makefile.PL or a Build.PL, which installer would you prefer (EUMM or MB or RAND)?

  • prefs_dir — so CPAN.pm can store customized build environments based on regular expressions that match distribution names. These are YAML files where the default options for CPAN.pm and the environment can be overridden — and you can even stash dialog sequences in there that an Expect.pm object can run later. The CPAN.pm distribution ships with some prefab YAML files covering sample distributions, and you can use them as blueprints for your own prefs. Go peek at the distroprefs/ directory of the CPAN.pm distribution for a quick-start into the prefs system. 🧚

The question is: Directory where to store default options/environment/dialogs for building modules that need some customization?

  • prerequisites_policy — the CPAN module can clock when a module you're trying to build has prerequisites. When that happens it can either build them for you automatically (follow), ask you for a confirmation (ask), or just fully ignore them (ignore). Heads up: picking follow also sets PERL_AUTOINSTALL and PERL_EXTUTILS_AUTOINSTALL for "--defaultdeps" — but only if they're not already set. 👀

Please set your policy to one of the three values.

Policy on building prerequisites (follow, ask or ignore)?

  • pushy_https — a Boolean, and it defaults to true. When it's true, the cpan shell downloads stuff from the CPAN over https://cpan.org/. If it can't do https for some reason (missing modules, missing programs), it'll fall back to http://cpan.org/ — and whenever it does that fallback, it'll throw a warning at you. Also, if this option is true, the urllist option gets ignored. So lowkey: if you want to work with local mirrors via your own configured list of URLs, you're gonna have to answer no below. 💀

Do you want to turn the pushy_https behaviour on?

  • randomize_urllist — CPAN.pm can sprinkle in some randomness when picking hosts for downloads out of the ones configured in the urllist parameter. Give it a numeric value between 0 and 1 to say how often you want CPAN.pm to try a random host from the urllist. A value of 1 means always use a random host as the first try. A value of 0 means no randomness at all. Anything in between says how often, on average, a random host should get tried first. 🎲

Randomize parameter

  • recommends_policy — (Experimental feature!) Some CPAN modules recommend additional, optional dependencies. These should generally be installed, except in resource constrained environments. When this policy is true, recommended modules get included alongside the required modules. ✨

Include recommended modules?

  • scan_cache — by default, every single time the CPAN module starts up, it scans the cache to keep the cache size in sync ('atstart'). Or you can have the scanning and cleanup happen when CPAN exits instead ('atexit'). And if you wanna block any cache cleanup at all, answer 'never'. 🧹

Perform cache scanning ('atstart', 'atexit' or 'never')?

  • shell — what's your favorite shell, bestie? What is your favorite shell? 💅
  • show_unparsable_versions — during the 'r' command, CPAN.pm finds modules that have no version number. When the command finishes, it prints a report about it. If you want that report to be very verbose, say yes to this variable. 📋

Show all individual modules that have no $VERSION?

  • show_upload_date — so the 'd' and the 'm' commands normally only show you info they already have in their in-memory database, which means they never connect to the internet. But if you set 'show_upload_date' to true, 'm' and 'd' will additionally show you the upload date of the module or distribution. Per default this feature is off, because it may need a net connection to get at that upload date. 🌐

Always try to show upload date with 'd' and 'm' command (yes/no)?

  • show_zero_versions — during the 'r' command, CPAN.pm finds modules whose version number is zero. When the command finishes, it prints a report about it. If you want that report to be very verbose, say yes to this variable. 🫶

Show all individual modules that have a $VERSION of zero?

  • suggests_policy — (Experimental feature!) Some CPAN modules suggest additional, optional dependencies. These 'suggest' dependencies provide enhanced operation. When this policy is true, suggested modules get included alongside the required modules. 💜

Include suggested modules?

  • tar_verbosity — when CPAN.pm uses the tar command, which switch for verbosity should it use? Pick 'none' for quiet operation, 'v' for file name listing, or 'vv' for a full listing. 🔍

Tar command verbosity level (none or v or vv)?

  • term_is_latin — okay so the next option is all about the charset (a.k.a. character set) your terminal supports. In general, CPAN is English-speaking territory, so the charset doesn't matter much — but some CPAN names sit outside the ASCII range. So: if your terminal supports UTF-8, you should say no to the next question. If it expects ISO-8859-1 (also known as LATIN1), then say yes. And if it supports neither, honestly your answer doesn't matter, because you won't be able to read the names of some authors anyway 😭. If you answer no, names get output in UTF-8.

Your terminal expects ISO-8859-1 (yes/no)?

  • term_ornaments — when you're using Term::ReadLine, you can turn ornaments on so your input pops and stands out against the output from CPAN.pm. ✨

Do you want to turn ornaments on?

  • test_report — so the goal of the CPAN Testers project (http://testers.cpan.org/) is to test as many CPAN packages as possible on as many platforms as possible. This gives module authors and potential users valuable feedback to spot bugs or platform compatibility issues, and it just makes CPAN better overall. 🫶

One way you can contribute is by sending test results for every module you install. If you install the CPAN::Reporter module, you get the option to automatically generate and deliver test reports to CPAN Testers whenever you run tests on a CPAN package.

Check the CPAN::Reporter documentation for extra details and configuration settings. And ngl, if your firewall blocks outgoing traffic, you may need to configure CPAN::Reporter before it can send reports. 🔥

Generate test reports if CPAN::Reporter is installed (yes/no)?

  • perl5lib_verbosity — when CPAN.pm extends @INC via PERL5LIB, it prints a list of the directories it added (or a summary of how many directories got added). Pick 'v' to actually get this message, 'none' to suppress it. 🤫

Verbosity level for PERL5LIB changes (none or v)?

  • prefer_external_tar — per default, all untar operations get done with the perl module Archive::Tar. By setting this variable to true, the external tar command gets used instead — if it's available. On Unix this is usually preferred, since they have a reliable and fast gnutar implementation. 🔥

Use the external tar program instead of Archive::Tar?

  • trust_test_report_history — when a distribution has already been tested by CPAN::Reporter on this machine, CPAN can skip the test phase entirely and just rely on the test report history instead. 👀
Careful though: this will not apply to distributions that failed tests because of missing dependencies. Also, tests can be run regardless of the history using "force".

Do you want to rely on the test report history (yes/no)?

  • urllist_ping_external — when automatic selection of the nearest cpan mirrors happens, this turns on the use of the external ping via Net::Ping::External. It's recommended in the case where the local network has a transparent proxy. 📡

Do you want to use the external ping command when autoselecting mirrors?

  • urllist_ping_verbose — when automatic selection of the nearest cpan mirrors is performed, this option can turn on verbosity during that selection process. 🔊

Do you want to see verbosity turned on when autoselecting mirrors?

🌸 use_prompt_default

okay so when this one is true, CPAN sets PERL_MM_USE_DEFAULT to a true value. that makes ExtUtils::MakeMaker (and anything compatible with it) use default answers instead of stopping mid-install to grill you about stuff. it also sets NONINTERACTIVE_TESTING to a true value, which is a more general "hey, don't try to talk to the human" signal for distributions.

want prompt defaults, bestie?

Do you want to use prompt defaults (yes/no)?

🦋 use_sqlite

CPAN::SQLite is a whole layer sitting between the index files you download from CPAN and CPAN.pm itself, and it speeds up metadata queries while cutting CPAN.pm's memory use considerably. like, actually considerably.

use CPAN::SQLite if it's there?

Use CPAN::SQLite if available? (yes/no)?

⏱️ version_timeout

this timeout is here so CPAN doesn't just hang forever while trying to parse a $VERSION that was written pathologically. (pathologically. as in someone woke up and chose chaos.)

default is 15 seconds. if you set it to 0, no timeout happens at all — but that is not recommended, okay? be normal.

timeout for parsing module versions?

Timeout for parsing module versions?

🙈 yaml_load_code

both YAML.pm and YAML::Syck can deserialise code. the catch? that needs a string eval, which might be a security risk. so this option is your on/off switch for deserialising code via CPAN::DeferredCode. (heads up: this does not work under perl 5.6.)

want code deserialisation enabled?

Do you want to enable code deserialisation (yes/no)?

🧚 yaml_module

at the time of this writing (2009-03) there were three YAML implementations actually working: YAML, YAML::Syck, and YAML::XS. the latter two are faster but they need a C compiler installed on your system. there may be more alternative YAML-conforming modules out there too. when the author tried two other players, YAML::Tiny and YAML::Perl, they seemed not powerful enough to work with CPAN.pm. that may have changed in the meantime, fr fr.

which YAML implementation would you prefer?

Which YAML implementation would you prefer?

👑 LICENSE

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. periodt. 💅

and that's the whole page, bestie!! 🫶 this was CPAN::FirstTime(3perl) — Perl Programmers Reference Guide, perl v5.44.0, dated 2026-10-17. go forth and configure your CPAN, you absolute icon. ✨💖🌈

📦 where this page comes from