New ActivePerl Directory Structure

ActivePerl Directory Structure

THIS FILE IS OUT OF DATE!

- New ActivePerl Directory Structure

- Introduction
- Potential Users
- The possibilities
- The New Directory Structure
- Multiple Versions and Architectures
- Installing Modules in a Different sitelib
- Some additional information
- Conclusion

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

ActivePerl Directory Structure