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


\input commands.tex

\newcommand{\themeupstreamver}{5.1.0}
\newcommand{\debianrev}{{\rmfamily\textit{rev}}}
\newcommand{\themever}{\themeupstreamver-\debianrev}
\newcommand{\newver}{\themeupstreamver-\debianrev{}oldguile}
\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{Copyright}

Copyright (C) 2008-2023 Tommi Höynälänmaa

\vspace{0.5cm}

\noindent
See file \code{COPYING} for the license.



\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}.

Symbol \debianrev\ in the package names means the Debian revision of
the packages. It is typically 1 or 2. Symbol {\rmfamily\textit{arch}}
means the host system architecture, which can be obtained by command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg-architecture -q DEB\_HOST\_ARCH
\end{codeblock}

The newest version of the software is built for Guile version
3.0.8-2. It is possible to build \theme\ for Guile 3.0.7 but then you
have to edit some debianization files, see section \ref{sec:other-debian}.


\section{Installation}


\subsection{Debian bookworm (stable), trixie (testing), and %
  sid (unstable), Ubuntu Lunar and Mantic}

\label{sec:debian-basic}


If you use Synaptic Package Manager install the following packages:
\begin{itemize}
  \item \code{theme-d-rte}
  \item \code{theme-d-translator}
  \item \code{theme-d-stdlib}
\end{itemize}
If you also want to have the documentation install package
\code{theme-d-doc}, too.  The bootstrapped \theme\ system is contained
in package \code{theme-d-bootstrap}.
In order to install the system from the
command line give the following command:
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} sudo apt-get install theme-d-rte
  theme-d-translator theme-d-stdlib
\end{codeblock}
\noindent
and optionally one or both of the commands
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} sudo apt-get install theme-d-doc \\
  \noindent
  \mbox{ } \hspace{0.5cm} sudo apt-get install theme-d-bootstrap
\end{codeblock}


\subsection{Debian bullseye (oldstable)}

If you are satisfied with an older version of \theme\ follow the
instructions in section \ref{sec:debian-basic}. Otherwise
\begin{enumerate}
\item
  Install Guile 3.0 version 3.0.8-2 to your system:
  Get files \code{guile-3.0\_3.0.8.orig.tar.xz} and
  \code{guile-3.0\_3.0.8-2.debian.tar.xz}
  from
  
  https://packages.debian.org/bookworm/guile-3.0.
  
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} sudo apt install build-essential gperf devscripts \\
    \noindent
    \mbox{ } \hspace{0.5cm} sudo apt-get build-dep guile-3.0 \\
  \end{codeblock}
  Create a new directory and copy the downloaded files there. Change
  the working directory to the new directory and give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf guile-3.0\_3.0.8.orig.tar.xz \\
    \noindent
    \mbox{ } \hspace{0.5cm} cd guile-3.0-3.0.8.orig \\
    \noindent
    \mbox{ } \hspace{0.5cm} tar xvf ../guile-3.0\_3.0.8-2.debian.tar.xz \\
  \end{codeblock}
  Give command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dch -b -v 3.0.8-2\(\sim\)pre1 \\
  \end{codeblock}
  enter text ``Built for Debian bullseye'' in the changelog entry and
  save the changelog.
  Give commands
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} debuild -i -us -uc -b \\
    \noindent
    \mbox{ } \hspace{0.5cm} cd .. \\
    \noindent
    \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0-libs\_3.0.8-2\(\sim\)pre1\_\archsuffix.deb \\
    \noindent
    \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0\_3.0.8-2\(\sim\)pre1\_\archsuffix.deb \\
    \noindent
    \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0-dev\_3.0.8-2\(\sim\)pre1\_\archsuffix.deb \\
    \noindent
    \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0-doc\_3.0.8-2\(\sim\)pre1\_all.deb \\
  \end{codeblock}
  where the last command is optional.
\item
  Then follow section \ref{sec:other-debian} to build and install
  \theme. If your computer has amd64 architecture you can instead obtain
  the amd64 binary packages from the \theme\ homepage
  http://www.iki.fi/tohoyn/theme-d/ and install them with commands
  \begin{codeblock}
    \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
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-doc\_\themever\_all.deb
    \\
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-bootstrap\_\themever\_all.deb
    \\
  \end{codeblock}
\end{enumerate}
where the last two commands are optional.


\subsection{Ubuntu Jammy}


If you are satisfied with an older version of \theme\ follow the
instructions in section \ref{sec:debian-basic}. Otherwise
install Guile 3.0 with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} sudo apt install guile-3.0
\end{codeblock}
Then follow section \ref{sec:other-debian} to build and install
\theme.


\subsection{Ubuntu Kinetic}


If you are satisfied with an older version of \theme\ follow the
instructions in section \ref{sec:debian-basic}. Otherwise
install Guile 3.0 with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} sudo apt install guile-3.0
\end{codeblock}
Then follow section \ref{sec:other-debian} to build and install
\theme. Note that you don't have to edit \code{debian/rules} or
\code{debian/control} because Guile version in Ubuntu Kinetic is
3.0.8-2.
If you have amd64 architecture you can instead obtain
the amd64 binary packages from the \theme\ homepage
http://www.iki.fi/tohoyn/theme-d/ and install them with 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
  \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg -i theme-d-doc\_\themever\_all.deb
  \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg -i theme-d-bootstrap\_\themever\_all.deb
  \\
\end{codeblock}
where the last two commands are optional.


\subsection{Other UNIX Systems}


Follow the instructions in the next section.


\section{Building}


\subsection{Debian-based Systems}


These instructions apply to Debian-based Linux distributions such as
Debian and Ubuntu.  You can build the software for either Guile 3.0 or
Guile 2.2. If you use Guile 3.0 its version has to be $>= 3.0.7$.

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.

Install first one of the packages \code{guile-3.0-dev} or
\code{guile-2.2-dev} (or both) Use command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} apt-get install guile-3.0-dev
\end{codeblock}
or
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} apt-get install guile-2.2-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-3.0-dev \\
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg -s guile-2.2-dev
\end{codeblock}

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


\subsubsection{Building for Guile 3.0}
\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
  If you use Guile 3.0.7 change \code{GUILE\_VERSION2} from
  \code{3.0.8} to \code{3.0.7} in \code{debian/rules} and
  conditions \code{(>= 3.0.8)} to \code{(>= 3.0.7)} in
  \code{debian/control}.
\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 -b
  \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.
\item
  If you want to install the \theme\ bootstrapped environment give
  command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-bootstrap\_\themever\_all.deb
  \end{codeblock}
  as root.
\end{enumerate}


\subsubsection{Building for Guile 2.2}


\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 2.2 and
  \code{GUILE\_VERSION2} to 2.2.0 in file \code{debian/rules}, 14th
  and 15th line.
\item
  Change the package names \code{guile-3.0} and \code{guile-3.0-dev}
  to \code{guile-2.2} and \code{guile-2.2-dev} in the Build-Depends
  field in file \code{debian/control} (8th line).  Remove the
  \code{(>= 3.0.7)} from Build-Depends.
\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 -b
  \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.
\item
  If you want to install the \theme\ bootstrapped environment give
  command
  \begin{codeblock}
    \noindent
    \mbox{ } \hspace{0.5cm} dpkg -i theme-d-bootstrap\_\themever\_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 3.0 or 2.2 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-3.0 \\
    \noindent
    \mbox{ } \hspace{0.5cm} pkg-config --modversion guile-2.2
  \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{--with-guile-program={\rmfamily{\textit{file}}}} :
    Specify the Guile program used by the software explicitly. The
    default is \code{/usr/bin/guile-{\rmfamily\textit{version}}}.
  \item \code{--disable-nonopt-compilation} : Do not use the
    \code{-O1} flag for guile code compilation.
  \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.


\begin{enumerate}
\item
  Install guile 3.0 or 2.2 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.
The bootstrapped environment can be removed with command
\begin{codeblock}
  \noindent
  \mbox{ } \hspace{0.5cm} dpkg --purge theme-d-bootstrap \\
\end{codeblock}


\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.
\item \code{--version} : Show Theme-D version number and exit.
\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{--check-all-primitives} : Check that primitive procedure
  result values match the result types for all primitives, including
  those defined with \code{unchecked-prim-proc}.
\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.
\item \code{--guile-opt-level=} \metavar{level} : Set the optimization
  level for the final guile compilation. Default is 1.
\item \code{--extra-guild-options=} \metavar{options} : Define the
  extra options passed to \code{guild} when compiling the intermediate
  code to Guile bytecode.
\item \code{--version} : Show Theme-D version number and exit.
\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 the module name in the \code{-x} option is \code{"(mod1
  ... modn)"}.
%% 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 so big program that your system hangs with it it is
useful to split the linker output to several intermediate files. 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.

If option \code{--no-final-compilation} is not given the Tree-IL or
Scheme file generated by the linker is compiled to Guile bytecode with
command \code{guild compile}.
Option \code{--guile-opt-level} specifies the optimization level of
the final Guile compilation. Option \code{-O\textit{{\rmfamily level}}} is
passed to program \code{guild}. The default optimization level is 1.

  
\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.
  \item \code{--version} : Show Theme-D version number and exit.
\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{bootstrap-dir}: The location of the \theme\ bootstrap
    environment sources.
  \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. If your target system is
using a Debian-based Linux system (e.g. Debian or Ubuntu) and you
don't want to install whole \theme\ into it the easiest way to ensure
that all the necessary files are present is to install packages
\code{theme-d-rte}, \code{th-scheme-utilities}, and
\code{libthemedsupport} into the target system.


If you are using Guile in a non-Debian 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{Bootstrapping \theme}


The \theme\ source package contains a bootstrapped version of Theme-D,
i.e. Theme-D compiler and linker implemented with \theme itself.
Note that the bootstrap environment is not yet part of the
\theme\ Debian or Ubuntu packages.
To install the bootstrap environment change to the directory where you
want to install it and give command
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  setup-theme-d-bootstrap-env
\end{codeblock}
Note that you must have either \theme\ installed on your system or use
the uninstalled version of the software, see section
\ref{sec:local-mode}.

First you have to build \theme written in itself using compiler and
linker written in Guile. Change to the \code{theme-d-bootstrap}
directory and give the following commands:
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  cd build1/theme-d-in-theme-d \\
  \noindent \mbox{ } \hspace{0.5cm}
  make -f user.mk
\end{codeblock}
Then you build \theme using the compiler and linker built in the
previous step:
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  cd ../../bootstrap/theme-d-in-theme-d \\
  \noindent \mbox{ } \hspace{0.5cm}
  make -f user.mk
\end{codeblock}

Now you have the bootstrapped \theme\ compiler and linker in files
\code{theme-d-compile-b.go} and \code{theme-d-link-b.go} in
subdirectory \code{theme-d-bootstrap/bootstrap/theme-d-in-theme-d}.
You can use these programs with commands
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  run-theme-d-program BOOTSTRAPPATH/theme-d-compile-b.go ARGUMENTS
\end{codeblock}
and
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  run-theme-d-program BOOTSTRAPPATH/theme-d-link-b.go ARGUMENTS
\end{codeblock}


\section{Compiling, Linking, and Running Test and Example 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
order of elements in hash tables in tests \code{test826} and
\code{test827} may also vary.
The backtrace in \code{test764} and the path in \code{test598} may be
different in different runs. The values of environment variable
\code{HOME} printed by \code{test820} are different in different
systems.


If you want to build the examples with the bootstrapped compiler and
linker set the environment variables \code{THEME\_D\_COMPILE} to
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  "run-theme-d-program MYPATH/theme-d-compile-b.go"
\end{codeblock}
and
\code{THEME\_D\_LINK} to
\begin{codeblock}
  \noindent \mbox{ } \hspace{0.5cm}
  "run-theme-d-program MYPATH/theme-d-link-b.go"
\end{codeblock}
If you want to use the bootstrapped compiler give option
\code{-b MYPATH/theme-d-compile-b.go} to command
\code{compile-tests.scm}.
Program \code{link-test-programs.scm} accepts the following options:
\begin{itemize}
\item \code{-i} \metavar{backend} : Select the linker backend. The
  value of \metavar{backend} has to be either \code{tree-il},
  \code{guile}, or \code{guile0}. Value \code{guile0} means the
  nonoptimized Guile backend. The default value is \code{tree-il}.
\item \code{-k} : Do not delete the intermediate file (\code{.tree-il}
  or \code{.scm}).
\item \code{-b} \metavar{bootstrapped-linker-path}: Use the
  bootstrapped linker. The argument is the path to file
  \code{theme-d-link-b.go}.
\end{itemize}


Command \code{compile-tests.scm} passes the contents of environment
variable \code{EXTRA\_COMP\_OPTIONS} to the compiler.
Command \code{link-test-programs.scm} passes the contents of environment
variable \code{EXTRA\_LINK\_OPTIONS} to the linker.


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