[Rt-commit] rt branch, 4.2/installing-extensions, created. rt-4.2.9-54-g49b45be

Alex Vandiver alexmv at bestpractical.com
Fri Dec 12 13:03:40 EST 2014

The branch, 4.2/installing-extensions has been created
        at  49b45befb195ff244359dd752f9fa1065fd96523 (commit)

- Log -----------------------------------------------------------------
commit 49b45befb195ff244359dd752f9fa1065fd96523
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Fri Dec 12 13:03:22 2014 -0500

    Add documentation on finding and installing plugins

diff --git a/docs/extensions.pod b/docs/extensions.pod
new file mode 100644
index 0000000..3df27e7
--- /dev/null
+++ b/docs/extensions.pod
@@ -0,0 +1,100 @@
+=head1 Introduction
+RT has a lot of core features, but sometimes you have a problem to solve
+that's beyond the scope of just configuration. The standard way to add
+features to RT is with an extension, or plugin -- RT uses the terms
+=head1 Finding extensions
+Most of the extensions written by Best Practical (and quite a few
+contributed by the community) are available from CPAN; a L<search for
+RT::Extension|https://metacpan.org/search?q=RT::Extension::>.  The Best
+Practical website also maintains a list, at
+=head1 Installing extensions
+RT extensions should be installed by downloading the C<.tar.gz> file for
+the extensions, extracting it (with C<tar xzf filename.tar.gz>), and
+following the instructions in its included F<README>.
+The instructions under C<INSTALLING> in the F<README> always take
+precedence over those found here.  In general, however, the process is
+as follows:
+=item 1.
+B<Run C<perl Makefile.PL>> to check for dependencies, and minimum
+versions of RT.  If your RT is in an unusual location (not
+C</opt/rt4/>), you may need to set the C<RTHOME> environment variable to
+the root of your RT location.
+=item 2.
+B<Run C<make>> to prepare the package for installation
+=item 3.
+B<Run C<make install>>; you may need to run this step as C<root>, or at
+least a user that has permission to install into RT's directories.
+=item 4.
+If the extension contains database changes or new queues, scrips,
+templates, or the like, you will need to B<run C<make initdb>> to install
+them.  Not all extensions have database changes, and most of them only
+need this step run when they are first installed, and not on later
+updates.  Refer to the C<INSTALLING> section of the module's
+=item 5.
+B<Add the plugin to RT's configuration.>  By default, newly installed
+plugins are not enabled.  On RT 4.0, enabling them requires adding them
+to the C<@Plugins> configuration:
+    Set( @Plugins, 'RT::Extension::Example', 'RT::Extension::Sample' );
+On RT 4.2, each plugin can instead be enabled by the C<Plugin()> command:
+    Plugin( 'RT::Extension::Example' );
+    Plugin( 'RT::Extension::Sample' );
+=item 6.
+B<Configure any additional settings> that the extension requires.  Many
+options that must be set before the plugin can be used.  Read the
+documentation carefully.
+=item 7.
+Next, B<clear the cache>.  RT caches the files it serves, and installing
+a plugin requires clearing this cache to ensure that the changes are
+served.  This is done by removing files in the
+F</opt/rt4/var/mason_data/obj> directory:
+   rm -rf /opt/rt4/var/mason_data/obj
+This step may not be necessary if the extension does not affect RT's
+=item 8.
+Finally, B<restart your webserver>.  The steps for this will vary from
+webserver to webserver.
+Again, the above are generalizations.  The C<README> shipped with the
+extension always takes precedence over the above steps.
+We do not suggest using the command-line C<cpan> or C<cpanm> client to
+install RT extensions, despite them being available from CPAN.  Those
+command-line clients are not aware of steps 4-8 listed above, and may
+result in an incomplete installation.


More information about the rt-commit mailing list