diff options
Diffstat (limited to 'docs/users_guide_src/gettingStarted.tex')
-rwxr-xr-x | docs/users_guide_src/gettingStarted.tex | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/docs/users_guide_src/gettingStarted.tex b/docs/users_guide_src/gettingStarted.tex new file mode 100755 index 0000000..69a3136 --- /dev/null +++ b/docs/users_guide_src/gettingStarted.tex @@ -0,0 +1,266 @@ +\section{Getting Started} +\label{gettingStarted} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Requirements} +\label{gettingStarted.requirements} + +Cheetah requires Python release 2.0 or greater, and has been tested with Python +2.0, 2.1 and 2.2. It is known to run on Linux, Windows NT/98/XP, FreeBSD and +Solaris, and should run anywhere Python runs. + +99\% of Cheetah is written in Python. There is one small C module +(\code{\_namemapper.so}) for speed, but Cheetah automatically falls back to a +Python equivalent (\code{NameMapper.py}) if the C module is not available. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Installation} +\label{gettingStarted.install} + +To install Cheetah in your system-wide Python library: +\begin{enumerate} +\item Login as a user with privileges to install system-wide Python packages. + On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is normally + 'su root'. On non-POSIX systems such as Windows NT, login as an + administrator. + +\item Run \code{python setup.py install} at the command prompt. + +\item The setup program will install the wrapper script {\bf cheetah} to + wherever it usually puts Python binaries ("/usr/bin/", "bin/" in the + Python install directory, etc.) +\end{enumerate} + +Cheetah's installation is managed by Python's Distribution Utilities +('distutils'). There are many options for customization. Type \code{``python + setup.py help''} for more information. + +To install Cheetah in an alternate location -- someplace outside Python's +\code{site-packages/} directory, use one of these options: +\begin{verbatim} + python setup.py install --home /home/tavis + python setup.py install --install-lib /home/tavis/lib/python +\end{verbatim} +Either way installs to /home/tavis/lib/python/Cheetah/ . Of course, +/home/tavis/lib/python must be in your Python path in order for Python to +find Cheetah. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Files} +\label{gettingstarted.files} + +If you do the systemwide install, all Cheetah modules are installed in the +{\bf site-packages/Cheetah/} subdirectory of your standard library +directory; e.g., /opt/Python2.2/lib/python2.2/site-packages/Cheetah. + +Two commands are installed in Python's \code{bin/} directory or a system +bin directory: \code{cheetah} (section \ref{gettingStarted.cheetah}) and +\code{cheetah-compile} (section \ref{howWorks.cheetah-compile}). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Uninstalling} +\label{gettingstarted.uninstalling} + +% @@MO: When 'python setup.py uninstall' is implemented, mention it here. + +To uninstall Cheetah, merely delete the site-packages/Cheetah/ directory. +Then delete the ``cheetah'' and ``cheetah-compile'' commands from whichever +bin/ directory they were put in. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{The 'cheetah' command} +\label{gettingStarted.cheetah} + +Cheetah comes with a utility \code{cheetah} that provides a command-line +interface to various housekeeping tasks. The command's first argument is +the name of the task. The following commands are currently supported: + +\begin{verbatim} +cheetah compile [options] [FILES ...] : Compile template definitions +cheetah fill [options] [FILES ...] : Fill template definitions +cheetah help : Print this help message +cheetah options : Print options help message +cheetah test : Run Cheetah's regression tests +cheetah version : Print Cheetah version number +\end{verbatim} + +You only have to type the first letter of the command: +\code{cheetah c} is the same as \code{cheetah compile}. + +The test suite is described in the next section. The \code{compile} +command will be described in section \ref{howWorks.cheetah-compile}, +and the \code{fill} command in section \ref{howWorks.cheetah-fill}. + +The depreciated \code{cheetah-compile} program does the same thing as +\code{cheetah compile}. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Testing your installation} +\label{gettingStarted.test} + +After installing Cheetah, you can run its self-test routine to verify it's +working properly on your system. Change directory to any directory you have +write permission in (the tests write temporary files). Do not run the tests +in the directory you installed Cheetah from, or you'll get unnecessary errors. +Type the following at the command prompt: +\begin{verbatim} +cheetah test +\end{verbatim} + +The tests will run for about three minutes and print a success/failure +message. If the tests pass, start Python in interactive mode and try the +example in the next section. + +Certain test failures are insignificant: +\begin{description} +\item{{\bf AssertionError: Template output mismatch: Expected Output = 0(end) +Actual Output = False(end)}} Python 2.3 changed the string representation of +booleans, and the tests haven't yet been updated to reflect this. +\item{{\bf AssertionError: subcommand exit status 127}} Certain tests run +``cheetah'' as a subcommand. The failure may mean the command wasn't found +in your system path. (What happens if you run ``cheetah'' on the command line?) +The failure also happens on some Windows systems for unknown reasons. This +failure has never been observed outside the test suite. Long term, we plan to +rewrite the tests to do a function call rather than a subcommand, which will +also make the tests run significantly faster. +\item{{\bf ImportError: No module named SampleBaseClass}} The test tried to +write a temporary module in the current directory and \code{import} it. Reread +the first paragraph in this section about the current directory. +\item{{\bf ImportError: No module named tmp}} May be the same problem as +SampleBaseClass; let us know if changing the current directory doesn't work. +\end{description} + +If any other tests fail, please send a message to the e-mail list with a copy +of the test output and the following details about your installation: + +\begin{enumerate} +\item your version of Cheetah +\item your version of Python +\item your operating system +\item whether you have changed anything in the Cheetah installation +\end{enumerate} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Quickstart tutorial} +\label{gettingStarted.tutorial} + +This tutorial briefly introduces how to use Cheetah from the Python prompt. +The following chapters will discuss other ways to use templates and more of +Cheetah's features. + +The core of Cheetah is the \code{Template} class in the \code{Cheetah.Template} +module. The following example shows how to use the \code{Template} class in an +interactive Python session. \code{t} is the Template instance. Lines prefixed +with \code{>>>} and \code{...} are user input. The remaining lines are Python +output. + +\begin{verbatim} +>>> from Cheetah.Template import Template +>>> templateDef = """ +... <HTML> +... <HEAD><TITLE>$title</TITLE></HEAD> +... <BODY> +... $contents +... ## this is a single-line Cheetah comment and won't appear in the output +... #* This is a multi-line comment and won't appear in the output +... blah, blah, blah +... *# +... </BODY> +... </HTML>""" +>>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'} +>>> t = Template(templateDef, searchList=[nameSpace]) +>>> print t + +<HTML> +<HEAD><TITLE>Hello World Example</TITLE></HEAD> +<BODY> +Hello World! +</BODY> +</HTML> +>>> print t # print it as many times as you want + [ ... same output as above ... ] +>>> nameSpace['title'] = 'Example #2' +>>> nameSpace['contents'] = 'Hiya Planet Earth!' +>>> print t # Now with different plug-in values. +<HTML> +<HEAD><TITLE>Example #2</TITLE></HEAD> +<BODY> +Hiya Planet Earth! +</BODY> +</HTML> + +\end{verbatim} + +Since Cheetah is extremely flexible, you can achieve the same result this +way: + +\begin{verbatim} +>>> t2 = Template(templateDef) +>>> t2.title = 'Hello World Example!' +>>> t2.contents = 'Hello World' +>>> print t2 + [ ... same output as the first example above ... ] +>>> t2.title = 'Example #2' +>>> t2.contents = 'Hello World!' +>>> print t2 + [ ... same as Example #2 above ... ] +\end{verbatim} + +Or this way: + +\begin{verbatim} +>>> class Template3(Template): +>>> title = 'Hello World Example!' +>>> contents = 'Hello World!' +>>> t3 = Template3(templateDef) +>>> print t3 + [ ... you get the picture ... ] +\end{verbatim} + +The template definition can also come from a file instead of a string, +as we will see in section \ref{howWorks.constructing}. + +The above is all fine for short templates, but for long templates or +for an application that depends on many templates in a hierarchy, it's +easier to store the templates in separate *.tmpl files and use the +{\bf cheetah compile} program to convert them into Python classes in +their own modules. This will be covered in section +\ref{howWorks.cheetah-compile}. + +As an appetizer, we'll just briefly mention that you can store constant values +{\em inside} the template definition, and they will be converted to attributes +in the generated class. You can also create methods the same way. +You can even use inheritance to arrange your templates in a hierarchy, +with more specific templates overriding certain parts of more general +templates (e.g., a "page" template overriding a sidebar in a "section" +template). + +For the minimalists out there, here's a template definition, +instantiation and filling all in one Python statement: + +\begin{verbatim} +>>> print Template("Templates are pretty useless without placeholders.") +Templates are pretty useless without placeholders. +\end{verbatim} + +You use a precompiled template the same way, except you don't provide +a template definition since it was already established: + +\begin{verbatim} +from MyPrecompiledTemplate import MyPrecompiledTemplate +t = MyPrecompiledTemplate() +t.name = "Fred Flintstone" +t.city = "Bedrock City" +print t +\end{verbatim} + + +% Local Variables: +% TeX-master: "users_guide" +% End: + |