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.

Using Perlbrew

CPAN:perlbrew makes life pretty easy for:

1. Installing your personal Perl, e.g. in the home directory.
2. 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:

$ cd
$ 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 could 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 cpanminus ( cpanm ) This package just seems to work, no configuration needed, no q&a. It just works.

• 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.

CPANPLUS

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
$ cpanp
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

CPAN

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.

$ cpan
Accepted automatic configuration and quit.
$ cp -rp .cpan .cpan-5.12.2
$ cpan
        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
        q
$ 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:

1. Changing the shebang line of all related Foswiki scripts.
2. 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 foswiki/bin and foswiki/tools directory.

This change can be done manually but there is also the script rewriteshbang.pl available in foswiki/tools. It could be manually run with the local Perl using e.g.:

$ cd foswiki/tools
$ ~/perl5/perlbrew/bin/perl rewriteshbang.pl
or
$ ~/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
~/perl5/perlbrew/bin/perl

After adjusting at least the shebang line of foswiki/bin/configure, 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).

Adjusting LocalLib.cfg

LocalLib.cfg resides in foswiki/bin. Open it and configure it as required. At least $foswikiLibPath 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.