
\documentclass[a4paper]{article}
\usepackage{amsmath,amssymb,amsthm}
\usepackage[utf8]{inputenc}


\input commands.tex

\newcommand{\themeupstreamver}{3.1.2}
\newcommand{\debianrev}{{\rmfamily\textit{rev}}}
\newcommand{\themever}{\themeupstreamver-\debianrev}
\newcommand{\newver}{\themeupstreamver-newguile}
\newcommand{\themesrcpackage}{theme-d-\themeupstreamver.tar.xz}
\newcommand{\metavar}[1]{{\rmfamily{}\textit{#1}}}
\newcommand{\themerootdir}{\metavar{theme-d-root-dir}}
\newcommand{\themesourcedir}{\metavar{theme-d-source-dir}}
\newcommand{\themetestdir}{\metavar{theme-d-test-dir}}
\newcommand{\unitrootdir}{\metavar{unit-root-dir}}
\newcommand{\archsuffix}{\textit{\rmfamily{arch}}}
\newcommand{\mytilde}{\(\sim\)}


\begin{document}


\begin{titlepage}
\title{\theme\ User Guide}
\author{Tommi H\"oyn\"al\"anmaa}
\maketitle
\end{titlepage}


\tableofcontents


\section{General}


This guide covers only UNIX systems. The software has been tested in
Debian and Ubuntu. Many of the commands in this guide have to be run
as root. A root session is opened either with command \code{su root}
or \code{sudo} depending on your system. In Ubuntu the command is
\code{sudo}.


\section{Installation}


\subsection{Debian-based Systems}


These instructions apply to Debian-based Linux distributions such as
Debian and Ubuntu. The default directory configuration of \theme\ is
stored in file \code{/etc/theme-d-config}. You may override this
by defining environment variable \code{THEME\_D\_CONFIG\_FILE} to be
the path of your own configuration file.  The root directory of the
\theme\ installation shall be called \themerootdir.  By default this
is \code{/usr/share/theme-d} in Debian-based installations and
\code{/usr/local/share/theme-d} in other installations.

Symbol \debianrev\ in the package names means the Debian revision of
the packages. It is typically 1.

Install first one of the packages \code{guile-2.2-dev} or
\code{guile-3.0-dev} (or both)
Use command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} apt-get install guile-2.2-dev
\end{codeblock}
or
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} apt-get install guile-3.0-dev
\end{codeblock}
as root.
You can check if these packages have already been
installed with commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm}
  dpkg -s guile-2.2-dev
  \\
  \noindent
  \mbox{ } \hspace{0.5cm}
  dpkg -s guile-3.0-dev
\end{codeblock}

If you have both \code{guile-2.2-dev} and \code{guile-3.0-dev}
installed you may choose which platform to use for \theme.


\subsubsection{Package \code{guile-2.2-dev} and Amd64 / Intel 64-bit
  x86 Processor Architecture}


\begin{enumerate}
\item
  If your home directory contains file \code{\mytilde/.theme-d-config}
  delete the file.
\item
  Give the following commands as root:
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i th-scheme-utilities\_\themever\_amd64.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i libthemedsupport\_\themever\_amd64.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-rte\_\themever\_amd64.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-translator\_\themever\_amd64.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-stdlib\_\themever\_all.deb
    \\
  \end{codeblock}
  in the directory where you have the Debian files.
\item
  If you want to install the \theme\ documentation give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-doc\_\themever\_all.deb
  \end{codeblock}
  as root.
\end{enumerate}
If you want to rebuild the Debian packages follow the instructions in
section \ref{sec:other-debian}.


\subsubsection{Other Debian-based Systems with Guile 2.2}
\label{sec:other-debian}


\begin{enumerate}
\item
  If your home directory contains file \code{\mytilde/.theme-d-config}
  delete the file.
\item
  Change to the directory where you want to unpack the \theme\ source code
\item
  Copy files \code{\themesrcpackage} and
  \code{theme-d\_\themever.debian.tar.xz} into that directory.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} ln -s \themesrcpackage\
    theme-d\_\themeupstreamver.orig.tar.xz
  \end{codeblock}  
\item
  Unpack \theme\ source code with command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf \themesrcpackage
  \end{codeblock}
\item
  Change to the subdirectory \code{theme-d-\themeupstreamver}.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf \code{../theme-d\_\themever.debian.tar.xz}
  \end{codeblock}
\item
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_PATH \\
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_COMPILED\_PATH
  \end{codeblock}
  In case you don't use a \code{sh} compatible shell these commands
  may be different or you may just ignore them.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg-buildpackage -uc -us -ui
  \end{codeblock}
\item
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} cd .. \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i th-scheme-utilities\_\themever\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i libthemedsupport\_\themever\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-rte\_\themever\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-translator\_\themever\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-stdlib\_\themever\_all.deb
    \\
  \end{codeblock}
  where \textit{arch} is the name of your processor
  architecture. These commands have to be run as root.
\item
  If you want to install the \theme\ documentation give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-doc\_\themever\_all.deb
  \end{codeblock}
  as root.
\end{enumerate}


\subsubsection{Other Debian-based Systems with Guile 3.0}


\begin{enumerate}
\item
  If your home directory contains file \code{\mytilde/.theme-d-config}
  delete the file.
\item
  Change to the directory where you want to unpack the \theme\ source code
\item
  Copy files \code{\themesrcpackage} and
  \code{theme-d\_\themever.debian.tar.xz} into that directory.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} ln -s \themesrcpackage\
    theme-d\_\themeupstreamver.orig.tar.xz
  \end{codeblock}  
\item
  Unpack \theme\ source code with command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf \themesrcpackage
  \end{codeblock}
\item
  Change to the subdirectory \code{theme-d-\themeupstreamver}.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf \code{../theme-d\_\themever.debian.tar.xz}
  \end{codeblock}  
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dch -v \newver
  \end{codeblock}
  and write some comment into the changelog.
\item
  Change the value of the variable
  \code{GUILE\_VERSION} to 3.0 in file \code{debian/rules} (6th line).
\item
  Change the package names \code{guile-2.2} and \code{guile-2.2-dev}
  to \code{guile-3.0} and \code{guile-3.0-dev} in the Build-Depends
  field in file \code{debian/control} (5th line).
\item
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_PATH \\
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_COMPILED\_PATH
  \end{codeblock}  
  In case you don't use a \code{sh} compatible shell these commands
  may be different or you may just ignore them.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg-buildpackage -uc -us -ui
  \end{codeblock}
\item
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} cd .. \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i th-scheme-utilities\_\newver\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i libthemedsupport\_\newver\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-rte\_\newver\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-translator\_\newver\_\archsuffix.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    dpkg -i theme-d-stdlib\_\newver\_all.deb
    \\
  \end{codeblock}
  where \textit{arch} is the name of your processor
  architecture. These commands have to be run as root.
\item
  If you want to install the \theme\ documentation give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-doc\_\newver\_all.deb
  \end{codeblock}
  as root.
\end{enumerate}


\subsection{Other UNIX Systems}
\label{sec:other-systems}


\begin{enumerate}
\item
  If your home directory contains file \code{\mytilde/.theme-d-config}
  delete the file.
\item
  Install Guile 2.2 or 3.0 if you don't have it already. Check the
  version of the Guile development environment with commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm}
    pkg-config --modversion guile-2.2
    \\
    \noindent
    \mbox{ } \hspace{0.5cm}
    pkg-config --modversion guile-3.0
  \end{codeblock}  
  See \myurl{http://www.gnu.org/software/guile/}.
\item
  Create some directory and unpack \theme\ package there
  with command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf
    \metavar{theme-package-path}/\themesrcpackage
  \end{codeblock}
  The subdirectory \code{theme-d-\themeupstreamver} of the directory
  where you unpacked
  \theme\ shall be called \themesourcedir.
\item
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_PATH \\
    \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_COMPILED\_PATH
  \end{codeblock}  
  In case you don't use a \code{sh} compatible shell these commands
  may be different or you may just ignore them.
\item
  Change to the the subdirectory \themesourcedir.
\item
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} ./configure
  \end{codeblock}
  You may give the following options to command \code{./configure}:
  \begin{itemize}
  \item \code{--with-guile={\rmfamily{\textit{version}}}} :
    Specify the Guile version explicitly. The version has to be either
    3.0 or 2.2.
  \item \code{--without-support-library} : Don't use the
    \code{libthemedsupport} library.
  \item \code{--disable-extra-math} : Don't include the
    \code{(standard-library extra-math)} module in your installation.
  \item \code{--disable-posix-math} : Don't include the
    \code{(standard-library posix-math)} module in your installation.
  \end{itemize}
  If you use option \code{--without-support-library} option you also
  have to use options \code{--disable-extra-math} and
  \code{--disable-posix-math}.
\item 
  Change to the the subdirectory \themesourcedir\ and
  give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} make
  \end{codeblock}
  in order to prepare the code for installation.
  Install \theme\ by giving command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} make install-complete
  \end{codeblock}
  as root.
  %% Finally, give command
  %% \begin{codeblock}
  %%   \noindent
  %%   \mbox{ } \hspace{0.5cm} make compile-scheme-code
  %% \end{codeblock}
\end{enumerate}


\subsection{Using the Software without Installation}
\label{sec:local-mode}


This sofware may also be used without installing it.
This is useful if you develop \theme\ itself.
It is recommended that you should not use \theme\ simultaneously with
installed version and local mode.


\begin{enumerate}
\item
  Install guile 2.2 or 3.0 in case you do not have it already. See

  \vspace{0.3cm}
  \noindent
  \mbox{ } \hspace{0.5cm} \myurl{http://www.gnu.org/software/guile/}
  \vspace{0.3cm}
  
\item
  Create some directory and unpack \theme\ package there
  with command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf
    \metavar{theme-package-path}/\themesrcpackage
  \end{codeblock}
\item 
  Go into the the subdirectory \code{theme-d-\themeupstreamver} of the
  directory created in the previous step.  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} ./configure \\
    \noindent
    \mbox{ } \hspace{0.5cm} make
  \end{codeblock}
  See section \ref{sec:other-systems} for the configure options.
\end{enumerate}

In order to use \theme\ change to the subdirectory \code{meta} and
give command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} ./uninstalled-env bash
\end{codeblock}
Now the commands \code{theme-d-compile}, \code{theme-d-link}, and
\code{run-theme-d-program} are available for you.


\subsection{Support for Racket}
\label{sec:racket-install}


If you want to use Racket as the target platform (i.e. the platform
where you run your \theme\ programs) you have to install Racket
package \code{theme-d-racket}. To do this obtain the file
\code{theme-d-racket.zip} and give command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} raco pkg install theme-d-racket.zip
\end{codeblock}

  
\section{Removing the Software}


\subsection{Debian-based Systems}


Give commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge theme-d-stdlib \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge theme-d-translator \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge theme-d-rte \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge libthemedsupport \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge th-scheme-utilities \\
\end{codeblock}
as root.
In order to remove the \theme\ documentation give command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge theme-d-doc \\
\end{codeblock}
as root.


\subsection{Other Systems}


Give command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} make uninstall-complete
\end{codeblock}
as root in directory \themesourcedir.


\subsection{Support for Racket}


Give command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} raco pkg remove theme-d-racket
\end{codeblock}


\section{\theme\ Environment}


\section{File Extensions}

\theme\ source files have the following extensions:
\begin{itemize}
  \item \code{.thp} for proper programs
  \item \code{.ths} for scripts
  \item \code{.thi} for interfaces
  \item \code{.thb} for bodies
\end{itemize}
\theme\ compiled pseudocode files have the following extensions:
\begin{itemize}
  \item \code{.tcp} for proper programs
  \item \code{.tcs} for scripts
  \item \code{.tci} for interfaces
  \item \code{.tcb} for bodies
\end{itemize}


\section{Unit Root Directories}


When you define a unit with full name
\begin{codeblock}
(\metavar{dir-1} ... \metavar{dir-n} \metavar{unit-name})
\end{codeblock}
the module must have filename \metavar{unit-name} with proper
extension (see the previous section) and it must be
located in subdirectory
\begin{codeblock}
\metavar{dir-1}/.../\metavar{dir-n}/
\end{codeblock}
of some directory \unitrootdir. The directory \unitrootdir\ is
called a \defterm{unit root directory}.
If a unit name has only one component you may omit the parentheses
from the unit name.
When you compile of link a \theme\ unit
you must specify one or more unit
root directories where the imported modules are searched.
These are called the \defterm{module search directories}.
You should always have directory \themerootdir/\code{theme-d-code}
among the module search directories so that the standard libraries are
found by the compiler and by the linker.


\section{Compiling a \theme\ Unit}
\label{sec:compilation}


Give command
\begin{codeblock}
  theme-d-compile \metavar{options} \metavar{unit-name}
\end{codeblock}
where \metavar{unit-name} is the file name of the \theme\ unit.
Options are
\begin{itemize}
\item \code{--module-path=} \metavar{paths} or \code{-m}
  \metavar{paths} : Module search paths separated with
  :'s
\item \code{--output=} \metavar{output-filename} or \code{-o}
  \metavar{output-filename} : The output filename
\item \code{--unit-type=} \metavar{unit-type} or \code{-u}
  \metavar{unit-type} :
  The unit type (\code{proper-program}, \code{script},
  \code{interface}, or \code{body})
\item \code{--message-level=} \metavar{message-level} or \code{-l}
  \metavar{message-level} : Compiler message level,
  integer number from 0 to 3.
\item \code{--expand-only} : Do only macro expansion on the source.
\item \code{--no-expansion} : Compile the source without macro expansion.
\item \code{--backtrace} : Print backtrace on compilation error.
\item \code{--pretty-print} : Pretty print the pseudocode output.
\item \code{--no-verbose-errors} : Less information in the error messages.
\item \code{--show-modules} : Show information about loading modules.
\end{itemize}


By default the unit type is computed from the source file extension.
The default module search path is \code{\themerootdir:.}.
If you use option \code{-m} you may include the \theme\ default module
search path in your custom path by adding an extra ``:'' in the
beginning of the new path, e.g. \code{:my-path1:my-path2}.
The default target file
path is obtained by removing the path and the extension from the
source filename and appending the appropriate extension to the result.
The default message level is 1. Message level 0
means no output at all except in case of error. Message level 1
displays also message on successful compilation or linking. Message
level 2 displays some debug information and level 3 a lot of debug
information. When \code{--expand-only} is set the default target
filename is \code{myunit.expanded.thx} for source file
\code{myunit.thx}.


Suppose that you have your own \theme\ code at directory
\metavar{my-theme-d-dir} and you have a program called
\code{(mod-1 ... mod-n)} at location
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm}
  mod-1/.../mod-n.thp
\end{codeblock}
\noindent
In order to compile the program give commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} cd \metavar{my-theme-d-dir} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-compile
  \code{mod-1/.../mod-n.thp}
\end{codeblock}
Suppose that you have a module (an interface and a body) with name
\code{(mod-1 ... mod-n)} in files \code{mod-1/.../mod-n.thi} and
\code{mod-1/.../mod-n.thb}.
In order to compile the module give
commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} cd \metavar{my-theme-d-dir} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-compile
  \code{mod-1/.../mod-n.thi} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-compile
  \code{mod-1/.../mod-n.thb}
\end{codeblock}
If you want to have the compiled files in the same subdirectory where
the source files are, which is usually the case, give commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} cd \metavar{my-theme-d-dir} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-compile
  -o \code{mod-1/.../mod-n.tci} \bl \\
  \noindent
  \mbox{ } \hspace{0.8cm}
  \code{mod-1/.../mod-n.thi} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-compile
  -o \code{mod-1/.../mod-n.tcb} \bl \\
  \noindent
  \mbox{ } \hspace{0.8cm}
  \code{mod-1/.../mod-n.thb}
\end{codeblock}


If you use \theme\ without installing it you have to use command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{1.0cm}
  \code{MYPATH/theme-d-VERSION/theme-d/translator/theme-d-compile.scm}
\end{codeblock}
instead of \code{theme-d-compile}. Here \code{MYPATH} is the path where
you have unpacked \theme.


\section{Linking a \theme\ Program}
\label{sec:linking}


Give command
\begin{codeblock}
  theme-d-link \metavar{options} \metavar{program-name}
\end{codeblock}
where \metavar{program-name} is the file name of the \theme\ program.
Options are
\begin{itemize}
\item \code{--module-path=} \metavar{paths} or \code{-m}
  \metavar{paths} : Module search paths separated with
  :'s
\item \code{--output=} \metavar{output-filename} or \code{-o}
  \metavar{output-filename} : The output filename.
\item \code{--intermediate-file=} \metavar{filename} or \code{-n}
  \metavar{filename} : The intermediate filename.
\item \code{--intermediate-language=} \metavar{language} or \code{-i}
  \metavar{language} :
  The language used for the intermediate file.
\item \code{-x} \metavar{module}: Link (load) the module into the
  target program.
\item \code{-y} \metavar{module}: Link (load) the module into the
  target program using a relative path. This option is available only
  for Racket.
\item \code{--message-level=} \metavar{message-level} or \code{-l}
  \metavar{message-level} : Linker message level,
  integer number from 0 to 3.
\item \code{--no-final-compilation} : Do not compile the linker result file
  with \code{guild compile}.
\item \code{--no-strip} : Do not strip away unused code.
\item \code{--no-optimization} : Do not optimize linker output.
\item \code{--no-factorization} : Do not factorize the type expressions
  out of procedure implementations.
\item \code{--no-weak-assertions} : Do not check ordinary assertions.
  Strong assertions are always checked.
\item \code{--backtrace} : Print backtrace on linking error.
\item \code{--pretty-print} : Pretty print the linker output.
\item \code{--no-verbose-errors} : Less information in the error messages.
\item \code{--keep-intermediate} : Keep the intermediate Tree-IL or
  Scheme file
\item \code{--link-to-cache} : Link the target file into the guile
  cache.
\item \code{--runtime-pretty-backtrace} : Generate the code to support
  runtime pretty printed backtraces.
\item \code{--no-unlinked-procedure-names} : Do not generate code for
  reporting unlinked procedure names.
\item \code{--module-debug-output} : Print debug messages when a
  module body linkage is started and ended.
\item \code{--duplicates=} \metavar{symbols} : Set the values passed to
  \code{default-duplicate-binding-handler} in the target program. If
  there are several symbols enclose them in quotes.
\item \code{--split} : Split the linker output.
\item \code{--split-dir=} \metavar{dir} : Set the directory where to
  put the split linker output.
\item \code{--split-basename=} \metavar{name} : Set the basename for
  split linker output files.
\end{itemize}

The available intermediate languages are:
\begin{itemize}
\item \code{tree-il} : Guile Tree-IL. The Tree-IL version shall be the
  Guile version for which \theme\ has been configured.
\item \code{tree-il-3.0} : Guile 3.0 Tree-IL. This is currently
  identical to Guile 2.2 Tree-IL.
\item \code{tree-il-2.2} : Guile 2.2 Tree-IL.
\item \code{guile} : Guile Scheme. The Guile version shall be the
  version for which \theme\ has been configured.
\item \code{guile-3.0} : Guile Scheme 3.0.
\item \code{guile-2.2} : Guile Scheme 2.2.
\item \code{racket} : Racket Scheme.
\end{itemize}
The option \code{--no-optimization} has no effect for target platforms
for target platforms \code{--tree-il} and \code{--tree-il-xxx}. They
are always optimized.
If you use Racket options \code{--keep-intermediate} and
\code{--no-final-compilation} are assumed implicitly.
By default \theme\ linker produces a guile objcode file. Actually,
\theme\ makes a guile Tree-IL or Scheme file and uses guile to make an
objcode file from that. The default intermediate language is Tree-IL.
Note that many optimizations are performed only with Tree-IL.
If you want to optimize your code for speed you should link your
program without pretty backtraces when you no longer need them for
debugging. If you use Tree-IL as the intermediate language pretty
printing may cause the linker to crash with large programs.
The syntax of module names in the \code{-x} and \code{-y} options
depends on the intermediate language. It is \code{"(mod1 ... modn)"}
for Guile and \code{mod1/.../modn} for Racket. If you use the
\code{-y} option for linking a module (available only for Racket) the
module is imported with a \code{require} form so that the module name
is enclosed in double quotes. See the Racket documentation how this
works.

If you use option \code{--module-path} or \code{-m} you may include
the \theme\ default module
search path in your custom path by an extra ``:'' in the path as in
compilation.
Suppose that you have your own \theme\ code at directory
\metavar{my-theme-d-dir} and you have a program called
\code{(mod-1 ... mod-n)} at location \code{mod-1/.../mod-n.thp}.
In order to link the program give commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} cd \metavar{my-theme-d-dir} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-link \code{mod-1/.../mod-n.thp}
\end{codeblock}
The previous commands place the linked file into the root of
subdirectory \metavar{my-theme-d-dir}. If you want to place the linked
file in the same directory where the source files are use the
following commands:
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} cd \metavar{my-theme-d-dir} \\
  \noindent
  \mbox{ } \hspace{0.5cm} theme-d-link
  -o \code{mod-1/.../mod-n.go} \bl \\
  \noindent
  \mbox{ } \hspace{0.8cm}
  \code{mod-1/.../mod-n.thp}
\end{codeblock}

If you use \theme\ without installing it you have to use command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{1.0cm}
  \code{MYPATH/theme-d-VERSION/theme-d/translator/theme-d-link.scm}
\end{codeblock}
instead of \code{theme-d-link}. Here \code{MYPATH} is the path where
you have unpacked \theme.

If you have a big program it is useful to split the linker output to
several intermediate files so that the Guile bytecode compiler does
not begin to use the swap memory. You can do this by giving option
\code{--split} to the linker. The linker output files are placed on a
separate subdirectory. By default this subdirectory is called
\textit{program}-\texttt{.compiled}.  You can change the directory
name with option \code{--split-dir}. You can also change the basename
of the output files with option \code{--split-basename}. Note that
script \code{run-split-theme-d-program} does not work if you change
the basename.

  
\section{Running a \theme\ Program}
\label{sec:running}


When you use Guile as the target platform \theme\ programs can be run
with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} run-theme-d-program \metavar{metaarg}
  ... \metavar{programfile} \metavar{programarg} ...
\end{codeblock}
where \metavar{metaarg} are the arguments passed to the script
\code{run-theme-d-program}, \metavar{programfile} is the filename of
the linked \theme\ program, and \metavar{programarg} are the
arguments passed to the program.
Suppose you have your linked \theme\ program in file
\code{myprog.go}. You can run this program with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} run-theme-d-program myprog.go
\end{codeblock}
When you use Guile as the target platform it is also possible to link
you \theme\ program into a \code{.scm} intermediate file and run it
with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} guile -e main -s \metavar{programfile}.scm
  \metavar{programarg} ...
\end{codeblock}
or
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} guile -s \metavar{programfile}.scm
  \metavar{programarg} ...
\end{codeblock}
for scripts.

If you use Racket as the target platform you can run \theme\ programs
with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} racket -t myprog.rkt -m \metavar{programarg} ...
\end{codeblock}
or
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} racket -t myprog.rkt \metavar{programarg} ...
\end{codeblock}
for scripts.

If you need to import your own Scheme files into the \theme\ runtime
environment (because of the foreign function interface) you can do
this by defining the environment variable
\code{THEME\_D\_CUSTOM\_CODE}. Separate the file names with :'s.
However, it is recommended to use option \code{-x} for this.

The program \code{run-theme-d-program} accepts the following
arguments:
\begin{itemize}
  \item \code{--no-verbose-errors} : No verbose information about errors
    (exceptions).
  \item \code{--backtrace} : Display backtrace on error.
  \item \code{--pretty-backtrace} : Display pretty printed backtrace
    on error.
\end{itemize}
Note that the \code{--pretty-backtrace} option works only if you have
linked your \theme\ program with option
\code{--runtime-pretty-backtrace}.


In order to run a \theme\ program with split linker output give
command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{1.0cm}
  run-split-theme-d-program \metavar{dir-name}
\end{codeblock}
where \metavar{dir-name} is the directory where the linker output is
generated.


The pretty printed runtime backtrace has the following format:
\vspace{0.5cm}
\par \noindent
\hspace{0.5cm}\textit{number} \textit{kind} \textit{name}
\textit{module} \\
\par \noindent
\hspace{0.5cm}\(\vdots\) \\
\mbox{ }
\vspace{0.2cm} \\
%%\par\noindent
where \textit{kind} is the kind of the called procedure, \textit{name}
is the name of the procedure and \textit{module} is the module where
the procedure has been defined.
The \textit{kind} may take the following values:
\begin{itemize}
  \item \texttt{toplevel}: A toplevel procedure
  \item \texttt{local}: A local procedure
  \item \texttt{instance}: An instance of a parametrized procedure
  \item \texttt{zero}: A procedure used to generate the zero value of
    a class
\end{itemize}


\section{\theme\ Configuration File}


The \theme\ configuration file is searched according to the following
rules:
\begin{itemize}
  \item Use the value of environment variable
    \code{THEME\_D\_CONFIG\_FILE} is it is defined.
  \item Use file \code{.theme-d-config} in the user's home directory
    if present.
  \item Otherwise use file \code{/etc/theme-d-config}.
\end{itemize}
The installation procedure sets up the configuration file. Normally
you don't have to edit it.

The configuration file has the following format:
\begin{codeblock}
  \par \noindent \mbox{  } \hspace{0.5cm}
  (theme-d (\textit{\rmfamily{}var-name} \textit{\rmfamily{}var-value})...)
\end{codeblock}
All string type variable values must be enclosed in quotes. Boolean
and integer values must not be enclosed in quotes
The variables defined in the configuration file are:
\begin{itemize}
  \item \code{guile-version}: The Guile version used by \theme. This
    is a string.
  \item \code{translator-dir}: The location of the compiler and
    linker implementations.
  \item \code{runtime-dir}: The location of the
    \theme\ runtime environment.
  \item \code{lib-dir}: The location of the \theme\ standard library.
  \item \code{examples-dir}: The location of the \theme\ examples.
  \item \code{tests-dir}: The location of the \theme\ tests.
  \item \code{tools-dir}: The location of the \theme\ tools.
  \item \code{compiler-path} \theme\ compiler path (a \code{.scm}
    file).
  \item \code{linker-path} \theme\ linker path (a \code{.scm}
    file).
  \item \code{run-path} \theme\ run script path path (a \code{.scm}
    file).
  \item \code{use-support-lib?}: \true\ if the support library is
    used. This is a boolean value.
\end{itemize}
The values of the configuration variables can be fetched with command
\begin{codeblock}
  \par \noindent \mbox{  } \hspace{0.5cm}
  get-theme-d-config-var \metavar{config-var-name}
\end{codeblock}
\noindent
where \metavar{config-var-name} is the name of the configuration
variable.


\section{Distributing Linked \theme\ Programs}


If your target environment has \theme\ installed it is sufficient to
distribute only the linked \code{.go} file. Otherwise, the easiest way
to ensure that all the necessary \theme\ files are present is to
install the \code{theme-d-rte} Debian package in the target system.
If you use Racket as the target platform it is sufficient to install
package \code{theme-d-racket.zip} in the target system, see section
\ref{sec:racket-install}.

If you are using Guile and you don't want to install
\code{theme-d-rte} into the target system you have to ensure that the
following files are present in the Guile library path:
\begin{itemize}
  \item \code{theme-d/runtime/params.go}
  \item \code{theme-d/runtime/runtime-theme-d-environment.go}
  \item \code{theme-d/runtime/theme-d-stdlib-support.go}
\end{itemize}
You also need to distribute one of the following files:
\begin{itemize}
  \item \code{theme-d/runtime/theme-d-support-all.go}
  \item \code{theme-d/runtime/theme-d-support-no-extra.go}
  \item \code{theme-d/runtime/theme-d-support-no-posix.go}
  \item \code{theme-d/runtime/theme-d-alt-support.go}
\end{itemize}
and create symbolic link \code{theme-d/runtime/theme-d-support.go}
pointing to it. In order to find the library path give command
\begin{codeblock}
  \par \noindent \mbox{  } \hspace{0.5cm}
  pkg-config --variable=siteccachedir guile-\textit{\rmfamily version}
\end{codeblock}
Normally you should use file \code{theme-d-support-all.go}. If you
don't use the \theme\ support library you must use
\code{theme-d-alt-support.go}. If you distribute a \code{.go} file you
also need to have \code{run-theme-d-program.scm} in the target system.
These files are licensed under GNU Lesser General Public License.

If you use the support library the library \code{libthemedsupport} has
to be installed in the target system. The use of the support library
is recommended.


\section{Compiling, Linking, and Running Test and Examples Programs}


In order to install the \theme\ testing environment change to the
directory where you want the environment to be installed and give
command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  setup-theme-d-test-env
\end{codeblock}
This directory shall be
called \themetestdir\ in the sequel. The test programs are located in
subdirectory \code{test-env/theme-d-code/tests} and the example
programs in \code{test-env/theme-d-code/examples}. Subdirectory
\code{tools} contains scripts to run tests.


The example programs are built by giving command \code{make -f
  user.mk} in subdirectory \code{test-env/theme-d-code/examples}.
The example programs are run with command \code{run-theme-d-program
  {\rmfamily\textit{program}}.go}.


If \code{testX} is a program compile it with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  theme-d-compile -m :.. testX.thp
\end{codeblock}
and link with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  theme-d-link -m :.. testX.tcp
\end{codeblock}
in directory \code{\themetestdir/test-env/theme-d-code/tests}.

If \code{testX} is a module compile it with commands
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  theme-d-compile -m :.. testX.thi \\
  \noindent \mbox{ } \hspace{0.5cm}
  theme-d-compile -m :.. testX.thb
\end{codeblock}
in directory \code{\themetestdir/test-env/theme-d-code/tests}.


Note that some test programs import test modules in which case you
must compile the modules before the program that uses them.
When a test program imports several test modules compile first all the
interfaces of the imported modules and then all the bodies of the
imported modules. Compile the interfaces in the order they are
numbered. Note also that some test programs require the examples to be
built.


In order to run a test \code{testX} give commands
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  run-theme-d-program testX.go
\end{codeblock}
in directory \code{\themetestdir/test-env/theme-d-code/tests}.


If you want to build all the tests at once build the examples first.
Then change to the directory \code{\themetestdir/test-env/testing}.
Compile the tests with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./compile-tests.scm
\end{codeblock}
\noindent
and link them with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./link-test-programs.scm
\end{codeblock}
\noindent
Then run the linked programs with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./run-test-programs.scm
\end{codeblock}
The test results can be checked with commands
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./check-test-compilation.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./check-test-program-linking.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./check-test-runs.scm
\end{codeblock}
\noindent
for compilation, linking and running, respectively. All these scripts
are located in directory \code{\themetestdir/testing}.

You can generate the test output into the subdirectory \code{output}
with command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./run-test-programs-w-output.scm
\end{codeblock}
Use command \code{./compare-output.sh} to compare the output files
with the correct ones.  The correct outputs of the tests can be found
in subdirectory \code{tests} in files \code{test*.out}.  The outputs
of tests \code{test450} and \code{test756} may vary because of output
buffering.  The computed hash values in test \code{test587} and the
backtrace in \code{test764} may be different in different runs.

If you want to use \code{scheme} (Guile) as the intermediate language
use command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./link-test-programs-scheme.scm
\end{codeblock}
for linking.
If you want to use \code{racket} as the intermediate language use
scripts
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  ./link-test-programs-racket.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./check-test-program-linking-racket.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./run-test-programs-racket.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./check-test-runs-racket.scm \\
  \noindent \mbox{ } \hspace{0.5cm}
  ./run-test-programs-w-output-racket.scm
\end{codeblock}
for linking and running the test programs. Test \code{test450} does
not work for Racket. The following tests give different output with
Guile and Racket: 115, 235, 273, 277, 450, 556, 598, 606, 607, 673,
716, 717, 720, 729, 743, and 756. Note that the Racket-related scripts
omit the tests using features not available for Racket, such as GOOPS
or the extra math functions in the support library.


\section{Other Things}


An Emacs mode for \theme\ can be found at \code{tools/theme-d.el}.
There are some example programs in subdirectory
\code{theme-d-code/examples} in the \theme\ source package. You can
compile, link, and run them following the instructions given in sections
\ref{sec:compilation}, \ref{sec:linking}, and \ref{sec:running}.
If you install the \theme\ Debian package twice the configuration file
\code{theme-d-config} may not be installed. This problem is solved by
uninstalling \theme\ and installing it again.


\theme\ translator uses the following notation for printing pair and
tuple types:
\code{(:pair \objectvar{r} \objectvar{s})}
is printed as
\code{\{ \objectvar{r} . \objectvar{s} \}}
and
\code{(:tuple \indexedobjectvar{t}{1}
  ... \indexedobjectvar{t}{n})} is printed as
\code{\{\indexedobjectvar{t}{1} ... \indexedobjectvar{t}{n}\}}. Note
that this notation is not accepted in \theme\ code.


\section{Comments}


The linker requires that the compiled modules are placed in a proper
subdirectory hierarchy under some directory among the module search
directories.
This condition is fulfilled if you define the module search
directories to include all the unit root directories used by your
source files and put the compiled files
into same directories with the source files.


\end{document}
