24

I can't find an authoritative/comprehensive description of where CPAN installs its files. I assume there must be a set of rules and that it's not as simple as "XYZ directory" because, for example, multiple users on a Linux box can run CPAN even though there's a single Perl installation and it still somehow works. So, what are those rules?

A second part of this question: The documentation for the PERL5LIB environment variable says that it is "A list of directories in which to look for Perl library files before looking in the standard library and the current directory."

I assume that CPAN doesn't install into the standard library location, since presumably that is fixed for a particular Perl version. So maybe CPAN installs into PERL5LIB?

And finally, as I already alluded to, how does CPAN handle the fact that multiple users might be running the same Perl installation? Sorry if that's a separate question but it seems probably related.

Stephen
  • 8,508
  • 12
  • 56
  • 96
  • For such a complicated set of answers I would expect the question to have more up-votes. Has the situation changed since the original answers or is all development now going to Perl6? – stephenmm May 08 '19 at 18:50
  • Update: Seems like cpan has been improved with [cpanm](http://www.cpan.org/modules/INSTALL.html) `cpan App::cpanminus` – stephenmm May 08 '19 at 18:59

3 Answers3

25

First, some background. CPAN doesn't install modules. It's a repository.

cpan doesn't install modules either. cpan downloads distributions from CPAN and runs the installer provided within, be it Makefile.PL or Build.PL. (Same goes for cpanm and cpanp.)

These installation scripts mostly use ExtUtils::MakeMaker or Module::Build to install the distribution (though other installers exist).

Perl specifies three sets of installation locations.

  • perl, for modules included with Perl itself.
  • vendor, for modules installed by the provider of your perl binary.
  • site, for modules installed using cpan.

Each of these sets provides installation locations for a number of files types.

                        Installation location
                        --------------------------------------------------------
Type of file            perl             vendor                 site
----------------------  ---------------  ---------------------  -------------------
Build-specific modules  installarchlib   installvendorarch      installsitearch
Modules                 installprivlib   installvendorlib       installsitelib
Binary programs         installbin       installvendorbin       installsitebin
Other programs          installscript    installvendorscript    installsitescript
man pages for scripts   installman1dir   installvendorman1dir   installsiteman1dir
man pages for modules   installman3dir   installvendorman3dir   installsiteman3dir
html docs for scripts   installhtml1dir  installvendorhtml1dir  installsitehtml1dir
html docs for modules   installhtml3dir  installvendorhtml3dir  installsitehtml3dir

You can obtain the path for any of these locations using the following:

perl -V:{var}        # Substitute `{var}` for the var name.

You can obtain the paths for all of these locations using the following:

perl -V:'install.*'

Those are the defaults use by the installers. However, the two most commonly used installers allow the user doing to installation to override any and all of these. In fact, it's common for people to unknowingly use local::lib to do so.

If a module is installed in a non-standard location,

  • Env var PERL5LIB can be used to let perl know where to find the modules.
  • Env var PATH can be used to let the system know where to find bundled programs.
  • Env var MANPATH can be used to let man know where to find the man pages.
ikegami
  • 367,544
  • 15
  • 269
  • 518
  • 1
    In addition to CPAN-the-repository, there's also CPAN-the-Perl-module (which is what the `cpan` command uses). – melpomene Oct 16 '17 at 21:00
  • Is the table sourced from somewhere or did you write that yourself? – simbabque Oct 17 '17 at 12:59
  • 2
    @simbabque, It's based on the table under the heading `make intstall` in the docs for [ExtUtils::MakeMaker](http://search.cpan.org/perldoc?ExtUtils::MakeMaker) and on the list of variables provided by `perl -V:'install.*'`. – ikegami Jun 27 '20 at 18:41
5

CPAN doesn't actually install files. It runs the install script embedded in each distribution, which then performs the actual install.

For distributions using ExtUtils::MakeMaker, the defaults are documented here: https://metacpan.org/pod/ExtUtils::MakeMaker#make-install (and the default value of INSTALLDIRS is site). For Module::Build, see https://metacpan.org/pod/Module::Build#INSTALL-PATHS.

When the documentation talks about $Config{foo} or %Config, it means the %Config variable provided by the Config module. The value of $Config{foo} can also be inspected by running perl -V:foo.

(If you think this seems unnecessarily complicated, you're right.)

The short version is that perl has multiple "system directories", one of which is for "site specific" modules and thus used as the default installation target. You are right that this is a single directory (per perl install), which doesn't mesh well with a multi-user system: It is shared across all users, and you need root permissions to install modules (and doing so might upgrade/override modules from system packages, which is a bad idea).

What people do instead is to configure ExtUtils::MakeMaker, Module::Build, etc to install into a user's home directory. This can be done with environment variables. Then they tell perl to add this directory to @INC, so modules can actually be found and loaded. This is done with another environment variable, PERL5LIB. (PERL5LIB doesn't affect installation, it's purely used for loading.)

All of the above is automated and encapsulated in local::lib. (local::lib can also be used to e.g. create a per-project module subdirectory.)

The CPAN documentation also says:

As of CPAN 1.9463, if you do not have permission to write the default perl library directories, CPAN's configuration process will ask you whether you want to bootstrap local::lib, which makes keeping a personal perl library directory easy.

You can sidestep the whole issue by installing a private perl in your home directory (in which case the "system" directory is just another subdirectory under your $HOME and thus isn't shared with anyone and can be written to by you). This is very easy with e.g. perlbrew.

Another note: You've just found a bug in the documentation for PERL5LIB. "and the current directory" is outdated: . has been removed from the default list of module locations for security reasons.

melpomene
  • 84,125
  • 8
  • 85
  • 148
  • Thanks, this is helpful. Regarding this: "What people do instead is to configure ExtUtils::MakeMaker, Module::Build, etc to install into a user's home directory" Does local::lib make this redundant? – Stephen Oct 16 '17 at 20:50
  • @Stephen Well, most people use local::lib to do it. :-) local::lib is at its core just an automated way to create some directories and set a handful of environment variables correctly. So yes: if you use local::lib (by adding the magic line to your `.bashrc` or equivalent), you don't need to configure anything else by hand. – melpomene Oct 16 '17 at 20:53
1

This is a complex question. You can tell where core libraries are located by seeking the place of one of them:

perldoc -l B

Will tell you where the B core module is located. And you may try others with different results...

Also, perl -V will tell you all shell variables that matter along with the value of @INC, the places where it will look for libraries.

Core libraries are usually found in different places than local libraries. Also, if you are using perlbrew and local::lib you may have more things to consider. Regarding shell variables, along with PERL5LIB, you also have PERL_LOCAL_LIB_ROOT.

Regarding your other question, I would say that root may install libraries system-wide. Any user will have those and then any local places included by means of shell variables or other means like command line options perl -I <lib location>, or within the code like use lib <lib location>;.

There is also perlbrew that along with local::lib allows a non-privileged user to install Perl and libraries in local directories.

Regarding ways to install modules from CPAN, my favourite is cpanminus. It is invoked with cpanm <library to install>. It never fails...

Javier Elices
  • 2,066
  • 1
  • 16
  • 25