1=head1 Introduction
2
3RT has a lot of core features, but sometimes you have a problem to solve
4that's beyond the scope of just configuration. The standard way to add
5features to RT is with an extension, or plugin -- RT uses the terms
6interchangably.
7
8=head1 Finding extensions
9
10Most of the extensions written by Best Practical (and quite a few
11contributed by the community) are available from CPAN; a L<search for
12RT::Extension|https://metacpan.org/search?q=RT::Extension::> will turn
13up most of them.  The Best Practical website also maintains a list, at
14L<http://www.bestpractical.com/rt/extensions.html>
15
16=head1 Installing extensions
17
18RT extensions should be installed by downloading the C<.tar.gz> file for
19the extensions, extracting it (with C<tar xzf filename.tar.gz>), and
20following the instructions in its included F<README>.
21
22The instructions under C<INSTALLING> in the F<README> always take
23precedence over those found here.  In general, however, the process is
24as follows:
25
26=over
27
28=item 1.
29
30B<Run C<perl Makefile.PL>> to check for dependencies, and minimum
31versions of RT.  If your RT is in an unusual location (not
32C</opt/rt4/>), you may need to set the C<RTHOME> environment variable to
33the root of your RT location.
34
35=item 2.
36
37B<Run C<make>> to prepare the package for installation.
38
39=item 3.
40
41B<Run C<make install>>; you may need to run this step as C<root>, or at
42least a user that has permission to install into RT's directories.
43
44=item 4.
45
46If the extension contains database changes or new queues, scrips,
47templates, or the like, you will need to B<run C<make initdb>> to install
48them.  Not all extensions have database changes, and most of them only
49need this step run when they are first installed, and not on later
50updates.  Refer to the C<INSTALLING> section of the module's
51documentation.
52
53=item 5.
54
55B<Add the plugin to RT's configuration.> By default, newly installed plugins
56are not enabled.  On RT 4.2 and later, each plugin should be enabled by the
57C<Plugin()> command:
58
59    Plugin( 'RT::Extension::Example' );
60    Plugin( 'RT::Extension::Sample' );
61
62
63On RT 4.0, enabling them instead requires adding them to the C<@Plugins>
64configuration:
65
66    Set( @Plugins, 'RT::Extension::Example', 'RT::Extension::Sample' );
67
68=item 6.
69
70B<Configure any additional settings> that the extension requires.  Many
71options that must be set before the plugin can be used.  Read the
72documentation carefully.
73
74=item 7.
75
76Next, B<clear the cache>.  RT caches the files it serves, and installing
77a plugin requires clearing this cache to ensure that the changes are
78served.  This is done by removing files in the
79F</opt/rt4/var/mason_data/obj> directory:
80
81   rm -rf /opt/rt4/var/mason_data/obj
82
83This step may not be necessary if the extension does not affect RT's
84display.
85
86=item 8.
87
88Finally, B<restart your webserver>.  The steps for this will vary from
89webserver to webserver.
90
91=back
92
93Again, the above are generalizations.  The C<README> shipped with the
94extension always takes precedence over the above steps.
95
96
97We do not suggest using the command-line C<cpan> or C<cpanm> client to
98install RT extensions, despite them being available from CPAN.  Those
99command-line clients are not aware of steps 4-8 listed above, and may
100result in an incomplete installation.
101
102=cut
103