Upgrade to 4.2.2
[usit-rt.git] / docs / rt_perl.pod
1=head1 Perl for RT
3RT runs on Perl and there are many different approaches to installing
4and maintaining your Perl installation. This document reviews some of the
5options and pros and cons of different approaches.
7Perl has been around for a long time, so many different versions are
8installed on systems everywhere. We try to maintain a reasonable
9timeframe for backward compatibility, but beyond a certain age, running
10old versions of Perl is no longer safe or even possible with modern
11applications. We currently require at least version 5.10.1 which is
12old enough to be default on OSes from many years ago, but sufficiently
13new to support RT and the modules RT depends on.
15=head1 Default System Perls
17All Linux and Unix-type variants come with a version of Perl installed
18and many provide Perl and many CPAN modules as packages for easier
19maintenance and management. You can run RT on the vendor Perl on your
20system as long as it meets the minimum version requirement.
22When you run C<make testdeps> as part of your RT installation,
23you'll likely find that the RT will require you to upgrade some of the
24dependent modules to newer versions than those provided in the
25vendor packages. If you have any IT policy requirements to only use
26vendor packaged versions of software, this might be an issue. If
27so, you can consider installing an RT-only version of Perl.
28See L<"Stand-alone Perl">.
30Occasionally vendors introduce their own changes to their packaged version
31of Perl or modules and these might create issues when running RT.
32Also, the system Perl is also often used by other utilities on the system
33and modifying the default Perl too heavily can introduce issues for these
34other applications which might rely on an older version of a module, for
35example. Consider these factors before modifying your system Perl.
37Many packaging systems restore the system to the official packaged
38version of software when updates are applied. Since a Perl update is
39likely to have many or all packaged Perl modules as dependencies, this
40means an update to the vendor Perl will restore all of the modules you
41upgraded to their previous version. Therefore, if you decide to use
42the vendor Perl on your system, you need to note somewhere that you'll
43need to upgrade RT's dependencies any time the system Perl packages are
44updated. The L<rt-test-dependencies> tool provided in RT's sbin
45directory can help with this.
47=head1 Stand-alone Perl
49To avoid having modules unexpectedly downgraded as described above,
50we typically recommend installing a separate Perl to run RT. In doing so
51you take on the extra responsibility to patch that Perl if necessary,
52but you can plan this work as necessary rather than being surprised if
53RT has issues after a security package update is applied.
55Having a Perl version installed specifically for RT gives you the flexibility
56to upgrade or install a new module if needed to add a new extension or address
57a bug. You can then test just RT and not worry about possible side-effects
58on your system.
60You can install this Perl in an alternate location like C</opt/perl>, or
61to make it clear it's for RT, even C</opt/rt4/perl>. To make future
62upgrades easier, install in a version-specific directory like
63C</opt/perl-5.14.2>, then symlink C</opt/perl> to that directory. This
64makes it easy to switch to a newer version of Perl later by installing
65and just moving the symlink.
67If you install a stand-alone Perl, update your shell to put the path
68of the new C<perl> executable before the system Perl. You may want
69to set this in your shell profile for the user account you use to manage
70RT so you don't accidentally run commands or install modules in the
71wrong Perl installation.
73The following sections describe several approaches to installing a
74stand-alone Perl.
76=head2 Install from Source
78You can download Perl directly from L<http://www.perl.org> and follow
79the installation instructions. Typically this involves running C<Configure>,
80then C<make && make test && sudo make install>. For most installations,
81this C<Configure> command should be sufficient:
83 ./Configure -d -Dprefix=/opt/perl
85You can set the prefix to wherever you want Perl installed. Read the
86documentation provided with the distribution for more options.
88=head2 Perlbrew
90L<Perlbrew|http://perlbrew.pl> is a tool that makes it easy to manage multiple
91Perl installations. Once installed, the C<perlbrew> command provides options to
92build various versions of Perl, switch between version, update installed
93versions, and more.
95By default, C<perlbrew> installs all of its Perls in your C<$HOME> directory. If
96you want to install in an alternate location, you can set the C<PERLBREW_ROOT>
97environment variable:
99 export PERLBREW_ROOT=/opt/perl5
100 curl -kL http://install.perlbrew.pl | bash
102Since C<perlbrew> has a C<switch> command to use different installed Perl
103versions, you don't need to manually manage symlinks as described above.
105=head2 mod_perl
107If you plan to run RT with L<mod_perl|http://perl.apache.org> on a 64-bit system, you
108may need to run Configure with these options:
110 ./Configure -d -Dprefix=/opt/perl -A ccflags=-fPIC
112Then make sure you use your stand-alone perl when building and installing
113mod_perl. You find more details on these flags in the
114L<mod_perl installation documentation|http://perl.apache.org/docs/2.0/user/install/install.html#Prerequisites>.
116=head1 CPAN Modules
118RT requires modules from the
119L<Comprehensive Perl Archive Network|http://www.cpan.org> to run.
120Below are a few of the tools available to help download and install
121these modules from CPAN. These tools can work with RT's L<rt-test-dependencies>
122tool and the C<make testdeps> and C<make fixdeps> part of the installation
123process to get these modules installed.
125=head2 CPAN Shell
127The traditional tool for managing Perl modules is the CPAN shell,
128accessed with the C<cpan> command installed as part of Perl. To set up
129C<cpan> on an initial install, run the C<cpan> command and follow the
130prompts to set the initial configuration. You can set each option or allow
131it to automatically set some sensible defaults.
133The main options you'll need to set are the list of download servers and
134options for C<make install>. For download servers, you'll typically want to
135select some mirrors geographically close to you. If you typically run installs
136using C<sudo>, set C<make_install_make_command> to C<'sudo make'> and
137C<mbuild_install_build_command> to C<'sudo ./Build'>. Then install
138the CPAN bundle:
140 cpan>install Bundle::CPAN
142This installs some additional modules to add features to C<cpan>.
144Once you finish this initialization, RT's C<make fixdeps> should be able
145to handle the rest. Any time you need to install a new module or upgrade
146a module, you can just type C<cpan> and manage it from the cpan shell.
148=head2 cpanminus
150C<cpanminus>, or C<cpanm>, is a utility built to make it as easy as possible
151to install modules from CPAN. You can install the L<App::cpanminus> module
152itself from CPAN, or have it install itself:
154 curl -L http://cpanmin.us | perl - --sudo App::cpanminus
156Once installed, set the C<RT_FIX_DEPS_CMD> environment variable to
157have RT use C<cpanm> to install modules:
159 export RT_FIX_DEPS_CMD=/opt/perl/bin/cpanm
161Then run C<make fixdeps> and let RT install all of its dependencies.