X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2Fdocs%2Frt_perl.pod;fp=rt%2Fdocs%2Frt_perl.pod;h=513bb596f71022091bbf25638ed39d326803ecd6;hp=0000000000000000000000000000000000000000;hb=1c538bfabc2cd31f27067505f0c3d1a46cba6ef0;hpb=4f5619288413a185e9933088d9dd8c5afbc55dfa diff --git a/rt/docs/rt_perl.pod b/rt/docs/rt_perl.pod new file mode 100644 index 000000000..513bb596f --- /dev/null +++ b/rt/docs/rt_perl.pod @@ -0,0 +1,163 @@ +=head1 Perl for RT + +RT runs on Perl and there are many different approaches to installing +and maintaining your Perl installation. This document reviews some of the +options and pros and cons of different approaches. + +Perl has been around for a long time, so many different versions are +installed on systems everywhere. We try to maintain a reasonable +timeframe for backward compatibility, but beyond a certain age, running +old versions of Perl is no longer safe or even possible with modern +applications. We currently require at least version 5.10.1 which is +old enough to be default on OSes from many years ago, but sufficiently +new to support RT and the modules RT depends on. + +=head1 Default System Perls + +All Linux and Unix-type variants come with a version of Perl installed +and many provide Perl and many CPAN modules as packages for easier +maintenance and management. You can run RT on the vendor Perl on your +system as long as it meets the minimum version requirement. + +When you run C as part of your RT installation, +you'll likely find that the RT will require you to upgrade some of the +dependent modules to newer versions than those provided in the +vendor packages. If you have any IT policy requirements to only use +vendor packaged versions of software, this might be an issue. If +so, you can consider installing an RT-only version of Perl. +See L<"Stand-alone Perl">. + +Occasionally vendors introduce their own changes to their packaged version +of Perl or modules and these might create issues when running RT. +Also, the system Perl is also often used by other utilities on the system +and modifying the default Perl too heavily can introduce issues for these +other applications which might rely on an older version of a module, for +example. Consider these factors before modifying your system Perl. + +Many packaging systems restore the system to the official packaged +version of software when updates are applied. Since a Perl update is +likely to have many or all packaged Perl modules as dependencies, this +means an update to the vendor Perl will restore all of the modules you +upgraded to their previous version. Therefore, if you decide to use +the vendor Perl on your system, you need to note somewhere that you'll +need to upgrade RT's dependencies any time the system Perl packages are +updated. The L tool provided in RT's sbin +directory can help with this. + +=head1 Stand-alone Perl + +To avoid having modules unexpectedly downgraded as described above, +we typically recommend installing a separate Perl to run RT. In doing so +you take on the extra responsibility to patch that Perl if necessary, +but you can plan this work as necessary rather than being surprised if +RT has issues after a security package update is applied. + +Having a Perl version installed specifically for RT gives you the flexibility +to upgrade or install a new module if needed to add a new extension or address +a bug. You can then test just RT and not worry about possible side-effects +on your system. + +You can install this Perl in an alternate location like C, or +to make it clear it's for RT, even C. To make future +upgrades easier, install in a version-specific directory like +C, then symlink C to that directory. This +makes it easy to switch to a newer version of Perl later by installing +and just moving the symlink. + +If you install a stand-alone Perl, update your shell to put the path +of the new C executable before the system Perl. You may want +to set this in your shell profile for the user account you use to manage +RT so you don't accidentally run commands or install modules in the +wrong Perl installation. + +The following sections describe several approaches to installing a +stand-alone Perl. + +=head2 Install from Source + +You can download Perl directly from L and follow +the installation instructions. Typically this involves running C, +then C. For most installations, +this C command should be sufficient: + + ./Configure -d -Dprefix=/opt/perl + +You can set the prefix to wherever you want Perl installed. Read the +documentation provided with the distribution for more options. + +=head2 Perlbrew + +L is a tool that makes it easy to manage multiple +Perl installations. Once installed, the C command provides options to +build various versions of Perl, switch between version, update installed +versions, and more. + +By default, C installs all of its Perls in your C<$HOME> directory. If +you want to install in an alternate location, you can set the C +environment variable: + + export PERLBREW_ROOT=/opt/perl5 + curl -kL http://install.perlbrew.pl | bash + +Since C has a C command to use different installed Perl +versions, you don't need to manually manage symlinks as described above. + +=head2 mod_perl + +If you plan to run RT with L on a 64-bit system, you +may need to run Configure with these options: + + ./Configure -d -Dprefix=/opt/perl -A ccflags=-fPIC + +Then make sure you use your stand-alone perl when building and installing +mod_perl. You find more details on these flags in the +L. + +=head1 CPAN Modules + +RT requires modules from the +L to run. +Below are a few of the tools available to help download and install +these modules from CPAN. These tools can work with RT's L +tool and the C and C part of the installation +process to get these modules installed. + +=head2 CPAN Shell + +The traditional tool for managing Perl modules is the CPAN shell, +accessed with the C command installed as part of Perl. To set up +C on an initial install, run the C command and follow the +prompts to set the initial configuration. You can set each option or allow +it to automatically set some sensible defaults. + +The main options you'll need to set are the list of download servers and +options for C. For download servers, you'll typically want to +select some mirrors geographically close to you. If you typically run installs +using C, set C to C<'sudo make'> and +C to C<'sudo ./Build'>. Then install +the CPAN bundle: + + cpan>install Bundle::CPAN + +This installs some additional modules to add features to C. + +Once you finish this initialization, RT's C should be able +to handle the rest. Any time you need to install a new module or upgrade +a module, you can just type C and manage it from the cpan shell. + +=head2 cpanminus + +C, or C, is a utility built to make it as easy as possible +to install modules from CPAN. You can install the L module +itself from CPAN, or have it install itself: + + curl -L http://cpanmin.us | perl - --sudo App::cpanminus + +Once installed, set the C environment variable to +have RT use C to install modules: + + export RT_FIX_DEPS_CMD=/opt/perl/bin/cpanm + +Then run C and let RT install all of its dependencies. + +=cut