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