New ActivePerl Directory Structure

Introduction

This document describes the new ActivePerl directory structure, and how to use it, and how to maniuplate @INC, to make it work better for you.

ActiveState has received numerous comments and requests concerning the directory structure of ActivePerl. With the newly designed installation directory structure and building of @INC, we worked on addressing the following issues:

Allow for installation of multiple simultaneous versions
Allow for installation of multiple architectures, such as perl OBJECT and perl THREAD
Preserve the site libraries among installations
Allow for networked installations with shared lib and site directories
Allow for easy upgrading of ActivePerl releases

Potential Users

In determining our options we have tried to consider the position of the following groups of users:

Web Developers
Small-site System Administrators
Module/Extension Developers
Perl Developers
Large-site System Administrators / Enterprise Admins

The possibilities

The following possibilities were considered:

The core gets installed into a version, subversion, patch specific sub directory of the perl root
The core gets installed into a version and subversion specific sub directory of the perl root
The core gets installed into any directory the user desires
Perl executables are subdivided into architecture and non-architecture dependent directories
Perl executables are all installed in the same directory
sitelib is installed at the same level as lib or as a subdirectory of lib
sitelib is installed outside or at a level above lib
sitelib has version, subversion, patch specific sub directory
sitelib has version, subversion specific sub directory
sitelib has no version specific directories in the path

Essentially these options are all the same. What it means for you is, "Where do you want to install?"

Our solution supports all of these configurations.

The New Directory Structure

With earlier builds, we followed the core directory structure which gave us directories such as c:\perl\5.00502\bin\mswin32-x86-object. This is good for people who have a need for multiple versions or types of perl installed at a time. We quickly found that the Win32 public didn't like this at all, except for a rare few who actually used and needed this. People decided they wanted a plain old c:\perl\bin\perl.exe just like they were used to, fewer characters in their PATH, site libraries that were in a directory not dependent on a version, and architecture depended libraries worked in with the regular libraries where they could find them. As a result, we have simplified the directory structure significantly.

We are now using the following default directory structure:

 c:\perl
    bin                     ... all perl binaries and util scripts
    lib                     ... core modules
    site
       lib                  ... default site modules location

This is like what people are accustomed to from previous versions of Perl for Win32 and from the GSAR port of 5.004. However, if more explicit directory names are called for, you can still implement them as described below. If you are new to perl, or don't need anything more complicated than this, then just installing using ``c:\perl'' (or ``d:\perl'' for you NT multibooters) is simplified and things are where you have asked for them to be.

Multiple Versions and Architectures

On the other hand, you can still support the versioned installs like 500-502 were, to support multiple simultaneous versions. If you want multiple Perl versions installed you can change 'c:\perl' to 'c:\perl\whatever' when you install.

Installation 1:

    c:\perl\
        bin                                 ... all perl binaries and util scripts
        lib                                 ... core modules
        site
           lib                              ... default site modules location

Installation 2:

    c:\perl\
       site 
           lib                              ... default site modules location
       5.00501-thread
           bin                              ... all perl binaries and util scripts
           lib                              ... core modules

Shared site:

    c:\perl
        site
           lib                              ... global site modules location
        5.005
           bin
           lib
        5.00501
           bin
           lib
        5.00501-thread
           bin
           lib

The ActivePerl installer recognizes if you are installing in a <version>.<sub-version>* specific directory, and automatically moves site up a level so that you can share your site libraries between versions. If you want to change this default location, you have to set the following system registry values:

    \\HKLM\Software\Perl
        lib-5.005=c:\perl\site\lib

    \\HKLM\Software\Perl
        lib-5.00501=c:\perl\site\lib

or set PERL5LIB in your environment.

You can use this method to reset your perl system to use a site directory shared across a network for multiple workstations.

Installing Modules in a Different sitelib

If you want PPM to install into a different site lib, you need to set the following values in 'Config.pm':

    installsitelib='c:\Perl\site\lib'
    installarchlib='c:\Perl\site\lib\arch' (if using arch-specific dir)

If you don't use PPM, which you may well not if you are a module developer, you can pass the LIB parameter to 'perl makefile.pl LIB=c:\perl\site\lib'.

Some additional information

Additional suggestions have been submitted regarding the architecture specific directory for binaries in the core tree. Most people would like to see everything go into 'c:\perl\bin'.

The default directory structure for an ActivePerl installation is as follows

    c:\perl
       bin
       lib
       site
         lib

If you install ActivePerl into a directory such as 'c:\perl\5.005', the directory structure will be as follows

    c:\perl
       5.005
         bin
         lib
       site
         lib

@INC can be configured by modifying the following values:

    PERLLIB environment variable
    PERL5LIB environment variable
    \\HKLM\Software\Perl\lib-<version>
    \\HKLM\Software\Perl\sitelib-<version>
    \\HKLM\Software\Perl\lib
    \\HKLM\Software\Perl\sitelib

In the algorithm for building @INC we define the following values:

$Reg_Lib_Version = the actual value of \\HKLM\Software\Perl\lib-{$]}
$Reg_Site_Version = the actual value of \\HKLM\Software\Perl\sitelib-{$]}
$Reg_Lib = the actual value of \\HKLM\Software\Perl\lib
$Reg_Site = the actual value of \\HKLM\Software\Perl\sitelib
$Perl_Dir = the directory into which Perl was installed and contains 'bin' and 'lib' directories
$Arch = Perl architecture ex. 'MSWin32-x86-object', 'MSWin32-ALPHA-object'
$] = the Perl variable containing Perl's version, sub-version and patch level
$Perl_Version = Complete Perl <version>.<sub-version> with no patch level, for example: $Perl_Version == 5.005 for Perl 5.005_02

The algorithm for building @INC is as follows (this shows precedence):

    # This gets rid of a version in the path if one exists
    ($Perl_Site) = ($Perl_Dir =~ /(.*?)(?:[\/\\]$Perl_Version.*)?$/);
    $Perl_Site .= '/site';

    push @INC, split /;/, ($ENV{PERL5LIB} || $ENV{PERLLIB});
    push @INC, split /;/, ($Reg_Lib_Version || $Reg_Lib);
    push @INC, ("$Perl_Dir/lib/$Arch", "$Perl_Dir/lib);
    push @INC, ("$Perl_Site/$]/lib/$Arch", "$Perl_Site/$]/lib");
    push @INC, split /;/, ($Reg_Site_Version || $Reg_Site);
    push @INC, ("$Perl_Site/lib/$Arch", "$Perl_Site/lib");
    push @INC, '.';

Of course if a directory does not exist it does not get added to @INC.

Conclusion

We hope that this simplified directory structure, and the ability to easily reconfigure the installation locations, greatly improves your ability to use ActivePerl to the fullest. Enjoy!

We welcome comments and suggestions.

New ActivePerl Directory Structure