Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Diff of /sml/trunk/src/cm/Doc/manual.tex
ViewVC logotype

Diff of /sml/trunk/src/cm/Doc/manual.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 734, Sun Nov 19 05:27:41 2000 UTC revision 735, Tue Nov 21 12:15:55 2000 UTC
# Line 8  Line 8 
8  \columnsep0.25in  \columnsep0.25in
9    
10  \newcommand{\smlmj}{110}  \newcommand{\smlmj}{110}
11  \newcommand{\smlmn}{30}  \newcommand{\smlmn}{31}
12    
13  \author{Matthias Blume \\  \author{Matthias Blume \\
14  Research Institute for Mathematical Sciences \\  Research Institute for Mathematical Sciences \\
# Line 472  Line 472 
472  name is {\it path}{\tt /}{\it file}{\tt .cm} will be resolved relative  name is {\it path}{\tt /}{\it file}{\tt .cm} will be resolved relative
473  to {\it path}, i.e., relative to the directory that contains the  to {\it path}, i.e., relative to the directory that contains the
474  description file.  description file.
475  \item[Relative pathnames that have been entered interactively,] for  \item[Relative pathnames that have been entered interactively,]
476  example as an argument to one of CM's interface functions,  usually as an argument to one of CM's interface functions, will be
477  will be resolved in the OS-specific manner, i.e., relative to the  resolved in the OS-specific manner, i.e., relative to the current
478  current working directory.  However, CM will internally represent the  working directory.  However, notice that some of CM's operations (see
479  name in such a way that it remembers the corresponding working  section~\ref{sec:autoload}---autoload) will be executed lazily and,
480  directory.  Should the working directory change during an ongoing CM  thus, can occur interleaved with arbitary other operations---including
481  session while there still is a reference to the name, then CM will  changes of the working directory.  This is handled by CM in such a way
482  switch its mode of operation and prepend the path of the original  that it appears as if all path derived from an interactive relative
483  working directory. As a result, two names specified using identical  path $p$ had been completely resolved at the time $p$ was entered. As
484  strings but at different times when different working directories were  a result, two names specified using identical strings but at different
485  in effect will be kept distinct and continue to refer to the file  times when different working directories were in effect will be kept
486  system locations that they referred to when they were first seen.  apart and continue to refer to their respective original file system
487    locations.
488  \item[Anchored paths] consist of an anchor name (of non-zero length)  \item[Anchored paths] consist of an anchor name (of non-zero length)
489  and a non-empty list of additional arcs.  The name is enclosed by  and a non-empty list of additional arcs.  The name is enclosed by
490  the path's leading {\bf \$} on the left and the path's first {\bf /}  the path's leading {\bf \$} on the left and the path's first {\bf /}
# Line 653  Line 654 
654  The boolean result of {\tt CM.recomp} and {\tt CM.stabilize} indicates  The boolean result of {\tt CM.recomp} and {\tt CM.stabilize} indicates
655  success or failure of the operation ({\tt true} = success).  success or failure of the operation ({\tt true} = success).
656    
657  \subsubsection{Linking}  \subsubsection{Linking and execution}
658    
659  In SML/NJ, linking means executing top-level code (i.e., module  In SML/NJ, linking means executing top-level code (i.e., module
660  creation and initialization code) of each compilation unit.  The  creation and initialization code) of each compilation unit.  The
# Line 1269  Line 1270 
1270  this, the member name is followed by a colon {\bf :} and the name of  this, the member name is followed by a colon {\bf :} and the name of
1271  the member class.  All class names are case-insensitive.  the member class.  All class names are case-insensitive.
1272    
1273  In addition to genuine tool classes, there are two member classes  In addition to genuine tool classes, there are four member classes
1274  that refer to facilities internal to CM: {\tt sml} is the class of  that refer to facilities internal to CM:
1275  ordinary ML source files and {\tt cm} is the class of CM library or  \begin{description}
1276  group description files.  \item[{\tt sml}] is the class of ordinary ML source files.
1277    \item[{\tt cm}] is the class of CM library or group description files.
1278  CM automatically classifies files with a {\tt .sml} suffix, a {\tt  \item[{\tt tool}] is the class of {\em plugin tools}.  Its purpose is
1279  .sig} suffix, or a {\tt .fun} suffix as ML-source, file names ending  to trigger the loading of an auxiliary plugin module---usually with the
1280  in {\tt .cm} as CM descriptions.\footnote{Suffixes that are not known  purpose of extending the set of tool classes that CM understands.
1281  and for which no plugin module can be found are treated as ML source  See section~\ref{sec:plugintools} for more information.
1282  code.  However, as new tools are added there is no guarantee that  \item[{\tt suffix}] is a class similar to {\tt tool}.  Its purpose is
1283  this behavior will be preserved in future versions of CM.}  to declare additional filename suffixes and their associated classes.
1284    See section~\ref{sec:plugintools}.
1285    \end{description}
1286    
1287    By default, CM automatically classifies files with a {\tt .sml}
1288    suffix, a {\tt .sig} suffix, or a {\tt .fun} suffix as ML-source, file
1289    names ending in {\tt .cm} as CM descriptions.\footnote{Suffixes that
1290    are not known and for which no plugin module can be found are treated
1291    as ML source code.  However, as new tools are added there is no
1292    guarantee that this behavior will be preserved in future versions of
1293    CM.}
1294    
1295  \subsection{Tool parameters}  \subsection{Tool parameters}
1296  \label{sec:toolparam}  \label{sec:toolparam}
# Line 1383  Line 1394 
1394  the current anchor environment to form the environment that is used  the current anchor environment to form the environment that is used
1395  while processing the contents of the named CM description file.  while processing the contents of the named CM description file.
1396    
1397    \subsubsection{Parameters for classes {\tt tool} and {\tt suffix}}
1398    
1399    Class {\tt tool} (see the discussion is section~\ref{sec:localtools})
1400    does not accept any parameters.
1401    
1402    Class {\tt suffix} (see section~\ref{sec:localsuffixes}) takes one
1403    mandatory parameter which is either simply a class name or the same
1404    class name labeled by {\tt class}.  Thus, the following two lines are
1405    equivalent:
1406    
1407    \begin{verbatim}
1408    ml : suffix (sml)
1409    ml : suffix (class:sml)
1410    \end{verbatim}
1411    
1412    There are no recognized filename suffixes for these two classes.
1413    
1414  \subsection{Built-in tools}  \subsection{Built-in tools}
1415  \label{sec:builtin-tools}  \label{sec:builtin-tools}
1416    
# Line 1936  Line 1964 
1964  structure {\tt Tools} which is exported by the {\tt \$smlnj/cm/tools.cm}  structure {\tt Tools} which is exported by the {\tt \$smlnj/cm/tools.cm}
1965  library.  library.
1966    
1967    \subsection{Adding simple shell-command tools}
1968    
1969  If the tool is implemented as a ``typical'' shell command, then all  If the tool is implemented as a ``typical'' shell command, then all
1970  that needs to be done is a single call to:  that needs to be done is a single call to:
1971    
# Line 2049  Line 2079 
2079  interface {\tt Tools.registerClass}.  interface {\tt Tools.registerClass}.
2080    
2081  \subsection{Plug-in Tools}  \subsection{Plug-in Tools}
2082    \label{sec:plugintools}
2083    
2084    \subsubsection{Automatically-loaded, global plug-in tools}
2085    
2086  If CM comes across a member class name $c$ that it does not know  If CM comes across a member class name $c$ that it does not know
2087  about, then it tries to load a plugin module named {\tt \$/}$c${\tt  about, then it tries to load a plugin module named {\tt \$/}$c${\tt
2088  -tool.cm} or {\tt ./}$c${\tt -tool.cm}.  If it sees a file whose name  -tool.cm}.  If it sees a file whose name ends in suffix $s$ for which
2089  ends in suffix $s$ for which no explicit member class has been  no explicit member class has been specified in the CM description file
2090  specified in the CM description file and for which automatic  and for which automatic member classification fails, then it tries to
2091  member classification fails, then it tries to load a plugin module  load a plugin module named {\tt \$/}$s${\tt -ext.cm}.  The so-loaded
2092  named {\tt \$/}$s${\tt -ext.cm} or {\tt ./}$s${\tt -ext.cm}.  The  module can then register the required tool which enables CM to
2093  so-loaded module can then register the required tool which enables CM  successfully deal with the previously unknown member.
 to successfully deal with the previously unknown member.  
2094    
2095  This mechanism makes it possible for new tools to be added by simply  This mechanism makes it possible for new tools to be added by simply
2096  placing appropriately-named plug-in libraries in such a way that CM  placing appropriately-named plug-in libraries into a global tool
2097  can find them.  This can be done in one of two ways:  repository.  Of course, it will also require a corresponding
2098    re-configuration of the anchor environment.  In other words, for
2099    general-purpose tools that are installed in some central place,
2100    corresponding tool description files {\tt \$/}$c${\tt -tool.cm} and
2101    {\tt \$/}$s${\tt -ext.cm} should be registered using the path anchor
2102    mechanism.  If this is done, actual description files can be placed in
2103    arbitrary locations.
2104    
2105    \subsubsection{Explicitly-loaded, local plug-in tools}
2106    \label{sec:localtools}
2107    
2108    Some projects might want to use their own special-purpose tools for
2109    which a global installation is not convenient or not appropriate.  In
2110    such a case, the project's description file can explicitly demand the
2111    tool to be registered temporarily.  This is the purpose of the special
2112    tool class {\tt tool}.  Example:
2113    
2114  \begin{enumerate}  \begin{verbatim}
2115  \item For general-purpose tools that are installed in some central  Library
2116  place, corresponding tool description files {\tt \$/}$c${\tt -tool.cm}      structure Foo
2117  and {\tt \$/}$s${\tt -ext.cm} should be registered using the path  is
2118  anchor mechanism.  If this is done, actual description files can be      bar-tool.cm : tool
2119  placed in arbitrary locations.      foo.b : bar
2120  \item For special-purpose tools that are part of a specific program  \end{verbatim}
2121  and for which there is no need for central installation, one should  
2122  simply put the tool description files into the same directory as the  Here, the member whose class is {\tt tool} (i.e, {\tt bar-tool.cm})
2123  one that contains their ``client'' description file.  must be the CM description file of the tool's implementation.  The
2124  \end{enumerate}  difference to class {\tt cm} is that the so-specified library does not
2125    become part of the current project but is loaded and linked
2126    immediately via {\tt CM.load\_plugin}, causing one or more new classes
2127    and their classifiers to be registered.
2128    
2129    If we assume that loading {\tt bar-tool.cm} causes a class {\tt bar}
2130    to be registered with its associated rule (e.g., by invoking {\tt
2131    Tools.registerStdShellCmdTool}), the class name {\tt bar} will be
2132    available for all subsequent members of the current description file.
2133    Likewise, classifiers (e.g., filename suffixes) registered by {\tt
2134    bar-tool.cm} will also be available.
2135    
2136    The effect of registering classes and classifiers using class {\tt
2137    tool} lasts until the end of the current description file.  Moreover,
2138    the effect is {\em restricted} to the current description file.  This
2139    means that other description files that also want to use class {\tt
2140    bar} will have to have their own {\tt tool} entry.
2141    
2142    \noindent{\bf Important:} Registration of classes and classifiers
2143    happens by link-time side-effect.  If a class or a classifier has been
2144    registered locally via class {\tt tool}, then CM will {\em undo} this
2145    registration when finished with the corresponding description file.
2146    Therefore, it is important that the required side-effect happens {\em
2147    every time} the tool implementation is loaded!  Unfortunately, CM's
2148    default treatment of link-time state (see section~\ref{sec:sharing})
2149    would defeats this.  Therefore, it is necessary to mark the side-effecting
2150    ML code in the tool's implementation as {\em private}.
2151    
2152    \subsubsection{Locally declared suffixes}
2153    \label{sec:localsuffixes}
2154    
2155    It is sometimes convenient to locally add another recognized filename
2156    suffix to an already registered class.  This is done by using the
2157    special tool class {\tt suffix}.  For example, a programmer who has
2158    named all her ML files in such a way that they end in {\tt .ml}
2159    could write near the beginning of her description file:
2160    
2161    \begin{verbatim}
2162        ml : suffix (sml)
2163    \end{verbatim}
2164    
2165    For the remainder of the current description file, all such {\tt
2166    .ml}-files will now be classified under {\tt sml}.
2167    
2168  \section{Parallel and distributed compilation}  \section{Parallel and distributed compilation}
2169  \label{sec:parmake}  \label{sec:parmake}
# Line 3135  Line 3224 
3224  SML/NJ's implementation:  SML/NJ's implementation:
3225    
3226  \begin{center}  \begin{center}
3227  \begin{tabular}{p{2.8in}||p{2.3in}|c|c}  \begin{tabular}{p{2.9in}||p{2.2in}|c|c}
3228  name & description & installed & loaded \\  name & description & installed & loaded \\
3229  \hline\hline  \hline\hline
3230  {\tt \$MLRISC/Lib.cm} & utility library for MLRISC backend & always &  {\tt \$MLRISC/Lib.cm} & utility library for MLRISC backend & always &
# Line 3157  Line 3246 
3246  \hline  \hline
3247  {\tt \$MLRISC/IA32.cm} & IA32-specific MLRISC backend & always & no \\  {\tt \$MLRISC/IA32.cm} & IA32-specific MLRISC backend & always & no \\
3248  \hline\hline  \hline\hline
3249  {\tt \$/comp-lib.cm} & utility library for compiler & always & no \\  {\tt \$/pickle-lib.cm} & utility library for compiler and CM & always & no \\
3250  \hline  \hline
3251  {\tt \$smlnj/viscomp/core.cm} & architecture-neutral core of compiler  {\tt \$smlnj/viscomp/core.cm} & architecture-neutral core of compiler
3252  & always & no \\  & always & no \\
# Line 3180  Line 3269 
3269  {\tt \$smlnj/init/init.cmi} & initial ``glue''; implementation of  {\tt \$smlnj/init/init.cmi} & initial ``glue''; implementation of
3270  pervasive environment & always & no \\  pervasive environment & always & no \\
3271  \hline \hline  \hline \hline
3272    {\tt \$smlnj/internal/cm-sig-lib.cm} & signatures {\tt CM} and {\tt
3273    CMB} & always & no \\
3274    \hline
3275    {\tt \$smlnj/internal/srcpath-lib.cm} & implementation of an internal
3276    ``source path'' abstraction used by the compilation manager & always &
3277    no \\
3278    \hline
3279  {\tt \$smlnj/internal/cm-lib.cm} & implementation of compilation  {\tt \$smlnj/internal/cm-lib.cm} & implementation of compilation
3280  manager (not yet specialized to specific backends) & always & no \\  manager (not yet specialized to specific backends) & always & no \\
3281  \hline  \hline

Legend:
Removed from v.734  
changed lines
  Added in v.735

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0