{ "mode": "perldoc", "parameter": "CPAN", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/CPAN/json", "generated": "2026-10-08T12:46:25Z", "synopsis": "Interactive mode:\nperl -MCPAN -e shell", "sections": { "NAME": { "content": "CPAN - query, download and build perl modules from CPAN sites\n", "subsections": [] }, "SYNOPSIS": { "content": "Interactive mode:\n\nperl -MCPAN -e shell\n", "subsections": [ { "name": "--or--", "content": "cpan\n\nBasic commands:\n\n# Modules:\n\ncpan> install Acme::Meta # in the shell\n\nCPAN::Shell->install(\"Acme::Meta\"); # in perl\n\n# Distributions:\n\ncpan> install NWCLARK/Acme-Meta-0.02.tar.gz # in the shell\n\nCPAN::Shell->\ninstall(\"NWCLARK/Acme-Meta-0.02.tar.gz\"); # in perl\n\n# module objects:\n\n$mo = CPAN::Shell->expandany($mod);\n$mo = CPAN::Shell->expand(\"Module\",$mod); # same thing\n\n# distribution objects:\n\n$do = CPAN::Shell->expand(\"Module\",$mod)->distribution;\n$do = CPAN::Shell->expandany($distro); # same thing\n$do = CPAN::Shell->expand(\"Distribution\",\n$distro); # same thing\n", "long": "--or--" } ] }, "DESCRIPTION": { "content": "The CPAN module automates or at least simplifies the make and install of perl modules and\nextensions. It includes some primitive searching capabilities and knows how to use LWP,\nHTTP::Tiny, Net::FTP and certain external download clients to fetch distributions from the net.\n\nThese are fetched from one or more mirrored CPAN (Comprehensive Perl Archive Network) sites and\nunpacked in a dedicated directory.\n\nThe CPAN module also supports named and versioned *bundles* of modules. Bundles simplify\nhandling of sets of related modules. See Bundles below.\n\nThe package contains a session manager and a cache manager. The session manager keeps track of\nwhat has been fetched, built, and installed in the current session. The cache manager keeps\ntrack of the disk space occupied by the make processes and deletes excess space using a simple\nFIFO mechanism.\n\nAll methods provided are accessible in a programmer style and in an interactive shell style.\n\nCPAN::shell([$prompt, $command]) Starting Interactive Mode\nEnter interactive mode by running\n\nperl -MCPAN -e shell\n\nor\n\ncpan\n\nwhich puts you into a readline interface. If \"Term::ReadKey\" and either of\n\"Term::ReadLine::Perl\" or \"Term::ReadLine::Gnu\" are installed, history and command completion\nare supported.\n\nOnce at the command line, type \"h\" for one-page help screen; the rest should be\nself-explanatory.\n\nThe function call \"shell\" takes two optional arguments: one the prompt, the second the default\ninitial command line (the latter only works if a real ReadLine interface module is installed).\n\nThe most common uses of the interactive modes are\n\nSearching for authors, bundles, distribution files and modules\nThere are corresponding one-letter commands \"a\", \"b\", \"d\", and \"m\" for each of the four\ncategories and another, \"i\" for any of the mentioned four. Each of the four entities is\nimplemented as a class with slightly differing methods for displaying an object.\n\nArguments to these commands are either strings exactly matching the identification string of\nan object, or regular expressions matched case-insensitively against various attributes of the\nobjects. The parser only recognizes a regular expression when you enclose it with slashes.\n\nThe principle is that the number of objects found influences how an item is displayed. If the\nsearch finds one item, the result is displayed with the rather verbose method \"asstring\", but\nif more than one is found, each object is displayed with the terse method \"asglimpse\".\n\nExamples:\n\ncpan> m Acme::MetaSyntactic\nModule id = Acme::MetaSyntactic\nCPANUSERID BOOK (Philippe Bruhat (BooK) <[...]>)\nCPANVERSION 0.99\nCPANFILE B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz\nUPLOADDATE 2006-11-06\nMANPAGE Acme::MetaSyntactic - Themed metasyntactic variables names\nINSTFILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm\nINSTVERSION 0.99\ncpan> a BOOK\nAuthor id = BOOK\nEMAIL [...]\nFULLNAME Philippe Bruhat (BooK)\ncpan> d BOOK/Acme-MetaSyntactic-0.99.tar.gz\nDistribution id = B/BO/BOOK/Acme-MetaSyntactic-0.99.tar.gz\nCPANUSERID BOOK (Philippe Bruhat (BooK) <[...]>)\nCONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]\nUPLOADDATE 2006-11-06\ncpan> m /lorem/\nModule = Acme::MetaSyntactic::loremipsum (BOOK/Acme-MetaSyntactic-0.99.tar.gz)\nModule Text::Lorem (ADEOLA/Text-Lorem-0.3.tar.gz)\nModule Text::Lorem::More (RKRIMEN/Text-Lorem-More-0.12.tar.gz)\nModule Text::Lorem::More::Source (RKRIMEN/Text-Lorem-More-0.12.tar.gz)\ncpan> i /berlin/\nDistribution BEATNIK/Filter-NumberLines-0.02.tar.gz\nModule = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime-TimeZone-0.7904.tar.gz)\nModule Filter::NumberLines (BEATNIK/Filter-NumberLines-0.02.tar.gz)\nAuthor [...]\n\nThe examples illustrate several aspects: the first three queries target modules, authors, or\ndistros directly and yield exactly one result. The last two use regular expressions and yield\nseveral results. The last one targets all of bundles, modules, authors, and distros\nsimultaneously. When more than one result is available, they are printed in one-line format.\n\n\"get\", \"make\", \"test\", \"install\", \"clean\" modules or distributions\nThese commands take any number of arguments and investigate what is necessary to perform the\naction. Argument processing is as follows:\n\nknown module name in format Foo/Bar.pm module\nother embedded slash distribution\n- with trailing slash dot directory\nenclosing slashes regexp\nknown module name in format Foo::Bar module\n\nIf the argument is a distribution file name (recognized by embedded slashes), it is processed.\nIf it is a module, CPAN determines the distribution file in which this module is included and\nprocesses that, following any dependencies named in the module's META.yml or Makefile.PL (this\nbehavior is controlled by the configuration parameter \"prerequisitespolicy\"). If an argument\nis enclosed in slashes it is treated as a regular expression: it is expanded and if the result\nis a single object (distribution, bundle or module), this object is processed.\n\nExample:\n\ninstall Dummy::Perl # installs the module\ninstall AUXXX/Dummy-Perl-3.14.tar.gz # installs that distribution\ninstall /Dummy-Perl-3.14/ # same if the regexp is unambiguous\n\n\"get\" downloads a distribution file and untars or unzips it, \"make\" builds it, \"test\" runs the\ntest suite, and \"install\" installs it.\n\nAny \"make\" or \"test\" is run unconditionally. An\n\ninstall \n\nis also run unconditionally. But for\n\ninstall \n\nCPAN checks whether an install is needed and prints *module up to date* if the distribution\nfile containing the module doesn't need updating.\n\nCPAN also keeps track of what it has done within the current session and doesn't try to build\na package a second time regardless of whether it succeeded or not. It does not repeat a test\nrun if the test has been run successfully before. Same for install runs.\n\nThe \"force\" pragma may precede another command (currently: \"get\", \"make\", \"test\", or\n\"install\") to execute the command from scratch and attempt to continue past certain errors.\nSee the section below on the \"force\" and the \"fforce\" pragma.\n\nThe \"notest\" pragma skips the test part in the build process.\n\nExample:\n\ncpan> notest install Tk\n\nA \"clean\" command results in a\n\nmake clean\n\nbeing executed within the distribution file's working directory.\n\n\"readme\", \"perldoc\", \"look\" module or distribution\n\"readme\" displays the README file of the associated distribution. \"Look\" gets and untars (if\nnot yet done) the distribution file, changes to the appropriate directory and opens a subshell\nprocess in that directory. \"perldoc\" displays the module's pod documentation in html or plain\ntext format.\n\n\"ls\" author\n\"ls\" globbingexpression\nThe first form lists all distribution files in and below an author's CPAN directory as stored\nin the CHECKSUMS files distributed on CPAN. The listing recurses into subdirectories.\n\nThe second form limits or expands the output with shell globbing as in the following examples:\n\nls JV/make*\nls GSAR/*make*\nls */*make*\n\nThe last example is very slow and outputs extra progress indicators that break the alignment\nof the result.\n\nNote that globbing only lists directories explicitly asked for, for example FOO/* will not\nlist FOO/bar/Acme-Sthg-n.nn.tar.gz. This may be regarded as a bug that may be changed in some\nfuture version.\n\n\"failed\"\nThe \"failed\" command reports all distributions that failed on one of \"make\", \"test\" or\n\"install\" for some reason in the currently running shell session.\n\nPersistence between sessions\nIf the \"YAML\" or the \"YAML::Syck\" module is installed a record of the internal state of all\nmodules is written to disk after each step. The files contain a signature of the currently\nrunning perl version for later perusal.\n\nIf the configurations variable \"builddirreuse\" is set to a true value, then CPAN.pm reads\nthe collected YAML files. If the stored signature matches the currently running perl, the\nstored state is loaded into memory such that persistence between sessions is effectively\nestablished.\n\nThe \"force\" and the \"fforce\" pragma\nTo speed things up in complex installation scenarios, CPAN.pm keeps track of what it has\nalready done and refuses to do some things a second time. A \"get\", a \"make\", and an \"install\"\nare not repeated. A \"test\" is repeated only if the previous test was unsuccessful. The\ndiagnostic message when CPAN.pm refuses to do something a second time is one of *Has already\nbeen *\"unwrapped|made|tested successfully\" or something similar. Another situation where CPAN\nrefuses to act is an \"install\" if the corresponding \"test\" was not successful.\n\nIn all these cases, the user can override this stubborn behaviour by prepending the command\nwith the word force, for example:\n\ncpan> force get Foo\ncpan> force make AUTHOR/Bar-3.14.tar.gz\ncpan> force test Baz\ncpan> force install Acme::Meta\n\nEach *forced* command is executed with the corresponding part of its memory erased.\n\nThe \"fforce\" pragma is a variant that emulates a \"force get\" which erases the entire memory\nfollowed by the action specified, effectively restarting the whole get/make/test/install\nprocedure from scratch.\n\nLockfile\nInteractive sessions maintain a lockfile, by default \"~/.cpan/.lock\". Batch jobs can run\nwithout a lockfile and not disturb each other.\n\nThe shell offers to run in *downgraded mode* when another process is holding the lockfile.\nThis is an experimental feature that is not yet tested very well. This second shell then does\nnot write the history file, does not use the metadata file, and has a different prompt.\n\nSignals\nCPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are in the cpan-shell, it\nis intended that you can press \"^C\" anytime and return to the cpan-shell prompt. A SIGTERM\nwill cause the cpan-shell to clean up and leave the shell loop. You can emulate the effect of\na SIGTERM by sending two consecutive SIGINTs, which usually means by pressing \"^C\" twice.\n\nCPAN.pm ignores SIGPIPE. If the user sets \"inactivitytimeout\", a SIGALRM is used during the\nrun of the \"perl Makefile.PL\" or \"perl Build.PL\" subprocess. A SIGALRM is also used during\nmodule version parsing, and is controlled by \"versiontimeout\".\n\nCPAN::Shell\nThe commands available in the shell interface are methods in the package CPAN::Shell. If you\nenter the shell command, your input is split by the Text::ParseWords::shellwords() routine,\nwhich acts like most shells do. The first word is interpreted as the method to be invoked, and\nthe rest of the words are treated as the method's arguments. Continuation lines are supported by\nending a line with a literal backslash.\n\nautobundle\n\"autobundle\" writes a bundle file into the \"$CPAN::Config->{cpanhome}/Bundle\" directory. The\nfile contains a list of all modules that are both available from CPAN and currently installed\nwithin @INC. Duplicates of each distribution are suppressed. The name of the bundle file is\nbased on the current date and a counter, e.g. Bundle/Snapshot2012052100.pm. This is\ninstalled again by running \"cpan Bundle::Snapshot2012052100\", or installing\n\"Bundle::Snapshot2012052100\" from the CPAN shell.\n\nReturn value: path to the written file.\n\nhosts\nNote: this feature is still in alpha state and may change in future versions of CPAN.pm\n\nThis commands provides a statistical overview over recent download activities. The data for this\nis collected in the YAML file \"FTPstats.yml\" in your \"cpanhome\" directory. If no YAML module is\nconfigured or YAML not installed, no stats are provided.\n\ninstalltested\nInstall all distributions that have been tested successfully but have not yet been\ninstalled. See also \"istested\".\n\nistested\nList all build directories of distributions that have been tested successfully but have not\nyet been installed. See also \"installtested\".\n\nmkmyconfig", "subsections": [ { "name": "mkmyconfig", "content": "save your own preferences instead of the system-wide ones.\n\nr [Module|/Regexp/]...\nscans current perl installation for modules that have a newer version available on CPAN and\nprovides a list of them. If called without argument, all potential upgrades are listed; if\ncalled with arguments the list is filtered to the modules and regexps given as arguments.\n\nThe listing looks something like this:\n\nPackage namespace installed latest in CPAN file\nCPAN 1.9464 1.9600 ANDK/CPAN-1.9600.tar.gz\nCPAN::Reporter 1.1801 1.1902 DAGOLDEN/CPAN-Reporter-1.1902.tar.gz\nYAML 0.70 0.73 INGY/YAML-0.73.tar.gz\nYAML::Syck 1.14 1.17 AVAR/YAML-Syck-1.17.tar.gz\nYAML::Tiny 1.44 1.50 ADAMK/YAML-Tiny-1.50.tar.gz\nCGI 3.43 3.55 MARKSTOS/CGI.pm-3.55.tar.gz\nModule::Build::YAML 1.40 1.41 DAGOLDEN/Module-Build-0.3800.tar.gz\nTAP::Parser::Result::YAML 3.22 3.23 ANDYA/Test-Harness-3.23.tar.gz\nYAML::XS 0.34 0.35 INGY/YAML-LibYAML-0.35.tar.gz\n\nIt suppresses duplicates in the column \"in CPAN file\" such that distributions with many\nupgradeable modules are listed only once.\n\nNote that the list is not sorted.\n\nrecent *EXPERIMENTAL COMMAND*\nThe \"recent\" command downloads a list of recent uploads to CPAN and displays them *slowly*.\nWhile the command is running, a $SIG{INT} exits the loop after displaying the current item.\n\nNote: This command requires XML::LibXML installed.\n\nNote: This whole command currently is just a hack and will probably change in future versions of\nCPAN.pm, but the general approach will likely remain.\n\nNote: See also smoke\n\nrecompile" }, { "name": "recompile", "content": "with brute force over all installed dynamically loadable extensions (a.k.a. XS modules) with\n'force' in effect. The primary purpose of this command is to finish a network installation.\nImagine you have a common source tree for two different architectures. You decide to do a\ncompletely independent fresh installation. You start on one architecture with the help of a\nBundle file produced earlier. CPAN installs the whole Bundle for you, but when you try to repeat\nthe job on the second architecture, CPAN responds with a \"Foo up to date\" message for all\nmodules. So you invoke CPAN's recompile on the second architecture and you're done.\n\nAnother popular use for \"recompile\" is to act as a rescue in case your perl breaks binary\ncompatibility. If one of the modules that CPAN uses is in turn depending on binary compatibility\n(so you cannot run CPAN commands), then you should try the CPAN::Nox module for recovery.\n\nreport Bundle|Distribution|Module\nThe \"report\" command temporarily turns on the \"testreport\" config variable, then runs the\n\"force test\" command with the given arguments. The \"force\" pragma reruns the tests and repeats\nevery step that might have failed before.\n\nsmoke *EXPERIMENTAL COMMAND*\n* WARNING: this command downloads and executes software from CPAN to your computer of\ncompletely unknown status. You should never do this with your normal account and better have a\ndedicated well separated and secured machine to do this. *\n\nThe \"smoke\" command takes the list of recent uploads to CPAN as provided by the \"recent\" command\nand tests them all. While the command is running $SIG{INT} is defined to mean that the current\nitem shall be skipped.\n\nNote: This whole command currently is just a hack and will probably change in future versions of\nCPAN.pm, but the general approach will likely remain.\n\nNote: See also recent\n\nupgrade [Module|/Regexp/]...\nThe \"upgrade\" command first runs an \"r\" command with the given arguments and then installs the\nnewest versions of all modules that were listed by that.\n\nThe four \"CPAN::*\" Classes: Author, Bundle, Module, Distribution\nAlthough it may be considered internal, the class hierarchy does matter for both users and\nprogrammer. CPAN.pm deals with the four classes mentioned above, and those classes all share a\nset of methods. Classical single polymorphism is in effect. A metaclass object registers all\nobjects of all kinds and indexes them with a string. The strings referencing objects have a\nseparated namespace (well, not completely separated):\n\nNamespace Class\n\nwords containing a \"/\" (slash) Distribution\nwords starting with Bundle:: Bundle\neverything else Module or Author\n\nModules know their associated Distribution objects. They always refer to the most recent\nofficial release. Developers may mark their releases as unstable development versions (by\ninserting an underscore into the module version number which will also be reflected in the\ndistribution name when you run 'make dist'), so the really hottest and newest distribution is\nnot always the default. If a module Foo circulates on CPAN in both version 1.23 and 1.2390,\nCPAN.pm offers a convenient way to install version 1.23 by saying\n\ninstall Foo\n\nThis would install the complete distribution file (say BAR/Foo-1.23.tar.gz) with all\naccompanying material. But if you would like to install version 1.2390, you need to know where\nthe distribution file resides on CPAN relative to the authors/id/ directory. If the author is\nBAR, this might be BAR/Foo-1.2390.tar.gz; so you would have to say\n\ninstall BAR/Foo-1.2390.tar.gz\n\nThe first example will be driven by an object of the class CPAN::Module, the second by an object\nof class CPAN::Distribution.\n" }, { "name": "Integrating local directories", "content": "Note: this feature is still in alpha state and may change in future versions of CPAN.pm\n\nDistribution objects are normally distributions from the CPAN, but there is a slightly\ndegenerate case for Distribution objects, too, of projects held on the local disk. These\ndistribution objects have the same name as the local directory and end with a dot. A dot by\nitself is also allowed for the current directory at the time CPAN.pm was used. All actions such\nas \"make\", \"test\", and \"install\" are applied directly to that directory. This gives the command\n\"cpan .\" an interesting touch: while the normal mantra of installing a CPAN module without\nCPAN.pm is one of\n\nperl Makefile.PL perl Build.PL\n( go and get prerequisites )\nmake ./Build\nmake test ./Build test\nmake install ./Build install\n\nthe command \"cpan .\" does all of this at once. It figures out which of the two mantras is\nappropriate, fetches and installs all prerequisites, takes care of them recursively, and finally\nfinishes the installation of the module in the current directory, be it a CPAN module or not.\n\nThe typical usage case is for private modules or working copies of projects from remote\nrepositories on the local disk.\n" }, { "name": "Redirection", "content": "The usual shell redirection symbols \" | \" and \">\" are recognized by the cpan shell only when\nsurrounded by whitespace. So piping to pager or redirecting output into a file works somewhat as\nin a normal shell, with the stipulation that you must type extra spaces.\n\nPlugin support *EXPERIMENTAL*\nPlugins are objects that implement any of currently eight methods:\n\npreget\npostget\npremake\npostmake\npretest\nposttest\npreinstall\npostinstall\n\nThe \"pluginlist\" configuration parameter holds a list of strings of the form\n\nModulename=arg0,arg1,arg2,arg3,...\n\neg:\n\nCPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1\n\nAt run time, each listed plugin is instantiated as a singleton object by running the equivalent\nof this pseudo code:\n\nmy $plugin = ;\n;\nmy $p = $instance{$plugin} ||= Modulename->new($arg0,$arg1,...);\n\nThe generated singletons are kept around from instantiation until the end of the shell session.\n can be reconfigured at any time at run time. While the cpan shell is running, it\nchecks all activated plugins at each of the 8 reference points listed above and runs the\nrespective method if it is implemented for that object. The method is called with the active\nCPAN::Distribution object passed in as an argument.\n" } ] }, "CONFIGURATION": { "content": "When the CPAN module is used for the first time, a configuration dialogue tries to determine a\ncouple of site specific options. The result of the dialog is stored in a hash reference\n$CPAN::Config in a file CPAN/Config.pm.\n\nDefault values defined in the CPAN/Config.pm file can be overridden in a user specific file:\nCPAN/MyConfig.pm. Such a file is best placed in \"$HOME/.cpan/CPAN/MyConfig.pm\", because\n\"$HOME/.cpan\" is added to the search path of the CPAN module before the use() or require()\nstatements. The mkmyconfig command writes this file for you.\n\nThe \"o conf\" command has various bells and whistles:\n\ncompletion support\nIf you have a ReadLine module installed, you can hit TAB at any point of the commandline and\n\"o conf\" will offer you completion for the built-in subcommands and/or config variable\nnames.\n\ndisplaying some help: o conf help\nDisplays a short help\n\ndisplaying current values: o conf [KEY]\nDisplays the current value(s) for this config variable. Without KEY, displays all\nsubcommands and config variables.\n\nExample:\n\no conf shell\n\nIf KEY starts and ends with a slash, the string in between is treated as a regular\nexpression and only keys matching this regexp are displayed\n\nExample:\n\no conf /color/\n\nchanging of scalar values: o conf KEY VALUE\nSets the config variable KEY to VALUE. The empty string can be specified as usual in shells,\nwith '' or \"\"\n\nExample:\n\no conf wget /usr/bin/wget\n\nchanging of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST\nIf a config variable name ends with \"list\", it is a list. \"o conf KEY shift\" removes the\nfirst element of the list, \"o conf KEY pop\" removes the last element of the list. \"o conf\nKEYS unshift LIST\" prepends a list of values to the list, \"o conf KEYS push LIST\" appends a\nlist of valued to the list.\n\nLikewise, \"o conf KEY splice LIST\" passes the LIST to the corresponding splice command.\n\nFinally, any other list of arguments is taken as a new list value for the KEY variable\ndiscarding the previous value.\n\nExamples:\n\no conf urllist unshift http://cpan.dev.local/CPAN\no conf urllist splice 3 1\no conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org\n\nreverting to saved: o conf defaults\nReverts all config variables to the state in the saved config file.\n\nsaving the config: o conf commit\nSaves all config variables to the current config file (CPAN/Config.pm or CPAN/MyConfig.pm\nthat was loaded at start).\n\nThe configuration dialog can be started any time later again by issuing the command \" o conf\ninit \" in the CPAN shell. A subset of the configuration dialog can be run by issuing \"o conf\ninit WORD\" where WORD is any valid config variable or a regular expression.\n", "subsections": [ { "name": "Config Variables", "content": "The following keys in the hash reference $CPAN::Config are currently defined:\n\nallowinstallingmoduledowngrades\nallow or disallow installing module downgrades\nallowinstallingoutdateddists\nallow or disallow installing modules that are\nindexed in the cpan index pointing to a distro\nwith a higher distro-version number\napplypatch path to external prg\nautocommit commit all changes to config variables to disk\nbuildcache size of cache for directories to build modules\nbuilddir locally accessible directory to build modules\nbuilddirreuse boolean if distros in builddir are persistent\nbuildrequiresinstallpolicy\nto install or not to install when a module is\nonly needed for building. yes|no|ask/yes|ask/no\nbzip2 path to external prg\ncachemetadata use serializer to cache metadata\nchecksigs if signatures should be verified\ncleanupafterinstall\nremove build directory immediately after a\nsuccessful install and remember that for the\nduration of the session\ncolorizedebug Term::ANSIColor attributes for debugging output\ncolorizeoutput boolean if Term::ANSIColor should colorize output\ncolorizeprint Term::ANSIColor attributes for normal output\ncolorizewarn Term::ANSIColor attributes for warnings\ncommandnumberinprompt\nboolean if you want to see current command number\ncommandsquote preferred character to use for quoting external\ncommands when running them. Defaults to double\nquote on Windows, single tick everywhere else;\ncan be set to space to disable quoting\nconnecttointernetok\nwhether to ask if opening a connection is ok before\nurllist is specified\ncpanhome local directory reserved for this package\ncurl path to external prg\ndontloadhash DEPRECATED\ndontloadlist arrayref: modules in the list will not be\nloaded by the CPAN::hasinst() routine\nftp path to external prg\nftppassive if set, the environment variable FTPPASSIVE is set\nfor downloads\nftpproxy proxy host for ftp requests\nftpstatsperiod max number of days to keep download statistics\nftpstatssize max number of items to keep in the download statistics\ngetcwd see below\ngpg path to external prg\ngzip location of external program gzip\nhaltonfailure stop processing after the first failure of queued\nitems or dependencies\nhistfile file to maintain history between sessions\nhistsize maximum number of lines to keep in histfile\nhttpproxy proxy host for http requests\ninactivitytimeout breaks interactive Makefile.PLs or Build.PLs\nafter this many seconds inactivity. Set to 0 to\ndisable timeouts.\nindexexpire refetch index files after this many days\ninhibitstartupmessage\nif true, suppress the startup message\nkeepsourcewhere directory in which to keep the source (if we do)\nloadmoduleverbosity\nreport loading of optional modules used by CPAN.pm\nlynx path to external prg\nmake location of external make program\nmakearg arguments that should always be passed to 'make'\nmakeinstallmakecommand\nthe make command for running 'make install', for\nexample 'sudo make'\nmakeinstallarg same as makearg for 'make install'\nmakeplarg arguments passed to 'perl Makefile.PL'\nmbuildarg arguments passed to './Build'\nmbuildinstallarg arguments passed to './Build install'\nmbuildinstallbuildcommand\ncommand to use instead of './Build' when we are\nin the install stage, for example 'sudo ./Build'\nmbuildplarg arguments passed to 'perl Build.PL'\nncftp path to external prg\nncftpget path to external prg\nnoproxy don't proxy to these hosts/domains (comma separated list)\npager location of external program more (or any pager)\npassword your password if you CPAN server wants one\npatch path to external prg\npatchesdir local directory containing patch files\nperl5libverbosity verbosity level for PERL5LIB additions\npluginlist list of active hooks (see Plugin support above\nand the CPAN::Plugin module)\npreferexternaltar\nper default all untar operations are done with\nArchive::Tar; by setting this variable to true\nthe external tar command is used if available\npreferinstaller legal values are MB and EUMM: if a module comes\nwith both a Makefile.PL and a Build.PL, use the\nformer (EUMM) or the latter (MB); if the module\ncomes with only one of the two, that one will be\nused no matter the setting\nprerequisitespolicy\nwhat to do if you are missing module prerequisites\n('follow' automatically, 'ask' me, or 'ignore')\nFor 'follow', also sets PERLAUTOINSTALL and\nPERLEXTUTILSAUTOINSTALL for \"--defaultdeps\" if\nnot already set\nprefsdir local directory to store per-distro build options\nproxyuser username for accessing an authenticating proxy\nproxypass password for accessing an authenticating proxy\npushyhttps use https to cpan.org when possible, otherwise use http\nto cpan.org and issue a warning\nrandomizeurllist add some randomness to the sequence of the urllist\nrecommendspolicy whether recommended prerequisites should be included\nscancache controls scanning of cache ('atstart', 'atexit' or 'never')\nshell your favorite shell\nshowunparsableversions\nboolean if r command tells which modules are versionless\nshowuploaddate boolean if commands should try to determine upload date\nshowzeroversions boolean if r command tells for which modules $version==0\nsuggestspolicy whether suggested prerequisites should be included\ntar location of external program tar\ntarverbosity verbosity level for the tar command\ntermislatin deprecated: if true Unicode is translated to ISO-8859-1\n(and nonsense for characters outside latin range)\ntermornaments boolean to turn ReadLine ornamenting on/off\ntestreport email test reports (if CPAN::Reporter is installed)\ntrusttestreporthistory\nskip testing when previously tested ok (according to\nCPAN::Reporter history)\nunzip location of external program unzip\nurllist arrayref to nearby CPAN sites (or equivalent locations)\nurllistpingexternal\nuse external ping command when autoselecting mirrors\nurllistpingverbose\nincrease verbosity when autoselecting mirrors\nusepromptdefault set PERLMMUSEDEFAULT for configure/make/test/install\nusesqlite use CPAN::SQLite for metadata storage (fast and lean)\nusername your username if you CPAN server wants one\nversiontimeout stops version parsing after this many seconds.\nDefault is 15 secs. Set to 0 to disable.\nwaitlist arrayref to a wait server to try (See CPAN::WAIT)\nwget path to external prg\nyamlloadcode enable YAML code deserialisation via CPAN::DeferredCode\nyamlmodule which module to use to read/write YAML files\n\nYou can set and query each of these options interactively in the cpan shell with the \"o conf\" or\nthe \"o conf init\" command as specified below.\n\n\"o conf \"\nprints the current value of the *scalar option*\n\n\"o conf \"\nSets the value of the *scalar option* to *value*\n\n\"o conf \"\nprints the current value of the *list option* in MakeMaker's neatvalue format.\n\n\"o conf [shift|pop]\"\nshifts or pops the array in the *list option* variable\n\n\"o conf [unshift|push|splice] \"\nworks like the corresponding perl commands.\n\ninteractive editing: o conf init [MATCH|LIST]\nRuns an interactive configuration dialog for matching variables. Without argument runs the\ndialog over all supported config variables. To specify a MATCH the argument must be enclosed\nby slashes.\n\nExamples:\n\no conf init ftppassive ftpproxy\no conf init /color/\n\nNote: this method of setting config variables often provides more explanation about the\nfunctioning of a variable than the manpage.\n\nCPAN::anycwd($path): Note on config variable getcwd\nCPAN.pm changes the current working directory often and needs to determine its own current\nworking directory. By default it uses Cwd::cwd, but if for some reason this doesn't work on your\nsystem, configure alternatives according to the following table:\n\ncwd Calls Cwd::cwd\n\ngetcwd\nCalls Cwd::getcwd\n\nfastcwd\nCalls Cwd::fastcwd\n\ngetdcwd\nCalls Cwd::getdcwd\n\nbacktickcwd\nCalls the external command cwd.\n" }, { "name": "Note on the format of the urllist parameter", "content": "urllist parameters are URLs according to RFC 1738. We do a little guessing if your URL is not\ncompliant, but if you have problems with \"file\" URLs, please try the correct format. Either:\n\nfile://localhost/whatever/ftp/pub/CPAN/\n\nor\n\nfile:///home/ftp/pub/CPAN/\n" }, { "name": "The urllist parameter has CD-ROM support", "content": "The \"urllist\" parameter of the configuration table contains a list of URLs used for downloading.\nIf the list contains any \"file\" URLs, CPAN always tries there first. This feature is disabled\nfor index files. So the recommendation for the owner of a CD-ROM with CPAN contents is: include\nyour local, possibly outdated CD-ROM as a \"file\" URL at the end of urllist, e.g.\n\no conf urllist push file://localhost/CDROM/CPAN\n\nCPAN.pm will then fetch the index files from one of the CPAN sites that come at the beginning of\nurllist. It will later check for each module to see whether there is a local copy of the most\nrecent version.\n\nAnother peculiarity of urllist is that the site that we could successfully fetch the last file\nfrom automatically gets a preference token and is tried as the first site for the next request.\nSo if you add a new site at runtime it may happen that the previously preferred site will be\ntried another time. This means that if you want to disallow a site for the next transfer, it\nmust be explicitly removed from urllist.\n" }, { "name": "Maintaining the urllist parameter", "content": "If you have YAML.pm (or some other YAML module configured in \"yamlmodule\") installed, CPAN.pm\ncollects a few statistical data about recent downloads. You can view the statistics with the\n\"hosts\" command or inspect them directly by looking into the \"FTPstats.yml\" file in your\n\"cpanhome\" directory.\n\nTo get some interesting statistics, it is recommended that \"randomizeurllist\" be set; this\nintroduces some amount of randomness into the URL selection.\n\nThe \"requires\" and \"buildrequires\" dependency declarations\nSince CPAN.pm version 1.8851 modules declared as \"buildrequires\" by a distribution are treated\ndifferently depending on the config variable \"buildrequiresinstallpolicy\". By setting\n\"buildrequiresinstallpolicy\" to \"no\", such a module is not installed. It is only built and\ntested, and then kept in the list of tested but uninstalled modules. As such, it is available\nduring the build of the dependent module by integrating the path to the \"blib/arch\" and\n\"blib/lib\" directories in the environment variable PERL5LIB. If \"buildrequiresinstallpolicy\"\nis set to \"yes\", then both modules declared as \"requires\" and those declared as \"buildrequires\"\nare treated alike. By setting to \"ask/yes\" or \"ask/no\", CPAN.pm asks the user and sets the\ndefault accordingly.\n\nConfiguration of the allowinstalling* parameters\nThe \"allowinstalling*\" parameters are evaluated during the \"make\" phase. If set to \"yes\", they\nallow the testing and the installation of the current distro and otherwise have no effect. If\nset to \"no\", they may abort the build (preventing testing and installing), depending on the\ncontents of the \"blib/\" directory. The \"blib/\" directory is the directory that holds all the\nfiles that would usually be installed in the \"install\" phase.\n\n\"allowinstallingoutdateddists\" compares the \"blib/\" directory with the CPAN index. If it\nfinds something there that belongs, according to the index, to a different dist, it aborts the\ncurrent build.\n\n\"allowinstallingmoduledowngrades\" compares the \"blib/\" directory with already installed\nmodules, actually their version numbers, as determined by ExtUtils::MakeMaker or equivalent. If\na to-be-installed module would downgrade an already installed module, the current build is\naborted.\n\nAn interesting twist occurs when a distroprefs document demands the installation of an outdated\ndist via goto while \"allowinstallingoutdateddists\" forbids it. Without additional provisions,\nthis would let the \"allowinstallingoutdateddists\" win and the distroprefs lose. So the proper\narrangement in such a case is to write a second distroprefs document for the distro that \"goto\"\npoints to and overrule the \"cpanconfig\" there. E.g.:\n\n---\nmatch:\ndistribution: \"^MAUKE/Keyword-Simple-0.04.tar.gz\"\ngoto: \"MAUKE/Keyword-Simple-0.03.tar.gz\"\n---\nmatch:\ndistribution: \"^MAUKE/Keyword-Simple-0.03.tar.gz\"\ncpanconfig:\nallowinstallingoutdateddists: yes\n\nConfiguration for individual distributions (*Distroprefs*)\n(Note: This feature has been introduced in CPAN.pm 1.8854)\n\nDistributions on CPAN usually behave according to what we call the CPAN mantra. Or since the\nadvent of Module::Build we should talk about two mantras:\n\nperl Makefile.PL perl Build.PL\nmake ./Build\nmake test ./Build test\nmake install ./Build install\n\nBut some modules cannot be built with this mantra. They try to get some extra data from the user\nvia the environment, extra arguments, or interactively--thus disturbing the installation of\nlarge bundles like Phalanx100 or modules with many dependencies like Plagger.\n\nThe distroprefs system of \"CPAN.pm\" addresses this problem by allowing the user to specify extra\ninformations and recipes in YAML files to either\n\n* pass additional arguments to one of the four commands,\n\n* set environment variables\n\n* instantiate an Expect object that reads from the console, waits for some regular expressions\nand enters some answers\n\n* temporarily override assorted \"CPAN.pm\" configuration variables\n\n* specify dependencies the original maintainer forgot\n\n* disable the installation of an object altogether\n\nSee the YAML and Data::Dumper files that come with the \"CPAN.pm\" distribution in the\n\"distroprefs/\" directory for examples.\n" }, { "name": "Filenames", "content": "The YAML files themselves must have the \".yml\" extension; all other files are ignored (for two\nexceptions see *Fallback Data::Dumper and Storable* below). The containing directory can be\nspecified in \"CPAN.pm\" in the \"prefsdir\" config variable. Try \"o conf init prefsdir\" in the\nCPAN shell to set and activate the distroprefs system.\n\nEvery YAML file may contain arbitrary documents according to the YAML specification, and every\ndocument is treated as an entity that can specify the treatment of a single distribution.\n\nFilenames can be picked arbitrarily; \"CPAN.pm\" always reads all files (in alphabetical order)\nand takes the key \"match\" (see below in *Language Specs*) as a hashref containing match criteria\nthat determine if the current distribution matches the YAML document or not.\n" }, { "name": "Fallback Data::Dumper and Storable", "content": "If neither your configured \"yamlmodule\" nor YAML.pm is installed, CPAN.pm falls back to using\nData::Dumper and Storable and looks for files with the extensions \".dd\" or \".st\" in the\n\"prefsdir\" directory. These files are expected to contain one or more hashrefs. For\nData::Dumper generated files, this is expected to be done with by defining $VAR1, $VAR2, etc.\nThe YAML shell would produce these with the command\n\nysh < somefile.yml > somefile.dd\n\nFor Storable files the rule is that they must be constructed such that Storable::retrieve(file)\nreturns an array reference and the array elements represent one distropref object each. The\nconversion from YAML would look like so:\n\nperl -MYAML=LoadFile -MStorable=nstore -e '\n@y=LoadFile(shift);\nnstore(\\@y, shift)' somefile.yml somefile.st\n\nIn bootstrapping situations it is usually sufficient to translate only a few YAML files to\nData::Dumper for crucial modules like \"YAML::Syck\", \"YAML.pm\" and \"Expect.pm\". If you prefer\nStorable over Data::Dumper, remember to pull out a Storable version that writes an older format\nthan all the other Storable versions that will need to read them.\n" }, { "name": "Blueprint", "content": "The following example contains all supported keywords and structures with the exception of\n\"eexpect\" which can be used instead of \"expect\".\n\n---\ncomment: \"Demo\"\nmatch:\nmodule: \"Dancing::Queen\"\ndistribution: \"^CHACHACHA/Dancing-\"\nnotdistribution: \"\\.zip$\"\nperl: \"/usr/local/cariba-perl/bin/perl\"\nperlconfig:\narchname: \"freebsd\"\nnotcc: \"gcc\"\nenv:\nDANCINGFLOOR: \"Shubiduh\"\ndisabled: 1\ncpanconfig:\nmake: gmake\npl:\nargs:\n- \"--somearg=specialcase\"\n\nenv: {}\n\nexpect:\n- \"Which is your favorite fruit\"\n- \"apple\\n\"\n\nmake:\nargs:\n- all\n- extra-all\n\nenv: {}\n\nexpect: []\n\ncommandline: \"echo SKIPPING make\"\n\ntest:\nargs: []\n\nenv: {}\n\nexpect: []\n\ninstall:\nargs: []\n\nenv:\nWANTTOINSTALL: YES\n\nexpect:\n- \"Do you really want to install\"\n- \"y\\n\"\n\npatches:\n- \"ABCDE/Fedcba-3.14-ABCDE-01.patch\"\n\ndepends:\nconfigurerequires:\nLWP: 5.8\nbuildrequires:\nTest::Exception: 0.25\nrequires:\nSpiffy: 0.30\n" }, { "name": "Language Specs", "content": "Every YAML document represents a single hash reference. The valid keys in this hash are as\nfollows:\n\ncomment [scalar]\nA comment\n\ncpanconfig [hash]\nTemporarily override assorted \"CPAN.pm\" configuration variables.\n\nSupported are: \"buildrequiresinstallpolicy\", \"checksigs\", \"make\",\n\"makeinstallmakecommand\", \"preferinstaller\", \"testreport\". Please report as a bug when\nyou need another one supported.\n\ndepends [hash] * EXPERIMENTAL FEATURE *\nAll three types, namely \"configurerequires\", \"buildrequires\", and \"requires\" are supported\nin the way specified in the META.yml specification. The current implementation *merges* the\nspecified dependencies with those declared by the package maintainer. In a future\nimplementation this may be changed to override the original declaration.\n\ndisabled [boolean]\nSpecifies that this distribution shall not be processed at all.\n\nfeatures [array] * EXPERIMENTAL FEATURE *\nExperimental implementation to deal with optionalfeatures from META.yml. Still needs\ncoordination with installer software and currently works only for META.yml declaring\n\"dynamicconfig=0\". Use with caution.\n\ngoto [string]\nThe canonical name of a delegate distribution to install instead. Useful when a new version,\nalthough it tests OK itself, breaks something else or a developer release or a fork is\nalready uploaded that is better than the last released version.\n\ninstall [hash]\nProcessing instructions for the \"make install\" or \"./Build install\" phase of the CPAN\nmantra. See below under *Processing Instructions*.\n\nmake [hash]\nProcessing instructions for the \"make\" or \"./Build\" phase of the CPAN mantra. See below\nunder *Processing Instructions*.\n\nmatch [hash]\nA hashref with one or more of the keys \"distribution\", \"module\", \"perl\", \"perlconfig\", and\n\"env\" that specify whether a document is targeted at a specific CPAN distribution or\ninstallation. Keys prefixed with \"not\" negates the corresponding match.\n\nThe corresponding values are interpreted as regular expressions. The \"distribution\" related\none will be matched against the canonical distribution name, e.g.\n\"AUTHOR/Foo-Bar-3.14.tar.gz\".\n\nThe \"module\" related one will be matched against *all* modules contained in the distribution\nuntil one module matches.\n\nThe \"perl\" related one will be matched against $^X (but with the absolute path).\n\nThe value associated with \"perlconfig\" is itself a hashref that is matched against\ncorresponding values in the %Config::Config hash living in the \"Config.pm\" module. Keys\nprefixed with \"not\" negates the corresponding match.\n\nThe value associated with \"env\" is itself a hashref that is matched against corresponding\nvalues in the %ENV hash. Keys prefixed with \"not\" negates the corresponding match.\n\nIf more than one restriction of \"module\", \"distribution\", etc. is specified, the results of\nthe separately computed match values must all match. If so, the hashref represented by the\nYAML document is returned as the preference structure for the current distribution.\n\npatches [array]\nAn array of patches on CPAN or on the local disk to be applied in order via an external\npatch program. If the value for the \"-p\" parameter is 0 or 1 is determined by reading the\npatch beforehand. The path to each patch is either an absolute path on the local filesystem\nor relative to a patch directory specified in the \"patchesdir\" configuration variable or in\nthe format of a canonical distro name. For examples please consult the distroprefs/\ndirectory in the CPAN.pm distribution (these examples are not installed by default).\n\nNote: if the \"applypatch\" program is installed and \"CPAN::Config\" knows about it and a patch\nis written by the \"makepatch\" program, then \"CPAN.pm\" lets \"applypatch\" apply the patch.\nBoth \"makepatch\" and \"applypatch\" are available from CPAN in the \"JV/makepatch-*\"\ndistribution.\n\npl [hash]\nProcessing instructions for the \"perl Makefile.PL\" or \"perl Build.PL\" phase of the CPAN\nmantra. See below under *Processing Instructions*.\n\ntest [hash]\nProcessing instructions for the \"make test\" or \"./Build test\" phase of the CPAN mantra. See\nbelow under *Processing Instructions*.\n" }, { "name": "Processing Instructions", "content": "args [array]\nArguments to be added to the command line\n\ncommandline\nA full commandline to run via system(). During execution, the environment variable PERL is\nset to $^X (but with an absolute path). If \"commandline\" is specified, \"args\" is not used.\n\neexpect [hash]\nExtended \"expect\". This is a hash reference with four allowed keys, \"mode\", \"timeout\",\n\"reuse\", and \"talk\".\n\nYou must install the \"Expect\" module to use \"eexpect\". CPAN.pm does not install it for you.\n\n\"mode\" may have the values \"deterministic\" for the case where all questions come in the\norder written down and \"anyorder\" for the case where the questions may come in any order.\nThe default mode is \"deterministic\".\n\n\"timeout\" denotes a timeout in seconds. Floating-point timeouts are OK. With\n\"mode=deterministic\", the timeout denotes the timeout per question; with \"mode=anyorder\" it\ndenotes the timeout per byte received from the stream or questions.\n\n\"talk\" is a reference to an array that contains alternating questions and answers. Questions\nare regular expressions and answers are literal strings. The Expect module watches the\nstream from the execution of the external program (\"perl Makefile.PL\", \"perl Build.PL\",\n\"make\", etc.).\n\nFor \"mode=deterministic\", the CPAN.pm injects the corresponding answer as soon as the stream\nmatches the regular expression.\n\nFor \"mode=anyorder\" CPAN.pm answers a question as soon as the timeout is reached for the\nnext byte in the input stream. In this mode you can use the \"reuse\" parameter to decide what\nwill happen with a question-answer pair after it has been used. In the default case\n(reuse=0) it is removed from the array, avoiding being used again accidentally. If you want\nto answer the question \"Do you really want to do that\" several times, then it must be\nincluded in the array at least as often as you want this answer to be given. Setting the\nparameter \"reuse\" to 1 makes this repetition unnecessary.\n\nenv [hash]\nEnvironment variables to be set during the command\n\nexpect [array]\nYou must install the \"Expect\" module to use \"expect\". CPAN.pm does not install it for you.\n\n\"expect: \" is a short notation for this \"eexpect\":\n\neexpect:\nmode: deterministic\ntimeout: 15\ntalk: \n\nSchema verification with \"Kwalify\"\nIf you have the \"Kwalify\" module installed (which is part of the Bundle::CPANxxl), then all your\ndistroprefs files are checked for syntactic correctness.\n" }, { "name": "Example Distroprefs Files", "content": "\"CPAN.pm\" comes with a collection of example YAML files. Note that these are really just\nexamples and should not be used without care because they cannot fit everybody's purpose. After\nall, the authors of the packages that ask questions had a need to ask, so you should watch their\nquestions and adjust the examples to your environment and your needs. You have been warned:-)\n\nPROGRAMMER'S INTERFACE\nIf you do not enter the shell, shell commands are available both as methods\n(\"CPAN::Shell->install(...)\") and as functions in the calling package (install(...)). Before\ncalling low-level commands, it makes sense to initialize components of CPAN you need, e.g.:\n\nCPAN::HandleConfig->load;\nCPAN::Shell::setupoutput;\nCPAN::Index->reload;\n\nHigh-level commands do such initializations automatically.\n\nThere's currently only one class that has a stable interface - CPAN::Shell. All commands that\nare available in the CPAN shell are methods of the class CPAN::Shell. The arguments on the\ncommandline are passed as arguments to the method.\n\nSo if you take for example the shell command\n\nnotest install A B C\n\nthe actually executed command is\n\nCPAN::Shell->notest(\"install\",\"A\",\"B\",\"C\");\n\nEach of the commands that produce listings of modules (\"r\", \"autobundle\", \"u\") also return a\nlist of the IDs of all modules within the list.\n" }, { "name": "expand", "content": "The IDs of all objects available within a program are strings that can be expanded to the\ncorresponding real objects with the \"CPAN::Shell->expand(\"Module\",@things)\" method. Expand\nreturns a list of CPAN::Module objects according to the @things arguments given. In scalar\ncontext, it returns only the first element of the list.\n" }, { "name": "expandany", "content": "Like expand, but returns objects of the appropriate type, i.e. CPAN::Bundle objects for\nbundles, CPAN::Module objects for modules, and CPAN::Distribution objects for distributions.\nNote: it does not expand to CPAN::Author objects.\n\nProgramming Examples\nThis enables the programmer to do operations that combine functionalities that are available\nin the shell.\n\n# install everything that is outdated on my disk:\nperl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'\n\n# install my favorite programs if necessary:\nfor $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {\nCPAN::Shell->install($mod);\n}\n\n# list all modules on my disk that have no VERSION number\nfor $mod (CPAN::Shell->expand(\"Module\",\"/./\")) {\nnext unless $mod->instfile;\n# MakeMaker convention for undefined $VERSION:\nnext unless $mod->instversion eq \"undef\";\nprint \"No VERSION in \", $mod->id, \"\\n\";\n}\n\n# find out which distribution on CPAN contains a module:\nprint CPAN::Shell->expand(\"Module\",\"Apache::Constants\")->cpanfile\n\nOr if you want to schedule a *cron* job to watch CPAN, you could list all modules that need\nupdating. First a quick and dirty way:\n\nperl -e 'use CPAN; CPAN::Shell->r;'\n\nIf you don't want any output should all modules be up to date, parse the output of above\ncommand for the regular expression \"/modules are up to date/\" and decide to mail the output\nonly if it doesn't match.\n\nIf you prefer to do it more in a programmerish style in one single process, something like\nthis may better suit you:\n\n# list all modules on my disk that have newer versions on CPAN\nfor $mod (CPAN::Shell->expand(\"Module\",\"/./\")) {\nnext unless $mod->instfile;\nnext if $mod->uptodate;\nprintf \"Module %s is installed as %s, could be updated to %s from CPAN\\n\",\n$mod->id, $mod->instversion, $mod->cpanversion;\n}\n\nIf that gives too much output every day, you may want to watch only for three modules. You can\nwrite\n\nfor $mod (CPAN::Shell->expand(\"Module\",\"/Apache|LWP|CGI/\")) {\n\nas the first line instead. Or you can combine some of the above tricks:\n\n# watch only for a new modperl module\n$mod = CPAN::Shell->expand(\"Module\",\"modperl\");\nexit if $mod->uptodate;\n# new modperl arrived, let me know all update recommendations\nCPAN::Shell->r;\n" }, { "name": "Methods in the other Classes", "content": "CPAN::Author::asglimpse()\nReturns a one-line description of the author\n\nCPAN::Author::asstring()\nReturns a multi-line description of the author\n\nCPAN::Author::email()\nReturns the author's email address\n\nCPAN::Author::fullname()\nReturns the author's name\n\nCPAN::Author::name()\nAn alias for fullname\n\nCPAN::Bundle::asglimpse()\nReturns a one-line description of the bundle\n\nCPAN::Bundle::asstring()\nReturns a multi-line description of the bundle\n\nCPAN::Bundle::clean()\nRecursively runs the \"clean\" method on all items contained in the bundle.\n\nCPAN::Bundle::contains()\nReturns a list of objects' IDs contained in a bundle. The associated objects may be bundles,\nmodules or distributions.\n\nCPAN::Bundle::force($method,@args)\nForces CPAN to perform a task that it normally would have refused to do. Force takes as\narguments a method name to be called and any number of additional arguments that should be\npassed to the called method. The internals of the object get the needed changes so that\nCPAN.pm does not refuse to take the action. The \"force\" is passed recursively to all\ncontained objects. See also the section above on the \"force\" and the \"fforce\" pragma.\n\nCPAN::Bundle::get()\nRecursively runs the \"get\" method on all items contained in the bundle\n\nCPAN::Bundle::instfile()\nReturns the highest installed version of the bundle in either @INC or\n\"$CPAN::Config->{cpanhome}\". Note that this is different from CPAN::Module::instfile.\n\nCPAN::Bundle::instversion()\nLike CPAN::Bundle::instfile, but returns the $VERSION\n\nCPAN::Bundle::uptodate()\nReturns 1 if the bundle itself and all its members are up-to-date.\n\nCPAN::Bundle::install()\nRecursively runs the \"install\" method on all items contained in the bundle\n\nCPAN::Bundle::make()\nRecursively runs the \"make\" method on all items contained in the bundle\n\nCPAN::Bundle::readme()\nRecursively runs the \"readme\" method on all items contained in the bundle\n\nCPAN::Bundle::test()\nRecursively runs the \"test\" method on all items contained in the bundle\n\nCPAN::Distribution::asglimpse()\nReturns a one-line description of the distribution\n\nCPAN::Distribution::asstring()\nReturns a multi-line description of the distribution\n\nCPAN::Distribution::author\nReturns the CPAN::Author object of the maintainer who uploaded this distribution\n\nCPAN::Distribution::prettyid()\nReturns a string of the form \"AUTHORID/TARBALL\", where AUTHORID is the author's PAUSE ID and\nTARBALL is the distribution filename.\n\nCPAN::Distribution::baseid()\nReturns the distribution filename without any archive suffix. E.g \"Foo-Bar-0.01\"\n\nCPAN::Distribution::clean()\nChanges to the directory where the distribution has been unpacked and runs \"make clean\"\nthere.\n\nCPAN::Distribution::containsmods()\nReturns a list of IDs of modules contained in a distribution file. Works only for\ndistributions listed in the 02packages.details.txt.gz file. This typically means that just\nmost recent version of a distribution is covered.\n\nCPAN::Distribution::cvsimport()\nChanges to the directory where the distribution has been unpacked and runs something like\n\ncvs -d $cvsroot import -m $cvslog $cvsdir $userid v$version\n\nthere.\n\nCPAN::Distribution::dir()\nReturns the directory into which this distribution has been unpacked.\n\nCPAN::Distribution::force($method,@args)\nForces CPAN to perform a task that it normally would have refused to do. Force takes as\narguments a method name to be called and any number of additional arguments that should be\npassed to the called method. The internals of the object get the needed changes so that\nCPAN.pm does not refuse to take the action. See also the section above on the \"force\" and\nthe \"fforce\" pragma.\n\nCPAN::Distribution::get()\nDownloads the distribution from CPAN and unpacks it. Does nothing if the distribution has\nalready been downloaded and unpacked within the current session.\n\nCPAN::Distribution::install()\nChanges to the directory where the distribution has been unpacked and runs the external\ncommand \"make install\" there. If \"make\" has not yet been run, it will be run first. A \"make\ntest\" is issued in any case and if this fails, the install is cancelled. The cancellation\ncan be avoided by letting \"force\" run the \"install\" for you.\n\nThis install method only has the power to install the distribution if there are no\ndependencies in the way. To install an object along with all its dependencies, use\nCPAN::Shell->install.\n\nNote that install() gives no meaningful return value. See uptodate().\n\nCPAN::Distribution::isaperl()\nReturns 1 if this distribution file seems to be a perl distribution. Normally this is\nderived from the file name only, but the index from CPAN can contain a hint to achieve a\nreturn value of true for other filenames too.\n\nCPAN::Distribution::look()\nChanges to the directory where the distribution has been unpacked and opens a subshell\nthere. Exiting the subshell returns.\n\nCPAN::Distribution::make()\nFirst runs the \"get\" method to make sure the distribution is downloaded and unpacked.\nChanges to the directory where the distribution has been unpacked and runs the external\ncommands \"perl Makefile.PL\" or \"perl Build.PL\" and \"make\" there.\n\nCPAN::Distribution::perldoc()\nDownloads the pod documentation of the file associated with a distribution (in HTML format)\nand runs it through the external command *lynx* specified in \"$CPAN::Config->{lynx}\". If\n*lynx* isn't available, it converts it to plain text with the external command *html2text*\nand runs it through the pager specified in \"$CPAN::Config->{pager}\".\n\nCPAN::Distribution::prefs()\nReturns the hash reference from the first matching YAML file that the user has deposited in\nthe \"prefsdir/\" directory. The first succeeding match wins. The files in the \"prefsdir/\"\nare processed alphabetically, and the canonical distro name (e.g.\nAUTHOR/Foo-Bar-3.14.tar.gz) is matched against the regular expressions stored in the\n$root->{match}{distribution} attribute value. Additionally all module names contained in a\ndistribution are matched against the regular expressions in the $root->{match}{module}\nattribute value. The two match values are ANDed together. Each of the two attributes are\noptional.\n\nCPAN::Distribution::prereqpm()\nReturns the hash reference that has been announced by a distribution as the \"requires\" and\n\"buildrequires\" elements. These can be declared either by the \"META.yml\" (if authoritative)\nor can be deposited after the run of \"Build.PL\" in the file \"./build/prereqs\" or after the\nrun of \"Makfile.PL\" written as the \"PREREQPM\" hash in a comment in the produced \"Makefile\".\n*Note*: this method only works after an attempt has been made to \"make\" the distribution.\nReturns undef otherwise.\n\nCPAN::Distribution::readme()\nDownloads the README file associated with a distribution and runs it through the pager\nspecified in \"$CPAN::Config->{pager}\".\n\nCPAN::Distribution::reports()\nDownloads report data for this distribution from www.cpantesters.org and displays a subset\nof them.\n\nCPAN::Distribution::readyaml()\nReturns the content of the META.yml of this distro as a hashref. Note: works only after an\nattempt has been made to \"make\" the distribution. Returns undef otherwise. Also returns\nundef if the content of META.yml is not authoritative. (The rules about what exactly makes\nthe content authoritative are still in flux.)\n\nCPAN::Distribution::test()\nChanges to the directory where the distribution has been unpacked and runs \"make test\"\nthere.\n\nCPAN::Distribution::uptodate()\nReturns 1 if all the modules contained in the distribution are up-to-date. Relies on\ncontainsmods.\n\nCPAN::Index::forcereload()\nForces a reload of all indices.\n\nCPAN::Index::reload()\nReloads all indices if they have not been read for more than \"$CPAN::Config->{indexexpire}\"\ndays.\n\nCPAN::InfoObj::dump()\nCPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution inherit this method. It\nprints the data structure associated with an object. Useful for debugging. Note: the data\nstructure is considered internal and thus subject to change without notice.\n\nCPAN::Module::asglimpse()\nReturns a one-line description of the module in four columns: The first column contains the\nword \"Module\", the second column consists of one character: an equals sign if this module is\nalready installed and up-to-date, a less-than sign if this module is installed but can be\nupgraded, and a space if the module is not installed. The third column is the name of the\nmodule and the fourth column gives maintainer or distribution information.\n\nCPAN::Module::asstring()\nReturns a multi-line description of the module\n\nCPAN::Module::clean()\nRuns a clean on the distribution associated with this module.\n\nCPAN::Module::cpanfile()\nReturns the filename on CPAN that is associated with the module.\n\nCPAN::Module::cpanversion()\nReturns the latest version of this module available on CPAN.\n\nCPAN::Module::cvsimport()\nRuns a cvsimport on the distribution associated with this module.\n\nCPAN::Module::description()\nReturns a 44 character description of this module. Only available for modules listed in The\nModule List (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz)\n\nCPAN::Module::distribution()\nReturns the CPAN::Distribution object that contains the current version of this module.\n\nCPAN::Module::dslipstatus()\nReturns a hash reference. The keys of the hash are the letters \"D\", \"S\", \"L\", \"I\", and

,\nfor development status, support level, language, interface and public licence respectively.\nThe data for the DSLIP status are collected by pause.perl.org when authors register their\nnamespaces. The values of the 5 hash elements are one-character words whose meaning is\ndescribed in the table below. There are also 5 hash elements \"DV\", \"SV\", \"LV\", \"IV\", and\n that carry a more verbose value of the 5 status variables.\n\nWhere the 'DSLIP' characters have the following meanings:\n\nD - Development Stage (Note: *NO IMPLIED TIMESCALES*):\ni - Idea, listed to gain consensus or as a placeholder\nc - under construction but pre-alpha (not yet released)\na/b - Alpha/Beta testing\nR - Released\nM - Mature (no rigorous definition)\nS - Standard, supplied with Perl 5\n\nS - Support Level:\nm - Mailing-list\nd - Developer\nu - Usenet newsgroup comp.lang.perl.modules\nn - None known, try comp.lang.perl.modules\na - abandoned; volunteers welcome to take over maintenance\n\nL - Language Used:\np - Perl-only, no compiler needed, should be platform independent\nc - C and perl, a C compiler will be needed\nh - Hybrid, written in perl with optional C code, no compiler needed\n+ - C++ and perl, a C++ compiler will be needed\no - perl and another language other than C or C++\n\nI - Interface Style\nf - plain Functions, no references used\nh - hybrid, object and function interfaces available\nn - no interface at all (huh?)\nr - some use of unblessed References or ties\nO - Object oriented using blessed references and/or inheritance\n\nP - Public License\np - Standard-Perl: user may choose between GPL and Artistic\ng - GPL: GNU General Public License\nl - LGPL: \"GNU Lesser General Public License\" (previously known as\n\"GNU Library General Public License\")\nb - BSD: The BSD License\na - Artistic license alone\n2 - Artistic license 2.0 or later\no - open source: approved by www.opensource.org\nd - allows distribution without restrictions\nr - restricted distribution\nn - no license at all\n\nCPAN::Module::force($method,@args)\nForces CPAN to perform a task it would normally refuse to do. Force takes as arguments a\nmethod name to be invoked and any number of additional arguments to pass that method. The\ninternals of the object get the needed changes so that CPAN.pm does not refuse to take the\naction. See also the section above on the \"force\" and the \"fforce\" pragma.\n\nCPAN::Module::get()\nRuns a get on the distribution associated with this module.\n\nCPAN::Module::instfile()\nReturns the filename of the module found in @INC. The first file found is reported, just as\nperl itself stops searching @INC once it finds a module.\n\nCPAN::Module::availablefile()\nReturns the filename of the module found in PERL5LIB or @INC. The first file found is\nreported. The advantage of this method over \"instfile\" is that modules that have been\ntested but not yet installed are included because PERL5LIB keeps track of tested modules.\n\nCPAN::Module::instversion()\nReturns the version number of the installed module in readable format.\n\nCPAN::Module::availableversion()\nReturns the version number of the available module in readable format.\n\nCPAN::Module::install()\nRuns an \"install\" on the distribution associated with this module.\n\nCPAN::Module::look()\nChanges to the directory where the distribution associated with this module has been\nunpacked and opens a subshell there. Exiting the subshell returns.\n\nCPAN::Module::make()\nRuns a \"make\" on the distribution associated with this module.\n\nCPAN::Module::manpageheadline()\nIf module is installed, peeks into the module's manpage, reads the headline, and returns it.\nMoreover, if the module has been downloaded within this session, does the equivalent on the\ndownloaded module even if it hasn't been installed yet.\n\nCPAN::Module::perldoc()\nRuns a \"perldoc\" on this module.\n\nCPAN::Module::readme()\nRuns a \"readme\" on the distribution associated with this module.\n\nCPAN::Module::reports()\nCalls the reports() method on the associated distribution object.\n\nCPAN::Module::test()\nRuns a \"test\" on the distribution associated with this module.\n\nCPAN::Module::uptodate()\nReturns 1 if the module is installed and up-to-date.\n\nCPAN::Module::userid()\nReturns the author's ID of the module.\n" }, { "name": "Cache Manager", "content": "Currently the cache manager only keeps track of the build directory\n($CPAN::Config->{builddir}). It is a simple FIFO mechanism that deletes complete directories\nbelow \"builddir\" as soon as the size of all directories there gets bigger than\n$CPAN::Config->{buildcache} (in MB). The contents of this cache may be used for later\nre-installations that you intend to do manually, but will never be trusted by CPAN itself. This\nis due to the fact that the user might use these directories for building modules on different\narchitectures.\n\nThere is another directory ($CPAN::Config->{keepsourcewhere}) where the original distribution\nfiles are kept. This directory is not covered by the cache manager and must be controlled by the\nuser. If you choose to have the same directory as builddir and as keepsourcewhere directory,\nthen your sources will be deleted with the same fifo mechanism.\n" }, { "name": "Bundles", "content": "A bundle is just a perl module in the namespace Bundle:: that does not define any functions or\nmethods. It usually only contains documentation.\n\nIt starts like a perl module with a package declaration and a $VERSION variable. After that the\npod section looks like any other pod with the only difference being that *one special pod\nsection* exists starting with (verbatim):\n\n=head1 CONTENTS\n\nIn this pod section each line obeys the format\n\nModuleName [VersionString] [- optional text]\n\nThe only required part is the first field, the name of a module (e.g. Foo::Bar, i.e. *not* the\nname of the distribution file). The rest of the line is optional. The comment part is delimited\nby a dash just as in the man page header.\n\nThe distribution of a bundle should follow the same convention as other distributions.\n\nBundles are treated specially in the CPAN package. If you say 'install Bundle::Tkkit' (assuming\nsuch a bundle exists), CPAN will install all the modules in the CONTENTS section of the pod. You\ncan install your own Bundles locally by placing a conformant Bundle file somewhere into your\n@INC path. The autobundle() command which is available in the shell interface does that for you\nby including all currently installed modules in a snapshot bundle file.\n" } ] }, "PREREQUISITES": { "content": "The CPAN program is trying to depend on as little as possible so the user can use it in hostile\nenvironment. It works better the more goodies the environment provides. For example if you try\nin the CPAN shell\n\ninstall Bundle::CPAN\n\nor\n\ninstall Bundle::CPANxxl\n\nyou will find the shell more convenient than the bare shell before.\n\nIf you have a local mirror of CPAN and can access all files with \"file:\" URLs, then you only\nneed a perl later than perl5.003 to run this module. Otherwise Net::FTP is strongly recommended.\nLWP may be required for non-UNIX systems, or if your nearest CPAN site is associated with a URL\nthat is not \"ftp:\".\n\nIf you have neither Net::FTP nor LWP, there is a fallback mechanism implemented for an external\nftp command or for an external lynx command.\n", "subsections": [] }, "UTILITIES": { "content": "", "subsections": [ { "name": "Finding packages and VERSION", "content": "This module presumes that all packages on CPAN\n\n* declare their $VERSION variable in an easy to parse manner. This prerequisite can hardly be\nrelaxed because it consumes far too much memory to load all packages into the running program\njust to determine the $VERSION variable. Currently all programs that are dealing with version\nuse something like this\n\nperl -MExtUtils::MakeMaker -le \\\n'print MM->parseversion(shift)' filename\n\nIf you are author of a package and wonder if your $VERSION can be parsed, please try the above\nmethod.\n\n* come as compressed or gzipped tarfiles or as zip files and contain a \"Makefile.PL\" or\n\"Build.PL\" (well, we try to handle a bit more, but with little enthusiasm).\n" }, { "name": "Debugging", "content": "Debugging this module is more than a bit complex due to interference from the software producing\nthe indices on CPAN, the mirroring process on CPAN, packaging, configuration, synchronicity, and\neven (gasp!) due to bugs within the CPAN.pm module itself.\n\nFor debugging the code of CPAN.pm itself in interactive mode, some debugging aid can be turned\non for most packages within CPAN.pm with one of\n\no debug package...\nsets debug mode for packages.\n\no debug -package...\nunsets debug mode for packages.\n\no debug all\nturns debugging on for all packages.\n\no debug number\n\nwhich sets the debugging packages directly. Note that \"o debug 0\" turns debugging off.\n\nWhat seems a successful strategy is the combination of \"reload cpan\" and the debugging switches.\nAdd a new debug statement while running in the shell and then issue a \"reload cpan\" and see the\nnew debugging messages immediately without losing the current context.\n\n\"o debug\" without an argument lists the valid package names and the current set of packages in\ndebugging mode. \"o debug\" has built-in completion support.\n\nFor debugging of CPAN data there is the \"dump\" command which takes the same arguments as\nmake/test/install and outputs each object's Data::Dumper dump. If an argument looks like a perl\nvariable and contains one of \"$\", \"@\" or \"%\", it is eval()ed and fed to Data::Dumper directly.\n" }, { "name": "Floppy, Zip, Offline Mode", "content": "CPAN.pm works nicely without network access, too. If you maintain machines that are not\nnetworked at all, you should consider working with \"file:\" URLs. You'll have to collect your\nmodules somewhere first. So you might use CPAN.pm to put together all you need on a networked\nmachine. Then copy the $CPAN::Config->{keepsourcewhere} (but not $CPAN::Config->{builddir})\ndirectory on a floppy. This floppy is kind of a personal CPAN. CPAN.pm on the non-networked\nmachines works nicely with this floppy. See also below the paragraph about CD-ROM support.\n" }, { "name": "Basic Utilities for Programmers", "content": "" }, { "name": "has_inst", "content": "Returns true if the module is installed. Used to load all modules into the running CPAN.pm\nthat are considered optional. The config variable \"dontloadlist\" intercepts the hasinst()\ncall such that an optional module is not loaded despite being available. For example, the\nfollowing command will prevent \"YAML.pm\" from being loaded:\n\ncpan> o conf dontloadlist push YAML\n\nSee the source for details.\n" }, { "name": "use_inst", "content": "Similary to hasinst() tries to load optional library but also dies if library is not\navailable\n" }, { "name": "has_usable", "content": "Returns true if the module is installed and in a usable state. Only useful for a handful of\nmodules that are used internally. See the source for details.\n" }, { "name": "instance", "content": "The constructor for all the singletons used to represent modules, distributions, authors, and\nbundles. If the object already exists, this method returns the object; otherwise, it calls the\nconstructor.\n" }, { "name": "frontend", "content": "" }, { "name": "frontend", "content": "Getter/setter for frontend object. Method just allows to subclass CPAN.pm.\n" } ] }, "SECURITY": { "content": "There's no strong security layer in CPAN.pm. CPAN.pm helps you to install foreign, unmasked,\nunsigned code on your machine. We compare to a checksum that comes from the net just as the\ndistribution file itself. But we try to make it easy to add security on demand:\n", "subsections": [ { "name": "Cryptographically signed modules", "content": "Since release 1.77, CPAN.pm has been able to verify cryptographically signed module\ndistributions using Module::Signature. The CPAN modules can be signed by their authors, thus\ngiving more security. The simple unsigned MD5 checksums that were used before by CPAN protect\nmainly against accidental file corruption.\n\nYou will need to have Module::Signature installed, which in turn requires that you have at least\none of Crypt::OpenPGP module or the command-line gpg tool installed.\n\nYou will also need to be able to connect over the Internet to the public key servers, like\npgp.mit.edu, and their port 11731 (the HKP protocol).\n\nThe configuration parameter checksigs is there to turn signature checking on or off.\n" } ] }, "EXPORT": { "content": "Most functions in package CPAN are exported by default. The reason for this is that the primary\nuse is intended for the cpan shell or for one-liners.\n", "subsections": [] }, "ENVIRONMENT": { "content": "When the CPAN shell enters a subshell via the look command, it sets the environment\nCPANSHELLLEVEL to 1, or increments that variable if it is already set.\n\nWhen CPAN runs, it sets the environment variable PERL5CPANISRUNNING to the ID of the running\nprocess. It also sets PERL5CPANPLUSISRUNNING to prevent runaway processes which could happen\nwith older versions of Module::Install.\n\nWhen running \"perl Makefile.PL\", the environment variable \"PERL5CPANISEXECUTING\" is set to\nthe full path of the \"Makefile.PL\" that is being executed. This prevents runaway processes with\nnewer versions of Module::Install.\n\nWhen the config variable ftppassive is set, all downloads will be run with the environment\nvariable FTPPASSIVE set to this value. This is in general a good idea as it influences both\nNet::FTP and LWP based connections. The same effect can be achieved by starting the cpan shell\nwith this environment variable set. For Net::FTP alone, one can also always set passive mode by\nrunning libnetcfg.\n", "subsections": [] }, "POPULATE AN INSTALLATION WITH LOTS OF MODULES": { "content": "Populating a freshly installed perl with one's favorite modules is pretty easy if you maintain a\nprivate bundle definition file. To get a useful blueprint of a bundle definition file, the\ncommand autobundle can be used on the CPAN shell command line. This command writes a bundle\ndefinition file for all modules installed for the current perl interpreter. It's recommended to\nrun this command once only, and from then on maintain the file manually under a private name,\nsay Bundle/mybundle.pm. With a clever bundle file you can then simply say\n\ncpan> install Bundle::mybundle\n\nthen answer a few questions and go out for coffee (possibly even in a different city).\n\nMaintaining a bundle definition file means keeping track of two things: dependencies and\ninteractivity. CPAN.pm sometimes fails on calculating dependencies because not all modules\ndefine all MakeMaker attributes correctly, so a bundle definition file should specify\nprerequisites as early as possible. On the other hand, it's annoying that so many distributions\nneed some interactive configuring. So what you can try to accomplish in your private bundle file\nis to have the packages that need to be configured early in the file and the gentle ones later,\nso you can go out for coffee after a few minutes and leave CPAN.pm to churn away unattended.\n\nWORKING WITH CPAN.pm BEHIND FIREWALLS\nThanks to Graham Barr for contributing the following paragraphs about the interaction between\nperl, and various firewall configurations. For further information on firewalls, it is\nrecommended to consult the documentation that comes with the *ncftp* program. If you are unable\nto go through the firewall with a simple Perl setup, it is likely that you can configure *ncftp*\nso that it works through your firewall.\n", "subsections": [ { "name": "Three basic types of firewalls", "content": "Firewalls can be categorized into three basic types.\n\nhttp firewall\nThis is when the firewall machine runs a web server, and to access the outside world, you\nmust do so via that web server. If you set environment variables like httpproxy or\nftpproxy to values beginning with http://, or in your web browser you've proxy information\nset, then you know you are running behind an http firewall.\n\nTo access servers outside these types of firewalls with perl (even for ftp), you need LWP or\nHTTP::Tiny.\n\nftp firewall\nThis where the firewall machine runs an ftp server. This kind of firewall will only let you\naccess ftp servers outside the firewall. This is usually done by connecting to the firewall\nwith ftp, then entering a username like \"user@outside.host.com\".\n\nTo access servers outside these type of firewalls with perl, you need Net::FTP.\n\nOne-way visibility\nOne-way visibility means these firewalls try to make themselves invisible to users inside\nthe firewall. An FTP data connection is normally created by sending your IP address to the\nremote server and then listening for the return connection. But the remote server will not\nbe able to connect to you because of the firewall. For these types of firewall, FTP\nconnections need to be done in a passive mode.\n\nThere are two that I can think off.\n\nSOCKS\nIf you are using a SOCKS firewall, you will need to compile perl and link it with the\nSOCKS library. This is what is normally called a 'socksified' perl. With this executable\nyou will be able to connect to servers outside the firewall as if it were not there.\n\nIP Masquerade\nThis is when the firewall implemented in the kernel (via NAT, or networking address\ntranslation), it allows you to hide a complete network behind one IP address. With this\nfirewall no special compiling is needed as you can access hosts directly.\n\nFor accessing ftp servers behind such firewalls you usually need to set the environment\nvariable \"FTPPASSIVE\" or the config variable ftppassive to a true value.\n" }, { "name": "Configuring lynx or ncftp for going through a firewall", "content": "If you can go through your firewall with e.g. lynx, presumably with a command such as\n\n/usr/local/bin/lynx -pscott:tiger\n\nthen you would configure CPAN.pm with the command\n\no conf lynx \"/usr/local/bin/lynx -pscott:tiger\"\n\nThat's all. Similarly for ncftp or ftp, you would configure something like\n\no conf ncftp \"/usr/bin/ncftp -f /home/scott/ncftplogin.cfg\"\n\nYour mileage may vary...\n" } ] }, "FAQ": { "content": "1) I installed a new version of module X but CPAN keeps saying, I have the old version\ninstalled\n\nProbably you do have the old version installed. This can happen if a module installs itself\ninto a different directory in the @INC path than it was previously installed. This is not\nreally a CPAN.pm problem, you would have the same problem when installing the module\nmanually. The easiest way to prevent this behaviour is to add the argument \"UNINST=1\" to the\n\"make install\" call, and that is why many people add this argument permanently by\nconfiguring\n\no conf makeinstallarg UNINST=1\n\n2) So why is UNINST=1 not the default?\n\nBecause there are people who have their precise expectations about who may install where in\nthe @INC path and who uses which @INC array. In fine tuned environments \"UNINST=1\" can cause\ndamage.\n\n3) I want to clean up my mess, and install a new perl along with all modules I have. How do I\ngo about it?\n\nRun the autobundle command for your old perl and optionally rename the resulting bundle file\n(e.g. Bundle/mybundle.pm), install the new perl with the Configure option prefix, e.g.\n\n./Configure -Dprefix=/usr/local/perl-5.6.78.9\n\nInstall the bundle file you produced in the first step with something like\n\ncpan> install Bundle::mybundle\n\nand you're done.\n\n4) When I install bundles or multiple modules with one command there is too much output to keep\ntrack of.\n\nYou may want to configure something like\n\no conf makearg \"| tee -ai /root/.cpan/logs/make.out\"\no conf makeinstallarg \"| tee -ai /root/.cpan/logs/makeinstall.out\"\n\nso that STDOUT is captured in a file for later inspection.\n\n5) I am not root, how can I install a module in a personal directory?\n\nAs of CPAN 1.9463, if you do not have permission to write the default perl library\ndirectories, CPAN's configuration process will ask you whether you want to bootstrap\n, which makes keeping a personal perl library directory easy.\n\nAnother thing you should bear in mind is that the UNINST parameter can be dangerous when you\nare installing into a private area because you might accidentally remove modules that other\npeople depend on that are not using the private area.\n\n6) How to get a package, unwrap it, and make a change before building it?\n\nHave a look at the \"look\" (!) command.\n\n7) I installed a Bundle and had a couple of fails. When I retried, everything resolved nicely.\nCan this be fixed to work on first try?\n\nThe reason for this is that CPAN does not know the dependencies of all modules when it\nstarts out. To decide about the additional items to install, it just uses data found in the\nMETA.yml file or the generated Makefile. An undetected missing piece breaks the process. But\nit may well be that your Bundle installs some prerequisite later than some depending item\nand thus your second try is able to resolve everything. Please note, CPAN.pm does not know\nthe dependency tree in advance and cannot sort the queue of things to install in a\ntopologically correct order. It resolves perfectly well if all modules declare the\nprerequisites correctly with the PREREQPM attribute to MakeMaker or the \"requires\" stanza\nof Module::Build. For bundles which fail and you need to install often, it is recommended to\nsort the Bundle definition file manually.\n\n8) In our intranet, we have many modules for internal use. How can I integrate these modules\nwith CPAN.pm but without uploading the modules to CPAN?\n\nHave a look at the CPAN::Site module.\n\n9) When I run CPAN's shell, I get an error message about things in my \"/etc/inputrc\" (or\n\"~/.inputrc\") file.\n\nThese are readline issues and can only be fixed by studying readline configuration on your\narchitecture and adjusting the referenced file accordingly. Please make a backup of the\n\"/etc/inputrc\" or \"~/.inputrc\" and edit them. Quite often harmless changes like uppercasing\nor lowercasing some arguments solves the problem.\n\n10) Some authors have strange characters in their names.\n\nInternally CPAN.pm uses the UTF-8 charset. If your terminal is expecting ISO-8859-1 charset,\na converter can be activated by setting termislatin to a true value in your config file.\nOne way of doing so would be\n\ncpan> o conf termislatin 1\n\nIf other charset support is needed, please file a bug report against CPAN.pm at rt.cpan.org\nand describe your needs. Maybe we can extend the support or maybe UTF-8 terminals become\nwidely available.\n\nNote: this config variable is deprecated and will be removed in a future version of CPAN.pm.\nIt will be replaced with the conventions around the family of $LANG and $LC* environment\nvariables.\n\n11) When an install fails for some reason and then I correct the error condition and retry,\nCPAN.pm refuses to install the module, saying \"Already tried without success\".\n\nUse the force pragma like so\n\nforce install Foo::Bar\n\nOr you can use\n\nlook Foo::Bar\n\nand then \"make install\" directly in the subshell.\n\n12) How do I install a \"DEVELOPER RELEASE\" of a module?\n\nBy default, CPAN will install the latest non-developer release of a module. If you want to\ninstall a dev release, you have to specify the partial path starting with the author id to\nthe tarball you wish to install, like so:\n\ncpan> install KWILLIAMS/Module-Build-0.2707.tar.gz\n\nNote that you can use the \"ls\" command to get this path listed.\n\n13) How do I install a module and all its dependencies from the commandline, without being\nprompted for anything, despite my CPAN configuration (or lack thereof)?\n\nCPAN uses ExtUtils::MakeMaker's prompt() function to ask its questions, so if you set the\nPERLMMUSEDEFAULT environment variable, you shouldn't be asked any questions at all\n(assuming the modules you are installing are nice about obeying that variable as well):\n\n% PERLMMUSEDEFAULT=1 perl -MCPAN -e 'install My::Module'\n\n14) How do I create a Module::Build based Build.PL derived from an ExtUtils::MakeMaker focused\nMakefile.PL?\n\nhttp://search.cpan.org/dist/Module-Build-Convert/\n\n15) I'm frequently irritated with the CPAN shell's inability to help me select a good mirror.\n\nCPAN can now help you select a \"good\" mirror, based on which ones have the lowest 'ping'\nround-trip times. From the shell, use the command 'o conf init urllist' and allow CPAN to\nautomatically select mirrors for you.\n\nBeyond that help, the urllist config parameter is yours. You can add and remove sites at\nwill. You should find out which sites have the best up-to-dateness, bandwidth, reliability,\netc. and are topologically close to you. Some people prefer fast downloads, others\nup-to-dateness, others reliability. You decide which to try in which order.\n\nHenk P. Penning maintains a site that collects data about CPAN sites:\n\nhttp://mirrors.cpan.org/\n\nAlso, feel free to play with experimental features. Run\n\no conf init randomizeurllist ftpstatsperiod ftpstatssize\n\nand choose your favorite parameters. After a few downloads running the \"hosts\" command will\nprobably assist you in choosing the best mirror sites.\n\n16) Why do I get asked the same questions every time I start the shell?\n\nYou can make your configuration changes permanent by calling the command \"o conf commit\".\nAlternatively set the \"autocommit\" variable to true by running \"o conf init autocommit\"\nand answering the following question with yes.\n\n17) Older versions of CPAN.pm had the original root directory of all tarballs in the build\ndirectory. Now there are always random characters appended to these directory names. Why was\nthis done?\n\nThe random characters are provided by File::Temp and ensure that each module's individual\nbuild directory is unique. This makes running CPAN.pm in concurrent processes simultaneously\nsafe.\n\n18) Speaking of the build directory. Do I have to clean it up myself?\n\nYou have the choice to set the config variable \"scancache\" to \"never\". Then you must clean\nit up yourself. The other possible values, \"atstart\" and \"atexit\" clean up the build\ndirectory when you start (or more precisely, after the first extraction into the build\ndirectory) or exit the CPAN shell, respectively. If you never start up the CPAN shell, you\nprobably also have to clean up the build directory yourself.\n\n19) How can I switch to sudo instead of local::lib?\n\nThe following 5 environment veriables need to be reset to the previous values: PATH,\nPERL5LIB, PERLLOCALLIBROOT, PERLMBOPT, PERLMMOPT; and these two CPAN.pm config\nvariables must be reconfigured: makeinstallmakecommand and mbuildinstallbuildcommand.\nThe five env variables have probably been overwritten in your $HOME/.bashrc or some\nequivalent. You either find them there and delete their traces and logout/login or you\noverride them temporarily, depending on your exact desire. The two cpanpm config variables\ncan be set with:\n\no conf init /install.*command/\n\nprobably followed by\n\no conf commit\n", "subsections": [] }, "COMPATIBILITY": { "content": "OLD PERL VERSIONS\nCPAN.pm is regularly tested to run under 5.005 and assorted newer versions. It is getting more\nand more difficult to get the minimal prerequisites working on older perls. It is close to\nimpossible to get the whole Bundle::CPAN working there. If you're in the position to have only\nthese old versions, be advised that CPAN is designed to work fine without the Bundle::CPAN\ninstalled.\n\nTo get things going, note that GBARR/Scalar-List-Utils-1.18.tar.gz is compatible with ancient\nperls and that File::Temp is listed as a prerequisite but CPAN has reasonable workarounds if it\nis missing.\n\nCPANPLUS\nThis module and its competitor, the CPANPLUS module, are both much cooler than the other.\nCPAN.pm is older. CPANPLUS was designed to be more modular, but it was never intended to be\ncompatible with CPAN.pm.\n\nCPANMINUS\nIn the year 2010 App::cpanminus was launched as a new approach to a cpan shell with a\nconsiderably smaller footprint. Very cool stuff.\n", "subsections": [] }, "SECURITY ADVICE": { "content": "This software enables you to upgrade software on your computer and so is inherently dangerous\nbecause the newly installed software may contain bugs and may alter the way your computer works\nor even make it unusable. Please consider backing up your data before every upgrade.\n", "subsections": [] }, "BUGS": { "content": "Please report bugs via \n\nBefore submitting a bug, please make sure that the traditional method of building a Perl module\npackage from a shell by following the installation instructions of that package still works in\nyour environment.\n", "subsections": [] }, "AUTHOR": { "content": "Andreas Koenig \"\"\n", "subsections": [] }, "LICENSE": { "content": "This program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee \n", "subsections": [] }, "TRANSLATIONS": { "content": "Kawai,Takanori provides a Japanese translation of a very old version of this manpage at\n\n", "subsections": [] }, "SEE ALSO": { "content": "Many people enter the CPAN shell by running the cpan utility program which is installed in the\nsame directory as perl itself. So if you have this directory in your PATH variable (or some\nequivalent in your operating system) then typing \"cpan\" in a console window will work for you as\nwell. Above that the utility provides several commandline shortcuts.\n\nThe main CPAN website, which includes general information about the service, is at\n.\n\nmelezhik (Alexey) sent me a link where he published a chef recipe to work with CPAN.pm:\nhttp://community.opscode.com/cookbooks/cpan.\n", "subsections": [] } }, "summary": "CPAN - query, download and build perl modules from CPAN sites", "flags": [], "examples": [], "see_also": [] }