Installing the Template Toolkit - Perl

At any one time you can download from the Web at least two possible versions of the Template Toolkit: a stable version and a developer version. The stable version has a version number such as 2.10, and has been widely tested before release. The developer versions have version numbers such as 2.10a, and typically have bug fixes and early implementations of new features. Generally, you should install the latest stable release.

The Template Toolkit is available from the Comprehensive Perl Archive Network (CPAN). You can always download the most recent stable version of the Template Toolkit from http://search.cpan.org/dist/Template-Toolkit/ (which is where most people download it).

In addition, a web site is dedicated to the Template Toolkit. Located at http://www.template-toolkit.org, this site offers the latest stable version, as well as a number of other goodies such as native packages of the Template Toolkit for Debian GNU/Linux, Mac OS X (for installation using Fink), and Microsoft Windows (for installation using ActiveState’s Perl Package Manager).

You can also get developer versions of the Template Toolkit from the web site. Normally, you need to download only the current stable version, but if you come across a bug that isn’t fixed in the CPAN version, you may need to use a developer release.

If a developer release isn’t cutting-edge enough for you, the web site contains information on how to get access to the CVS repository, which is where the very latest versions of the Template Toolkit source code are kept. If you want to add functionality to the Template Toolkit or have found a bug that you can fix, and you want your patch to be accepted by Template Toolkit developers, you should make your changes against the current CVS HEAD.

Installing the Template Toolkit is like installing any other Perl module (see perlmodinstall(1) for platform-specific details). The basic idea is as follows:

$ perl Makefile.PL
$ make
$ make test
$ make install

A few optional modules and pages of documentation come with the Template Toolkit, and how much of that gets installed is controlled by arguments to perl Makefile.PL. Run perl Makefile.PL TT_HELP to get the following full list of options:

The following options can be specified as command-line arguments to 'perl Makefile.PL'. e.g.,

perl Makefile.PL TT_PREFIX=/my/tt2/dir TT_ACCEPT=y

TT_PREFIX        installation prefix    (/usr/local/tt2)
TT_IMAGES        images URL             (/tt2/images) T_DOCS           build HTML docs        (y)
TT_SPLASH        use Splash! for docs   (y)
TT_THEME         Splash! theme          (default)
TT_EXAMPLES      build HTML examples    (y)
TT_EXTRAS        install optional extras(y)
TT_XS_ENABLE     Enable XS Stash        (y)
TT_XS_DEFAULT    Use XS Stash by default(y)
TT_DBI           run DBI tests         (y if DBI installed)
TT_LATEX         install LaTeX filter  (y if LaTeX found)TT_LATEX_PATH    path to latex         (system dependant)TT_PDFLATEX_PATH path to pdflatex      ( "     "     " )
TT_DVIPS_PATH    path to dvips         ( "     "     " )
TT_QUIET         no messages           (n)
TT_ACCEPT        acceptdefaults        (n)

By default, the Makefile.PL runs in interactive mode, prompting for confirmation of the various configuration options. Setting the TT_ACCEPT option causes the default value (possibly modified by other command line options) to be accepted. The TT_QUIET option can also be set to suppress the prompt messages.

The make test step is important, especially if you’re using a developer release or version from CVS. Over 2,000 tests are provided with the Template Toolkit to ensure that everything works as expected, and to let you know about any problems that you might have. It takes no more than a minute or so to run the tests, and they can save you a great deal of debugging time in the unlikely event that something is wrong with your installation.

Test failures don’t necessarily indicate that something is fatally wrong. A serious problem causes nearly all of the tests to fail, although we haven’t heard of that happening to anyone for quite some time. More often than not, errors raised in the test suite come from plugin modules whose external Perl modules are not installed on your system or are the wrong version.

This kind of problem is rarely serious. At worst, it may mean that a particular plugin doesn’t work as expected—or at all—but that won’t stop the rest of the Template Toolkit from doing its job. You can usually solve the problem by installing the latest version of any dependent modules. If you are unsure about whether a particular test failure is significant, ask on the mailing list, or check the mailing list archives mentioned in the “Accessing the Mailing List” section, later in this chapter. Major problems tend to be reported by many people.

The README and INSTALL files in the Template Toolkit distribution directory provide further information about running the test suite and what to do if something goes wrong.  

If you've enjoyed what you've seen here, or to get more information, click on the "Buy the book!" graphic. Pick up a copy today! Visit the O'Reilly Network http://www.oreillynet.com for more online content.