rt/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