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 live 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 here
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
$ 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).
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.