path: root/docs/users_guide_src/gettingStarted.tex

\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: