How To Use Foswiki With Local Perl Installation
This is mainly for users who are installing Foswiki in a non-root environment and want to use their own Perl
installation in addition to installing CPAN modules. If only additional CPAN modules are required while still using the system wide Perl, then looking at HowToInstallCpanModules
is probably the better article.
makes life pretty easy for:
- Installing your personal Perl, e.g. in the home directory.
- Switching between different Perl installations, so the related Perl environment is automatically changed with just a single command.
Further on a detailed installation log is given but it is best to follow instructions at CPAN.
Perlbrew Installation Example
The line of commands used to install perlbrew 0.10 and the first local Perl:
$ curl -LO http://xrl.us/perlbrew
$ ./perlbrew install
$ rm -i ~/perlbrew
$ cd ~/perl5/perlbrew/bin
$ ./perlbrew init
Follow instructions about adding a line to ~/.bashrc
List which versions of perl are available for installation:
$ perlbrew available
$ perlbrew available --all
Install a version of perl:
$ perlbrew install perl-5.12.2
Use "$ perlbrew --force install perl-5.12.2" in case of errors which e.g. just might be caused by missing write permissions on some files.
$ perlbrew switch perl-5.12.2
Now the new perl is active in the environment of the active user.
$ perl -v
$ perl -V
Integrating CPAN Modules
There are many ways how you may want to handle additional CPAN modules as related to the local Perl installation. One way might be using local::lib
and another way coud be to just install the modules directly into the local Perl location(s).
Perlbrew and CPANMinus
The current recommended way of installing cpan modules with perlbrew is to use
) This package just seems to work, no configuration needed, no q&a. It
- Switch to an installed perl and install cpanm
$ perlbrew switch perl-5.12.5
$ curl -L http://cpanmin.us | perl - App::cpanminus
- Update all cpan modules to their latest versions
- When building a perl version, the core cpan modules that were "then current" are built. New versions of many of these modules may have been released since that particular version of perl. If you want to run with the very latest modules rather than the versions shipped with the selected version of perl, use the below commands to:
- Install App::cpanoutdated (this installs/updates a number of packages - 29 on perl 5.12.5. But still reports 108 packages out of date)
- List all outdated packages ... and if desired
- Update all outdated packages with cpanm
$ perlbrew switch perl-5.12.5
$ cpanm App::cpanoutdated
$ cpan-outdated (use -p flag to list them by perl module rather than distribution file)
$ cpan-outdated | cpanm
- Install foswiki required modules
$ cpanm HTML::Entities
$ cpanm HTML::Tree
$ cpanm Net::SMTP::SSL
$ cpanm Authen::SASL
$ cpanm CGI::Session
CPAN Modules in the Local Perl Location
The following setup example puts all the CPAN modules into the local Perl location(s). In case of switching the activated Perl then related CPAN modules will also be changed, hence Modules and Perl version(s) are tight together for each specific Perl version while clearly separated when it comes to different Perl versions.
This example uses a link that must be manually changed when switching the to another perlbrew based Perl. It might also be possible to configure CPANPLUS to reside inside the related Perl version, so that adjusting this link wouldn't be required.
$ mkdir .cpanplus-5.12.2
$ rm .cpanplus
$ ln -s .cpanplus-5.12.2 .cpanplus
CPAN Terminal> s selfupdate all
CPAN Terminal> i Test::Pod
CPAN Terminal> i Test::Pod::Coverage
CPAN Terminal> i YAML
CPAN Terminal> i LWP
CPAN Terminal> i Bundle::CPAN
CPAN Terminal> s reconfigure (5 - made verbose and use GPG, 7 - local mirrors)
CPAN Terminal> o (updated/re-installed everything reported)
CPAN Terminal> q
For CPAN the configuration resides directly in the related Perl location, hence when switching via perlbrew the related CPAN configuration will also change. Configuring the .cpan directory for each Perl version will also separate the source and build directories as related to the current Perl.
Accepted automatic configuration and quit.
$ cp -rp .cpan .cpan-5.12.2
o conf build_dir ~/.cpan-5.12.2/build
o conf cpan_home ~/.cpan-5.12.2
o conf histfile ~/.cpan-5.12.2/histfile
o conf keep_source_where ~/.cpan-5.12.2/sources
o conf prefs_dir ~/.cpan-5.12.2/prefs
o conf commit
$ perldoc perllocal
Using Foswiki with a Local Perl
There are two main configurations to be done in order to get Foswiki fully aligned with the local perl installation while ignoring whatever else might be available in the system:
- Changing the shebang line of all related Foswiki scripts.
- Adjusting LocalLib.cfg as required.
Adjusting the Shebang Line
As long as the shebang
line is not pointing to your new local Perl installation, the @INC path will still hold the paths of the system wide Perl installation. But now there shouldn't remain a fraction of whatever else the system may provide by default, so we go and change the shebang line in front of all Perl scripts residing in the
This change can be done manually but there is also the script
. It could be manually run with the local Perl using e.g.:
$ cd foswiki/tools
$ ~/perl5/perlbrew/bin/perl rewriteshbang.pl
$ ~/perl5/perlbrew/perls/current/bin/perl rewriteshbang.pl
$ ls -l perl5/perlbrew/bin/perl
lrwxrwxrwx 1 <USER> <GROUP> 57 Sep 20 12:41 perl5/perlbrew/bin/perl -> /home/<USER>/perl5/perlbrew/perls/current/bin/perl5.12.2
But this isn't required since most likely perlbrew already switched to the local Perl:
$ which perl
After adjusting at least the shebang line of
, one can see the @INC paths used by Foswiki under configure
(Foswiki 1.0.x: CGI Setup > @INC library path
, 1.1.x: Web Server Environment > @INC library path
. Open it and configure it as required. At least
should be defined. All other settings are mostly relevant in case you are separating the path(s) where CPAN modules are installed from the used Perl installation.