1 2 Template Toolkit 3 4 Version 2.24 5 6 February 2012 7 8 Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved 9 10 This is free software; you can redistribute it and/or 11 modify it under the same terms as Perl itself. 12 13QUICK INSTALL 14------------- 15 16If you have the CPAN module installed then you can install the Template 17Toolkit like this from the command line: 18 19 $ cpan Template 20 21Otherwise you can install from source code. The latest version of the Template 22Toolkit can be retrieved from: 23 24 http://www.cpan.org/modules/by-module/Template/ 25 26Fetch and install AppConfig 1.56 if you don't already have it installed. 27Available from CPAN in: 28 29 http://www.cpan.org/authors/Andy_Wardley/ 30 31To install the Template Toolkit from the command line: 32 33 $ tar zxf Template-Toolkit-2.24.tar.gz 34 $ cd Template-Toolkit-2.24 35 $ perl Makefile.PL 36 $ make 37 $ make test 38 $ make install 39 40The Makefile.PL will prompt for any additional configuration options. 41 42For further details, see the sections below on CONFIGURATION, BUILDING 43AND TESTING, and INSTALLATION. The Template Toolkit web site also has 44further information about installation. 45 46 http://template-toolkit.org/download/index.html 47 48 49PREREQUISITES 50------------- 51 52The Template Toolkit is written entirely in Perl and should run on any 53platform on which Perl is available. It requires Perl 5.006 or later. 54 55The 'ttree' utility uses the AppConfig module (version 1.56 or above) 56for parsing command line options and configuration files. It is 57available from CPAN: 58 59 http://www.cpan.org/authors/Andy_Wardley/ 60 61The Template Toolkit implements a "plugin" architecture which allow 62you to incorporate the functionality of virtually any Perl module into 63your templates. A number of plugin modules are included with the 64distribution for adding extra functionality or interfacing to external 65CPAN modules. You don't need to install any of these external modules 66unless you plan to use those particular plugins. See Template::Plugins 67and Template::Manual::Plugins for further details. 68 69 70OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT 71--------------------------------------------- 72 73The latest release version of the Template Toolkit can be downloaded 74from any CPAN site: 75 76 http://www.cpan.org/modules/by-module/Template/ 77 78Interim and development versions may also be available, along with 79other useful information, news, publications, mailing list archives, 80etc., from the Template Toolkit web site: 81 82 http://template-toolkit.org/ 83 84The Template Toolkit is distributed as a gzipped tar archive file: 85 86 Template-Toolkit-<version>.tar.gz 87 88where <version> represents the current version number, e.g. 2.24. 89 90To install the Template Toolkit, unpack the distribution archive to 91create an installation directory. Something like this: 92 93 $ tar zxf Template-Toolkit-2.24.tar.gz 94or 95 $ gunzip Template-Toolkit-2.24.tar.gz 96 $ tar xf Template-Toolkit-2.24.tar 97 98You can then 'cd' into the directory created, 99 100 $ cd Template-Toolkit-2.24 101 102and perform the usual Perl installation procedure: 103 104 $ perl Makefile.PL 105 $ make 106 $ make test 107 $ make install # may need root access 108 109The Makefile.PL performs various sanity checks and then prompts for a 110number of configuration items. The following CONFIGURATION section 111covers this in greater detail. 112 113If you choose to install the optional components then you may need to 114perform some post-installation steps to ensure that the template 115libraries, HTML documentation and examples can be correctly viewed via 116your web browser. The INSTALLATION section covers this. 117 118 119INSTALLING ON MICROSOFT WIN32 PLATFORMS 120--------------------------------------- 121 122For advice on using Perl under Microsoft Windows, have a look here: 123 124 http://win32.perl.org/ 125 126If you're using Strawberry Perl then you can install the Template 127Toolkit using the CPAN module as described above. 128 129If you're using ActivePerl then you can install it using the Perl Package 130Manager (ppm) with the pre-compiled packages built by Chris Winters. For 131further details, see: 132 133 http://openinteract.sourceforge.net/ 134 http://activestate.com/ 135 136If you prefer, you can manually install the Template Toolkit on Win32 137systems by following the instructions in this installation guide. 138However, please note that you are likely to encounter problems using 139'make' and should instead download and use 'nmake' as a replacement. 140This is available from Microsoft's ftp site. 141 142 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe 143 144In this case, you should substitute 'nmake' for 'make' in all the 145instructions contained herein. 146 147 148CONFIGURATION 149------------- 150 151This section covers the configuration of the Template Toolkit via 152the Makefile.PL program. If you've successfully run this and didn't 153have any problems answering any of the questions then you probably 154don't need to read this section. 155 156The Makefile.PL Perl program performs the module configuration and 157generates the Makefile which can then be used to build, test and 158install the Template Toolkit. 159 160 $ perl Makefile.PL 161 162The Template Toolkit now boasts a high-speed implementation of 163Template::Stash written in XS. You can choose to build this as 164an optional module for using explicitly as an alternative to 165the regular pure-perl stash module. In additional, you can opt 166to use the XS Stash as the default, typically making the Template 167Toolkit run twice as fast! 168 169When prompted, answer 'y' or 'n' to build and optionally use 170the XS Stash module by default: 171 172 Do you want to build the XS Stash module? [y] 173 Do you want to use the XS Stash for all Templates? [n] 174 175BUILDING AND TESTING 176-------------------- 177 178This section describes the "make" and "make test" commands which build 179and test the Template Toolkit. If you ran these without incident, 180then you can probably skip this section. 181 182The 'make' command will build the Template Toolkit modules in the 183usual manner. 184 185 make 186 187The 'make test' command runs the test scripts in the 't' subdirectory. 188 189 make test 190 191You can set the TEST_VERBOSE flag when running 'make test' to see the 192results of the individual tests: 193 194 make test TEST_VERBOSE=1 195 196 197INSTALLATION 198------------ 199 200This section describes the final installation of the Template Toolkit 201via the "make install" and covers any additional steps you may need to 202take if you opted to build the HTML documentation and/or examples. 203 204The 'make install' will install the modules and scripts on your 205system. You may need administrator privileges to perform this task. 206Alternately you can can install the Template Toolkit to a local 207directory (see ExtUtils::MakeMaker for full details), e.g. 208 209 $ perl Makefile.PL PREFIX=/home/abw/ 210 211Don't forget to update your PERL5LIB environment variable if you do 212this, or add a line to your script to tell Perl where to find the files, 213e.g. 214 215 use lib qw( /home/abw/lib/perl5/site_perl/5.10.0 ); 216 217 218AUTHOR 219------ 220 221The Template Toolkit was written by Andy Wardley <abw@wardley.org> with 222the invaluable assistance and contributions from many other people. 223See Template::Manual::Credits for details. 224 225 226COPYRIGHT 227--------- 228 229Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved. 230 231This is free software; you can redistribute it and/or modify it under 232the same terms as Perl itself. 233 234