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