%!TEX root = manual.tex
%
\chapter{Listing of all CM-specific environment variables}

Most control parameters that affect CM's operation can be adjusted
using environment variables $v_s$ at startup time, i.e, when the {\tt
sml} command is invoked.  Each such parameter has a default setting.
Default settings are determined at bootstrap time, i.e., the time when
the heap image for SML/NJ's interactive system is
built.\footnote{
  Normally this is the same as installation time, but
  for SML/NJ compiler hackers there is also a {\tt makeml} script for
  the purpose of bootstrapping.
}
At bootstrap time, it is possible to
adjust defaults by using a set of environment variables $v_b$.  In the
current version of CM it is always the case that $v_s = v_b$.  (In
older versions this was not the case.) If neither $v_s$ nor $v_b$ were
set, a hard-wired fallback value will be used.

The rule for constructing the name $v_s$ (and $v_b$) is the
following: For each adjustable parameter $x$ there is a {\em name
stem}.  If the stem for $x$ is $s$, then $v_s = v_b = \mbox{\tt CM\_}s$.

Since the normal installation procedure for SML/NJ sets some of the
$v_b$ variables at bootstrap time, there are two columns with default
values in the following table.  The value labeled {\em fallback} is
the one that would have been used had there been no environment
variable at bootrap time, the one labeled {\em default} is the one the
user will actually see.

To save space, the table lists the stem but not the names for its
associated (longer) $v_s$ and $v_b$.  For example, since the the table
shows {\tt VERBOSE} in the row for {\tt CM.Control.verbose}, CM's
per-session verbosity can be adjusted using {\tt CM\_VERBOSE}.

\begin{center}
\begin{small}
\begin{tabular}{@{}l||c|c|c|c|p{1.6in}@{}}
{\tt CM.Control.}$c$ & stem & type & fallback & default & default's meaning \\
\hline \hline
{\tt verbose} & {\tt VERBOSE} & {\tt bool} & {\tt true} & same & issue
progess messages \\
{\tt debug} & {\tt DEBUG} & {\tt bool} & {\tt false} & same & do not
issue debug messages \\
{\tt keep\_going} & {\tt KEEP\_GOING} & {\tt bool} & {\tt false} &
same & quit on first error \\
(none) & {\tt PATHCONFIG} & {\tt string} & see below & see below &
central path configuration file \\
{\tt parse\_caching} & {\tt PARSE\_CACHING} & {\tt int} & {\tt 100} &
same & at most 100 parse trees will be cached in main memory \\
(none) & {\tt LOCAL\_PATHCONFIG} & {\tt string} & see below & same &
user-specific path configuration file \\
{\tt warn\_obsolete} & {\tt WARN\_OBSOLETE} & {\tt bool} & {\tt true}
& same & issue warnings about obsolete C-style operators in
description files \\
{\tt conserve\_memory} & {\tt CONSERVE\_MEMORY} & {\tt bool} & {\tt
false} & same & avoid repeated I/O operations by keeping certain
information in main memory
\end{tabular}
\end{small}
\end{center}

The fallback for {\tt PATHCONFIG} is {\tt /usr/lib/smlnj-pathconfig},
but the standard installation overrides this and uses {\tt
\$INSTALLDIR/lib/pathconfig} (where {\tt \$INSTALLDIR} is the SML/NJ
installation directory) instead.

The default for the ``local'' path configuration file is {\tt
.smlnj-pathconfig}. This file is located in the user's home directory
(given by the environment variable {\tt \$HOME}).

Control parameters can also be set using command-line parameters (see
\chapref{chap:cmdline}).
