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 676, Sat Jun 24 03:37:03 2000 UTC revision 677, Mon Jun 26 00:56:56 2000 UTC
# Line 702  Line 702 
702    
703  {\tt CM.Library.descr} extracts a string describing the location of  {\tt CM.Library.descr} extracts a string describing the location of
704  the CM description file associated with the given library.  The syntax  the CM description file associated with the given library.  The syntax
705  of this string is the same as that being used by CM's master-slave  of this string is almost the same as that being used by CM's
706  protocol (see section~\ref{sec:pathencode}).  master-slave protocol (see section~\ref{sec:pathencode}).
707    
708  {\tt CM.Library.osstring} produces a string denoting the given  {\tt CM.Library.osstring} produces a string denoting the given
709  library's description file using the underlying operating system's  library's description file using the underlying operating system's
# Line 1125  Line 1125 
1125  rule function.  It is in each rule's own responsibility to assign  rule function.  It is in each rule's own responsibility to assign
1126  meaning to its options.  meaning to its options.
1127    
1128  The {\tt sml} class accepts one parameter which must be either the  \subsubsection*{Parameters for class {\tt sml}}
1129  word {\tt shared} or the word {\tt private}.  (Technically, the  
1130  strings {\tt private} and {\tt shared} fall under the {\em filename}  The {\tt sml} class accepts two optional parameters.  One is the {\em
1131  category from above, but the tool ignores that aspect and uses the  sharing annotation} that was explained earlier (see
1132  name directly.) If {\tt shared} is specified, then dynamic state  Section~\ref{sec:sharing}).  The sharing annotation must be one of the
1133  created by the compilation unit at link-time must be shared across  two strings {\tt shared} and {\tt private}.  If {\tt shared} is
1134  invocations of {\tt CM.make} or {\tt CM.autoload}.  As explained  specified, then dynamic state created by the compilation unit at
1135  earlier (Section~\ref{sec:sharing}), the {\tt private} annotation  link-time must be shared across invocations of {\tt CM.make} or {\tt
1136  means that dynamic state cannot be shared across such calls to {\tt  CM.autoload}.  The {\tt private} annotation, on the other hand, means
1137  CM.make} or {\tt CM.autoload}.  that dynamic state cannot be shared across such calls to {\tt CM.make}
1138    or {\tt CM.autoload}.
1139    
1140    The other possible parameter for class {\tt sml} is a sub-option
1141    list labeled {\tt setup} and can be used to specify code that will be
1142    executed just before and just after the compiler is invoked for the
1143    ML source file.  Code to be executed before compilation is labeled
1144    {\tt pre}, code to be executed after compilation is complete is
1145    labeled {\tt post}; either part is optional.  Executable code itself
1146    is specified using strings that contain ML source text.
1147    
1148    For example, if one wishes to disable warning messages for a specific
1149    source file {\tt poorlywritten.sml} (but not for others), then one
1150    could write:
1151    
1152    \begin{verbatim}
1153      poorlywritten.sml (setup:(pre: "local open Compiler.Control\n\
1154                                     \   in val w = !printWarnings before\n\
1155                                     \              printWarnings := false\n\
1156                                     \  end;"
1157                                post:"Compiler.Control.printWarnings := w;"))
1158    \end{verbatim}
1159    
1160    \noindent Note that neither the pre- nor the post-section will be
1161    executed if the ML file does not need to be compiled.
1162    
1163    The pre-section is compiled and executed in the current
1164    toplevel-environment while the post-section uses the
1165    toplevel-environment augmented with definitions from the pre-section.
1166    After the ML file has been compiled and the post-section (if present)
1167    has completed execution, definitions made by either section will be
1168    erased.  This means that setup code for other files {\em cannot} refer
1169    to them, and neither can code that in the future might be entered at
1170    top level.
1171    
1172    \subsubsection*{Parameters for class {\tt cm}}
1173    
1174  The {\tt cm} class understands two kinds of parameters.  The first is  The {\tt cm} class understands two kinds of parameters.  The first is
1175  a named parameter labeled by the string {\tt version}.  It must have  a named parameter labeled by the string {\tt version}.  It must have
# Line 1185  Line 1220 
1220  $f$, the tool produces two targets $f${\tt .sig} and $f${\tt .sml},  $f$, the tool produces two targets $f${\tt .sig} and $f${\tt .sml},
1221  both of which are always treated as ML source files.  Parameters are  both of which are always treated as ML source files.  Parameters are
1222  passed on without change to the $f${\tt .sml} file but not to the  passed on without change to the $f${\tt .sml} file but not to the
1223  $f${\tt .sig} file.  This means that the parameter can either be the  $f${\tt .sig} file.
 word {\tt private} or the word {\tt shared}, and that this sharing  
 annotation will apply to the $f${\tt .sml} file.  
1224    
1225  The tool invokes the {\tt ml-yacc} command if the targets are  The tool invokes the {\tt ml-yacc} command if the targets are
1226  ``outdated''.  A target is outdated if it is missing or older than the  ``outdated''.  A target is outdated if it is missing or older than the
# Line 1920  Line 1953 
1953  \subsection{Pathname protocol encoding}  \subsection{Pathname protocol encoding}
1954  \label{sec:pathencode}  \label{sec:pathencode}
1955    
1956  The master-slave protocol encodes pathnames in the following way:  A path encoded by CM's master-slave protocol encoding does not only
1957    specify which file a path refers to but also, in some sense, specifies
1958    why CM constructed this path in the first place.  For example, the
1959    encoding {\tt a/b/c.cm:d/e.sml} represents the file {\tt a/b/d/e.sml}
1960    but also tells us that it was constructed by putting {\tt d/e.sml}
1961    into the context of description file {\tt a/b/c.cm}.  Thus, an encoded
1962    path name consists of one or more colon-separated ({\bf :}) sections,
1963    and each section consists of slash-separated ({\bf /}) arcs.  To find
1964    out what actual file a path refers to, it is necessary to erase all
1965    arcs that precede colons.
1966    
1967    The first section is special because it also specifies whether the
1968    whole path was relative or absolute, or whether it was an anchored
1969    path.
1970    
1971  A pathname consists of {\bf /}-separated arcs (like Unix patnames).  \begin{description}
1972  The first arc can be interpreted relative to the current working directory,  \item[Anchored paths] start with a dollar-symbol {\bf \$}.  The name
1973  relative to the root of the file system, relative to the root of a  of the anchor is the string between this leading dollar-symbol and the
1974  volume (on systems that support separate volumes), or relative to a  first occurence of a slash {\bf /} within the first section.  The
1975  directory that corresponds to a pathname anchor.  The first character  remaining arcs of the first section are interpreted relative to the
1976  of the pathname is used to distinguish between these cases.  current value of the anchor.
1977    \item[Absolute paths] start either with a percent-sign {\bf \%} or a
1978    slash {\bf /}.  The canonical form is the one with the percent-sign:
1979    it specifies the volume name between the {\bf \%} and the first slash.
1980    The common case where the volume name is empty (i.e, {\em always} on
1981    Unix systems), the path starts with {\bf /}.
1982    \item[Relative paths] are all other paths.
1983    \end{description}
1984    
1985  \begin{itemize}  Encoded path names never contain white space.  Moreover, the encoding
1986  \item If the name starts with {\bf ./}, then the name is relative to  for path arcs, volume names, or anchor names does not contain special
1987  the working directory.  characters such as {\bf /}, {\bf \$}, {\bf \%}, {\bf :}, {\bf
1988  \item If the name starts with {\bf /}, then the name is relative to  \verb|\|}, {\bf (}, and {\bf )}.  Instead, should white space or
1989  the file system root.  special characters occur in the non-encoded name, then they will be
1990  \item If the name starts with {\bf \%}, then the substring between this  encoded using the escape-sequence \verb|\ddd| where {\tt ddd} is the
1991  {\bf \%} and the first {\bf /} is used as the name of a volume and the  decimal value of the respective character's ordinal number (i.e, the
1992  remaining arcs are interpreted relative to the root of that volume.  result of applying {\tt Char.ord}).
1993  \item If the name starts with {\bf \$}, then the substring between  
1994  this {\bf \$} and the first {\bf /} must be the name of a pathname  The so-called {\em current} arc is encoded as {\bf .}, the {\em
1995  anchor.  The remaining arcs are interpreted relative to the directory  parent} arc uses {\bf ..} as its representation.  On some operating
1996  that (on the slave side) is denoted by the anchor.  systems it can happen that although an arc is either {\tt .} or {\tt
1997  \item Any other name is interpreted relative to the current working  ..}, it still does not actually refer to the current or the parent
1998  directory.  arc.  In such a case, CM will encode the dots in these names using the
1999  \end{itemize}  \verb|\ddd| method, too.
2000    
2001    When issuing progress messages, CM shows path names in a form that is
2002    almost the same as the protocol encoding.  The only difference is that
2003    arcs that precede colon-sign {\bf :} are enclosed within parentheses
2004    to emphasize that they are ``not really there''.  The same form is
2005    also used by {\tt CM.Library.descr}.
2006    
2007  \subsection{Parallel bootstrap compilation}  \subsection{Parallel bootstrap compilation}
2008    

Legend:
Removed from v.676  
changed lines
  Added in v.677

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