% (C) Copyright International Business Machines Corporation 23 January 
% 1990.  All Rights Reserved. 
%  
% See the file USERAGREEMENT distributed with this software for full 
% terms and conditions of use. 
\subsection{Compiling Hermes to C}
\label{c-coded}

The {\tt pcom} command described earlier in this section produces
compiled object code in a special form called {\em LI
Code}\footnote{``LI'' stands for ``Language of the Interpreter.''} The
Hermes interpreter executes LI instructions in an interpretive manner.
This arrangement is quite flexible and simplified the development of
the Hermes compiler, since LI instructions were designed specifically
to support the operations performed by Hermes programs.  However,
performance suffers because each LI instruction execution incurs 
substantial interpreter and scheduling overhead.

With release 0.8alpha of the Hermes system, an alternative is
available on platforms that support dynamic loading of Unix object
files.  Specifically, the {\tt chcode} utility will produce C language
source from a Hermes program that has been compiled into LI code.
When the resulting C source files are compiled and linked into the
running interpreter, the Hermes programs from which they were derived
execute from 1.5 to 3 times faster.

This section describes how the {\tt chcode} utility is used.  A
document titled ``Transformation of Hermes Target Code into C-Code'',
by Bill Silverman, describes some of the internal design and logic of
the tool.  It is included with the distribution in both LaTeX source
and Postscript form in the directory {\tt doc/chcode}.

For platforms that support the {\tt chcode} tool, the entire set of
Hermes ``system'' binaries included in the {\tt bin} directory of the
distribution is also provided in ``C-Coded'' form.

\subsubsection{Using the {\tt chcode} Utility}

{\tt Chcode} is a Hermes program that is invoked as follows:

$$\hbox{\tt chcode {\em [options]} {\em process-module} $\ldots$}$$

Each {\tt process-module} argument should specify the name of a
compiled process module (i.e. one for which a {\tt .po} file has been
produced by {\tt pcom}).  The {\tt chcode} program produces, for each
process module, some or all of the following, depending on the options
that are specified:

\begin{itemize}

\item A ``residual {\tt .po}'' file, containing LI code that usually
consists entirely of {\tt ESCAPE} instructions.  Each {\tt ESCAPE}
instruction, when executed, causes a branch to an entry point in the
generated C code.

\item C source code that implements the input program.

\item A Unix ``object'' file produced by the system's C compiler,
suitable for dynamic linking into the running Hermes interpreter.

\end{itemize}

The C source can be placed in a source file of its own (a {\tt
.c} file), or it can be incorporated directly into the {\tt .po} file
produced by {\tt chcode}.  Similarly, the Unix object code can be
written to a {\tt .o} file or incorporated into the resulting {\tt
.po} file.

\subsubsection{Options}

The {\tt chcode} has many options that can be specified on the command
line, as follows: 

\begin{itemize}

\item {\tt -verbose}---Report all activity as it progresses.

\item {\tt -quiet}---Suppress all reports, except serious diagnostics.

\item {\tt -comment}---Include comments in the generated C source,
indicating the LI instructions being implemented by the various
sections of code.  This is extremely helpful for debugging the {\tt
chcode} transformations.

\item {\tt -load={\em<pathlist>}}---Specifies the search path used to
locate the {\tt .po} files to be transformed.  The default is to use
the {\tt pathLoad} capability provided in the resource manager to load
{\tt .po} files.

\item {\tt -store={\em<path>}}---Specifies the directory in which the
generated {\tt .po} files are stored.  If no {\em<path>} is specified,
or if this option is omitted altogether, transformed {\tt .po} files
are saved in the current directory (as given by the {\tt getCwd}
resource). 

\item {\tt -fullpaths}---When Unix object code is written to {\tt .o}
files, the names of these files are saved in the transformed {\tt .po}
file.  If this option is present full Unix path names are stored;
otherwise, just the final path component is stored.  In the latter
case, the dynamic loader locates the {\tt .o} file at runtime by means
of the {\tt HCOBJPATH} environment variable.

\item {\tt -keepC}---Incorporate the C source text directly into the
transformed {\tt .po} file.

\item {\tt -keepObj}---Incorporate the Unix object code directly into
the transformed {\tt .po} file.

\item {\tt -storeC={\em<path>}}---Specifies the directory where C
source files ({\tt .c} files) are stored.  If no {\em<path>} is given,
the current directory (as given by the {\tt getCwd} resource) is used.
If the option is omitted altogether, C source files are not produced.
(More precisely, temporary files are produced and deleted following
the transformation.)

\item {\tt -storeObj={\em<path>}}---Specifies the directory where Unix
object files ({\tt .o} files) are stored.  If no {\em<path>} appears,
or if this option is omitted entirely, object files are stored in the
first directory specified in the {\tt HCOBJPATH} environment variable;
if that variable is not set, the current directory (according to the
{\tt getCwd} resource) is used.

\item {\tt -nostoreObj}---Causes {\tt chcode} not to produce Unix
object files ({\tt .o} files).  If this option is given and {\tt
-keepObj} is not, {\tt chcode} will not compile the generated C source
code.

\item {\tt -notransform}---Prevents transformation of the original
{\tt .po} files.  In this case, the input {\tt .po} files should be
the result of previous transformations by {\tt chcode}.  This option
can be used, for example, to recompile previously generated C sources
for a second execution platform, without redoing the entire
transformation.  The previously generated C source must either have
been incorporated into the {\tt .po} file or it must be availble in a
{\tt .c} file in the directory specified in the {\tt -storeC} option.

\item {\tt -interpret={\em<opcodes>}}---Indicates a list of LI
instruction opcodes that should not be transformed into C code.  The
``residual'' LI code in the transformed {\tt .po} files produced by
{\tt chcode} will include {\tt ESCAPE} instructions, as well as the
instructions appearing on this list.  This option was used extensively
as the {\tt chcode} utility was developed, so the entire repertoire of
LI instructions could be phased in gradually.  It is not that this
option will be useful at this point.

\item {\tt -debug={\em<list>}}---Turns on the debug options named in
{\em <list>}.  Option names should be separated by commas.  Supported
options are listed below.  As with all other options, {\tt -debug} can
appear only once; multiple debug options must be listed in that one
appearance.  The currently supported debug options are:
\begin{itemize}
\item {\tt compile}---Echo C compilation commands as they are invoked.
\item {\tt config}---Print configuration parameters.
\end{itemize}

\item {\tt -compilecmd={\em<string>}}---Specifies the command to be
invoked to compile a C source file.  The following symbols can be
embedded in {\em<string>}, and are replaced by the indicated
compilation parameters or otherwise interpreted as indicated by {\tt
chcode}:
\begin{itemize}
\item{\tt \~{};} (tilde, semicolon): Delimits multiple commands that
are invoked in sequence to perform a compilation.
\item{\tt \~{}C} (tilde, ``C''): Replaced by the full pathname of the C
source file to be compiled.
\item{\tt \~{}O} (tilde, letter ``O''): Replaced by the full pathname of
the Unix object file ({\tt .o} file) to be produced.
\item{\tt \~{}N} (tilde, ``N''): Replaced by the name of the generated C
function.
\end{itemize}
In addition, the replacements described for configuration parameters
below are performed for {\em <string>}.  If this option is not
present, the value of the {\tt COMPILECMD} configuration parameter is
used. 

\item {\tt -chconfig={\em<file>}}---Specifies the file from which to
load {\tt chcode} configuration parameters.  If this option is not
present, {\tt chcode} looks for the file {\em
hermes-root}/chaux/chcode.cfg. 

Each line in the configuration file should be of the form {\tt{\em
var}={\tt text}} or {\tt{\em var}({\em arch})={\em text}}, where {\em
var} is the name of a configuration variable, and {\em text} is its
value.  If {\tt({\em arch})} is specified, the parameter specification
applies only when the Hermes interpreter is running on the named
platform.  An architecture-specific parameter definition overrides a
non-specific definition of the same name.  Long parameter definitions
can be split into multiple lines by ending all but the last line with
a backslash character.

Each {\em text} value may contain the following embedded sequences,
which are replaced by the indicated text:
\begin{itemize}
\item{\tt \~{}P[{\em var}]}: Replaced with the value of the
configuration parameter {\em var}.
\item{\tt \~{}E[{\em var}]}: Replaced with the value of the environment
variable {\em var}.
\item{\tt \~{}\~{}} (double tilde): Replaced with a single tilde.
\end{itemize}

\end{itemize}
