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

\input commands.tex

\newcommand{\themeupstreamver}{7.2.4}
\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 \copyright\ 2008-2025 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.10. 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{Using a Prerelease}

% If you want to use Theme-D prerelease 6.0.0\(\sim\)pre7 follow the instructions
% in section \ref{sec:other-systems} or \ref{sec:local-mode} and replace
% \themeupstreamver\ with 6.0.0\(\sim\)pre7.

\section{Installation}

\subsection{Debian forky (testing) and sid (unstable) and Ubuntu Resolute}

\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 trixie (stable) and bookworm (oldstable) and older versions of Ubuntu}

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{Debian bullseye (oldoldstable)}

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 \\
              \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\_\archsuffix.deb \\
              \noindent
              \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0\_3.0.8-2\_\archsuffix.deb \\
              \noindent
              \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0-dev\_3.0.8-2\_\archsuffix.deb \\
              \noindent
              \mbox{ } \hspace{0.5cm} sudo dpkg -i guile-3.0-doc\_3.0.8-2\_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{Other UNIX Systems}

Follow the instructions in the next section.

\section{Building}

\subsection{Debian-based Systems}
\label{sec:other-debian}

These instructions apply to Debian-based Linux distributions such as Debian and
Ubuntu. You need Guile 3.0 version $>= 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.

Build and install Theme-D with the following steps:

\begin{enumerate}
    \item
          Check if package \code{guile-3.0-dev} is installed with command
          \begin{codeblock}
              \noindent
              \mbox{ } \hspace{0.5cm} dpkg -s guile-3.0-dev
          \end{codeblock}
          If you don't have it install it with command
          \begin{codeblock}
              \noindent
              \mbox{ } \hspace{0.5cm} sudo apt-get install guile-3.0-dev
          \end{codeblock}
    \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
          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 \\
              \noindent
              \mbox{ } \hspace{0.5cm} unset GUILE\_LOAD\_COMPILED\_PATH \\
              \noindent
              \mbox{ } \hspace{0.5cm} dpkg-buildpackage -b --no-sign \\
              \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}

\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 if you don't have it already. Check the
          version of the Guile development environment with command
          \begin{codeblock}
              \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. Currently only version 3.0 is supported.
              \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{--with-guile-header-dir={\rmfamily{\textit{directory}}}} :
                    Specify the directory where to find header file \code{libguile.h}
                    for \code{libthemesupport} C compilation.
                    The default is not to specify the directory explicitly.
              \item \code{--with-extension-dir={\rmfamily{\textit{directory}}}} :
                    Specify the directory where to install Guile extensions.
              \item \code{--with-guile-module-dir={\rmfamily{\textit{directory}}}} :
                    Specify the directory where to install Guile modules.
              \item \code{--with-guile-comp-module-dir={\rmfamily{\textit{directory}}}} :
                    Specify the directory where to install compiled Guile modules.
              \item \code{--with-conf-dir={\rmfamily{\textit{directory}}}} :
                    Specify the directory where to install the global Theme-D
                    configuration file. Default is \code{/etc}.
              \item \code{--disable-xlat-opt-compilation} : Use Guile
                    optimization level 1 for compiling the Theme-D translator.
              \item \code{--disable-rte-opt-compilation} :
                    Use Guile optimization level 1 for the runtime environment 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 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.

\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}
The auxiliary module files use extension \code{.aux}.

\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\ Unit}
\label{sec:linking}

A \theme\ unit can be linked either monolithically or modularly. In
monolithic linking a \theme\ program is linked into a single Guile bytecode
file. In modular linking \theme\ units are linked to separate Guile bytecode
modules. For a \theme\ module \code{MYMODULE} the target interface module is
named \code{\_\_intf\_MYMODULE.go} and the target body module
\code{\_\_impl\_MYMODULE.go}. The auxiliary module files are named
\code{\_\_intf\_MYMODULE.aux} and \code{\_\_impl\_MYMODULE.aux}.
\theme\ dynamical plugin features can only be used with modular
linking,

In order to link a \theme\ program monolithically 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.
In order to link a \theme\ unit to a Guile module 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\ unit
and \metavar{options} contains \code{--module}.
Available options are
\begin{itemize}
    \item \code{--module-path=} \metavar{paths} or \code{-m}
          \metavar{paths} : Module search paths separated with :'s
    \item \code{--guile-target-path=} \metavar{paths} :
          Guile target module search paths separated with :'s
    \item \code{--empty-guile-target-path} :
          Set Guile target module search path to be empty.
    \item \code{--full-module-path=} \metavar{paths} or \code{-M}
          \metavar{paths} :
          Equivalent to
          \begin{codeblock}
              --module-path=\metavar{paths} --guile-target-path=\metavar{paths}.
          \end{codeblock}
    \item \code{--unit-type=} \metavar{unit-type} :
          Specify the unit type explicitly. Argument \metavar{unit-type}
          has to be one of \code{proper-program}, \code{script},
          \code{body}, or \code{interface}.
    \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{--show-inst-number} : Print the expression numbers of the
          processed expressions in parametrized type instantiation.
    \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. The 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{--plugin} :
          Link a module body to a plugin. This option implies \code{--module}.
    \item \code{--version} : Show Theme-D version number and exit.
\end{itemize}

The available intermediate languages are:
\begin{itemize}
    \item \code{tree-il-3.0} : Guile 3.0 Tree-IL.
    \item \code{guile-3.0} : Guile Scheme 3.0.
\end{itemize}
You may use aliases \code{tree-il} and \code{guile}.
Using intermediate language \code{guile0} is equivalent to options
\code{-i guile --no-optimization}.
The option \code{--no-optimization} has no effect for the Tree-IL target
platform. It is always optimized.
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 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. Note that
invoking the Guile optimization of \code{letrec} expressions requires the
optimization level to be at least 2. The Guile target path is used to set the
value of environment variable \code{GUILE\_LOAD\_COMPILED\_PATH} to the
\code{guild} command.

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

In order to run a modularly linked \theme\ program give command
\begin{codeblock}
    \noindent
    \mbox{ } \hspace{1.0cm}
    run-theme-d-program-m -g \metavar{guile-target-path} \metavar{program}
\end{codeblock}
where \metavar{program} is a \code{.go} file created by the linker and
\metavar{guile-target-path} is the path used to search Guile modules.
Normally you should use path \code{\metavar{root-dir}:} where \metavar{root-dir}
is the unit root directory of your program. Note that you don't need to include
Guile cache directories into the Guile target path.

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. If your program uses modular linking you also have to distribute
files \code{standard-library/\_\_intf\_*.go}, \code{standard-library/\_\_intf\_*.aux},
files \code{standard-library/\_\_impl\_*.go}, and
\code{standard-library/\_\_impl\_*.aux}.

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 and Debian package \code{theme-d-bootstrap} contain a
bootstrapped version of Theme-D, i.e.
Theme-D compiler and linker implemented with \theme\ itself.
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}
or if you want to use modular linking
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    cd build1/theme-d-in-theme-d \\
    \noindent \mbox{ } \hspace{0.5cm}
    LINK\_MODULES=1 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}
or if you want to use modular linking
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    cd ../../bootstrap/theme-d-in-theme-d \\
    \noindent \mbox{ } \hspace{0.5cm}
    LINK\_MODULES=1 make -f user.mk
\end{codeblock}
If you use modular linking with \code{build1} you have to define variable
\code{MODULAR\_TRANSLATOR} with \code{bootstrap}, e.g.
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    cd ../../bootstrap/theme-d-in-theme-d \\
    \noindent \mbox{ } \hspace{0.5cm}
    MODULAR\_TRANSLATOR=1 LINK\_MODULES=1 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}. We denote the path to
this directory by
\code{BOOTSTRAPPATH}.
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}
or if you use modular linking
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    run-theme-d-program-m -g BOOTSTRAPPATH2: $\backslash$ \\
    \noindent \mbox{ } \hspace{1.0cm}
    BOOTSTRAPPATH2/theme-d-in-theme-d/theme-d-compile-b.go ARGUMENTS
\end{codeblock}
and
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    run-theme-d-program-m -g BOOTSTRAPPATH2: $\backslash$ \\
    \noindent \mbox{ } \hspace{1.0cm}
    BOOTSTRAPPATH2/theme-d-in-theme-d/theme-d-link-b.go ARGUMENTS
\end{codeblock}
where \code{BOOTSTRAPPATH2} is the path to directory \code{bootstrap}.


\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}. If you want to use modular
linking use command
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    LINK\_MODULES=1 make -f user.mk
\end{codeblock}

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}
or
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    theme-d-link --module -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}.
If you use modular linking you also have to link the units with commands
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    theme-d-link --module -M ..: testX.tci \\
    \noindent \mbox{ } \hspace{0.5cm}
    theme-d-link --module -M ..: testX.tcb
\end{codeblock}

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}
or
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    run-theme-d-program-m -g ..: 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
Then you can link the programs monolithically with command
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./link-test-programs.scm
\end{codeblock}
or link all units modularly with command
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./link-to-modules.scm
\end{codeblock}
\noindent
Then run the linked programs with command
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./run-test-programs.scm
\end{codeblock}
in case of monolithic linking and
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./run-test-programs-m.scm
\end{codeblock}
in case of modular linking.
The compilation results can be checked with command
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./check-test-compilation.scm
\end{codeblock}
Results of monolithic linking and running can be checked with
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./check-test-program-linking.scm \\
    \noindent \mbox{ } \hspace{0.5cm}
    ./check-test-runs.scm
\end{codeblock}
and for modular linking and running with
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./check-test-module-linking.scm \\
    \noindent \mbox{ } \hspace{0.5cm}
    ./check-test-runs-m.scm
\end{codeblock}
\noindent
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}
or
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    ./run-test-programs-w-output-m.scm
\end{codeblock}
in case of modular linking.
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.  For modular linking, different outputs are reported for test cases
\code{test132}, \code{test135}, \code{test136}, \code{test173}, and
\code{test472} due to different internal variable names.

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-in-theme-d/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-in-theme-d/theme-d-link-b.go
\end{codeblock}
or in case of modular linking to
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    run-theme-d-program-m -g MYPATH $\backslash$ \\
    \noindent \mbox{ } \hspace{0.8cm}
    MYPATH/theme-d-in-theme-d/theme-d-compile-b.go
\end{codeblock}
and
\begin{codeblock}
    \noindent \mbox{ } \hspace{0.5cm}
    run-theme-d-program-m -g MYPATH $\backslash$ \\
    \noindent \mbox{ } \hspace{0.8cm}
    MYPATH/theme-d-in-theme-d/theme-d-link-b.go
\end{codeblock}
Here \code{MYPATH} is either directory \code{build1} or \code{bootstrap} in the
bootstrapped environment.
If you want to use the bootstrapped compiler give option
\code{-b MYPATH/theme-d-in-theme-d/theme-d-compile-b.go}
or
\code{-B MYPATH}
to command
\code{compile-tests.scm}.
If your bootstrapper compiler uses split linking give option
\code{-s MYPATH/theme-d-in-theme-d/theme-d-compile-b.build}.

Programs \code{compile-tests.scm}, \code{link-test-programs.scm},
and \code{link-to-modules.scm} accept the following options:
\begin{itemize}
    \item \code{-b} \metavar{bootstrap-path}: Use the
          bootstrapped compiler or linker. The argument is the path to file
          \code{theme-d-compile-b.go} or \code{theme-d-link-b.go}.
    \item \code{-B} \metavar{bootstrap-dir}: Use the
          modularly linked bootstrapped compiler or linker. The argument shall be
          either directory \code{build1} or \code{bootstrap} in the bootstrapped
          environment.
    \item \code{-s} \metavar{split-dir}:
          Use the compiler or linker linked with split linking.
\end{itemize}
Programs \code{link-test-programs.scm}
and \code{link-to-modules.scm} accept also 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}).
\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.

If you want to clean the testing environment in order to rebuild and rerun the
examples and the tests give command \code{./clean-test-env.sh} in the
subdirectory \code{testing}. If you want to keep the compilation output but
clean the other files use command \code{./link-clean-test.env.sh}.


\section{Computing Makefile Dependencies}

The software includes three scripts to compute makefile dependencies for \theme\
files:
\code{compute-theme-d-pcode-deps} for
\theme\ pseudocode files (\code{*.tc?}),
\code{compute-theme-d-program-deps} for monolithically linked programs
(\code{*.go}),
and
\code{compute-theme-d-module-deps} for modularly linked modules (\code{*.go}).
Each of these commands takes two arguments: the source code file (\code{*.th?})
for which to compute the dependencies and the unit path to specify the units
included in the dependency computation. Only dependencies with the specified
unit path are included. The unit path is computed from the unit name by dropping
the last symbol. For example, set the second argument to \code{examples} for the
example programs.


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