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 536, Fri Feb 18 16:51:54 2000 UTC revision 537, Fri Feb 18 17:20:16 2000 UTC
# Line 13  Line 13 
13    
14  \title{{\bf CM}\\  \title{{\bf CM}\\
15  The SML/NJ Compilation and Library Manager \\  The SML/NJ Compilation and Library Manager \\
16  {\it\small (for SML/NJ version 110.25 and later)} \\  {\it\small (for SML/NJ version 110.26 and later)} \\
17  User Manual}  User Manual}
18    
19  \setlength{\parindent}{0pt}  \setlength{\parindent}{0pt}
# Line 59  Line 59 
59    
60  \section{The CM model}  \section{The CM model}
61    
62  A CM library is a collection of ML source files and may also contain  A CM library is a (possibly empty) collection of ML source files and
63  references to other libraries together with an explicit export  may also contain references to other libraries.  Each library comes
64  interface.  The export interface lists all toplevel-defined symbols of  with an explicit export interface which lists all toplevel-defined
65  the library that shall be exported to its clients.  A library is  symbols of the library that shall be exported to its clients.  A
66  described by the contents of its {\em description file}.  library is described by the contents of its {\em description file}.
67    
68  \noindent Example:  \noindent Example:
69    
# Line 83  Line 83 
83  such exports appear between the keywords {\tt Library} and {\tt is}.  such exports appear between the keywords {\tt Library} and {\tt is}.
84  The {\em members} of the library are specified after the keyword {\tt  The {\em members} of the library are specified after the keyword {\tt
85  is}.  Here we have three ML source files ({\tt bar.sig}, {\tt  is}.  Here we have three ML source files ({\tt bar.sig}, {\tt
86  foo.sml}, and {\tt helper.sml}) and a reference to one external  foo.sml}, and {\tt helper.sml}) as well as a reference to one external
87  library ({\tt basis.cm}).  The entry {\tt basis.cm} typically denotes  library ({\tt basis.cm}).  The entry {\tt basis.cm} typically denotes
88  the description file for the {\it Standard ML Basis  the description file for the {\it Standard ML Basis
89  Library}~\cite{reppy99:basis}; most programs will want to list it in  Library}~\cite{reppy99:basis}; most programs will want to list it in
# Line 111  Line 111 
111  \end{enumerate}  \end{enumerate}
112    
113  Note that these rules do not require the exports of sub-groups or  Note that these rules do not require the exports of sub-groups or
114  sub-libraries to be distinct from the exports of ML source files.  sub-libraries to be distinct from the exports of ML source files.  If
115  Here, the disambiguating rule is that the definition from the ML  an ML source file re-defines an imported name, then the disambiguating
116  source takes precedence over the definition imported from the group or  rule is that the definition from the ML source takes precedence over
117  library.  the definition imported from the group or library.
118    
119  Rule~\ref{rule:diamond} may come as a bit of a surprise considering  Rule~\ref{rule:diamond} may come as a bit of a surprise considering
120  that each ML source file can be a member of at most one group or  that each ML source file can be a member of at most one group or
# Line 153  Line 153 
153  \label{sec:groups}  \label{sec:groups}
154    
155  CM's group model eliminates a whole class of potential naming problems  CM's group model eliminates a whole class of potential naming problems
156  by providing control over name spaces for program linkage. As has been  by providing control over name spaces for program linkage.  The group
157  described separately~\cite{blume:appel:cm99}, it sometimes involves  model in full generality sometimes requires bindings to be renamed at
158  the use of ``administrative'' libraries whose sole purpose is to  the time of import. As has been described
159  rename certain definitions.  separately~\cite{blume:appel:cm99}, in the case of ML this can also be
160    achieved using ``administative'' libaries, which is why CM can get
161    away with not providing more direct support for renaming.
162    
163  However, under CM, the term ``library'' does not only mean namespace  However, under CM, the term ``library'' does not only mean namespace
164  management but also refers to actual file system objects.  It would be  management (as it would from the point of view of the pure group
165    model) but also refers to actual file system objects.  It would be
166  inconvenient if name resolution problems would result in a  inconvenient if name resolution problems would result in a
167  proliferation of additional library files.  Therefore, CM also  proliferation of additional library files.  Therefore, CM also
168  provides the notion of groups (or: library components).  Name  provides the notion of groups (or: ``library components'').  Name
169  resolution for groups works like name resolution for entire libraries,  resolution for groups works like name resolution for entire libraries,
170  but grouping is entirely internal to each library.  but grouping is entirely internal to each library.
171    
# Line 241  Line 244 
244    
245  \subsection{Motivation}  \subsection{Motivation}
246    
247  File naming has been an area notorious for its problems and cause of  File naming has been an area notorious for its problems and was the
248  most of the gripes from CM's users.  With this in mind, CM now takes a  cause of most of the gripes from CM's users.  With this in mind, CM
249  different approach to file name resolution.  now takes a different approach to file name resolution.
250    
251  The main difficulty lies in the fact that files or even whole  The main difficulty lies in the fact that files or even whole
252  directories may move after CM has already partially (but not fully)  directories may move after CM has already partially (but not fully)
253  processed them.  For example, this happens when the {\em autoloader}  processed them.  For example, this happens when the {\em autoloader}
254  (see Section~\ref{sec:autoload}) has been invoked and the session  (see Section~\ref{sec:autoload}) has been invoked and the session
255  (including CM's internal state) is then saved via {\tt  (including CM's internal state) is then frozen (i.e., saved to a file)
256  SMLofNJ.exportML}.  CM is now able to resume such a session even when  via {\tt SMLofNJ.exportML}.  The new CM is now able to resume such a
257  operating in a different environment, perhaps on a different machine  session even when operating in a different environment, perhaps on a
258  with different file system mounted, or a different location of the  different machine with different file system mounted, or a different
259  SML/NJ installation.  location of the SML/NJ installation.
260    
261  For this, CM provides a configurable mechanism for locating file  To make this possible, CM provides a configurable mechanism for
262  system objects.  Moreover, it invokes this mechanism as late as  locating file system objects.  Moreover, it invokes this mechanism
263  possible and is prepared to re-invoke it if the configuration changes.  always as late as possible and is prepared to re-invoke it after the
264    configuration changes.
265    
266  \subsection{Basic rules}  \subsection{Basic rules}
267    
# Line 510  Line 514 
514  false} and can be overriden at startup time by the environment  false} and can be overriden at startup time by the environment
515  variable {\tt CM\_DEBUG}.  variable {\tt CM\_DEBUG}.
516    
517  Using {\tt CM.Control.conserve\_memory}, CM can be told to be lightly  Using {\tt CM.Control.conserve\_memory}, CM can be told to be slightly
518  more conservative with its use of main memory at the expense of  more conservative with its use of main memory at the expense of
519  occasionally incurring additional input from stable library files.  occasionally incurring additional input from stable library files.
520  This does not save very much and, therefore, is normally turned off.  This does not save very much and, therefore, is normally turned off.
# Line 570  Line 574 
574  Some care is necessary as {\tt CM.symval} does not check whether the  Some care is necessary as {\tt CM.symval} does not check whether the
575  syntax of the argument string is valid.  (However, the worst thing  syntax of the argument string is valid.  (However, the worst thing
576  that could happen is that a variable defined via {\tt CM.symval} is  that could happen is that a variable defined via {\tt CM.symval} is
577  not accessible from within CM's description files because there is no  not accessible\footnote{from within CM's description files} because
578  legal syntax to name it.)  there is no legal syntax to name it.)
579    
580  \subsubsection*{Library registry}  \subsubsection*{Library registry}
581    
# Line 725  Line 729 
729  and tools very easily without having to reconfigure or recompile CM,  and tools very easily without having to reconfigure or recompile CM,
730  not to mention modify its source code.  not to mention modify its source code.
731    
732    \subsubsection*{Building stand-alone programs}
733    
734    CM can be used to build stand-alone programs. In fact SML/NJ
735    itself---including CM---is an example of this.  (The interactive
736    system cannot rely on an existing compilation manager when starting
737    up.)
738    
739    A stand-alone program is constructed by the runtime system from
740    existing binfiles or members of existing stable libraries.  CM must
741    prepare those binfiles or libraries together with a list that
742    describes them to the runtime system.
743    
744    \begin{verbatim}
745      val mk_standalone : bool option -> string -> string list option
746    \end{verbatim}
747    
748    Depending on the optional boolean argument, function {\tt
749    CM.mk\_standalone} first acts like either {\tt CM.recomp} or {\tt
750    CM.stabilize}.  {\tt NONE} means {\tt CM.recomp}, and {\tt (SOME $r$)}
751    means {\tt CM.stabilize $r$}.  After recompilation (or stabilization)
752    is successful, {\tt CM.mk\_standalone} constructs a topologically
753    sorted list of strings that, when written to a file, can be passed to the
754    runtime system in order to perform stand-alone linkage of the given
755    program. Upon failure, {\tt CM.mk\_standalone} returns {\tt NONE}.
756    
757  \subsection{The autoloader}  \subsection{The autoloader}
758  \label{sec:autoload}  \label{sec:autoload}
759    
# Line 879  Line 908 
908    
909  CM provides a number of ``variables'' (names that stand for certain  CM provides a number of ``variables'' (names that stand for certain
910  integers). These variables may appear in expressions of the  integers). These variables may appear in expressions of the
911  conditional-compilation facility. The exact set of provided variable  conditional-compilation facility. The exact set of variables provided
912  names depends on SML/NJ version number, machine architecture, and  depends on SML/NJ version number, machine architecture, and
913  operating system.  A reference to a CM variable is considered an  operating system.  A reference to a CM variable is considered an
914  arithmetic expression. If the variable is not defined, then it  arithmetic expression. If the variable is not defined, then it
915  evaluates to 0.  The expression {\tt defined}($v$) is a boolean  evaluates to 0.  The expression {\tt defined}($v$) is a boolean
# Line 916  Line 945 
945    
946  \subsection{Querying exported definitions}  \subsection{Querying exported definitions}
947    
948  An expression of the form {\tt defined}($n$ $s$) where $s$ is an ML  An expression of the form {\tt defined}($n$ $s$), where $s$ is an ML
949  symbol and $n$ is an ML namespace specifier is a boolean expression  symbol and $n$ is an ML namespace specifier, is a boolean expression
950  that yields true if and only if any member included before this test  that yields true if and only if any member included before this test
951  exports a definition under this name.  Therefore, order among members  exports a definition under this name.  Therefore, order among members
952  matters after all (but it remains unrelated to the problem of  matters after all (but it remains unrelated to the problem of
# Line 961  Line 990 
990    
991  \subsection{Explicit errors}  \subsection{Explicit errors}
992    
993  A pseudo-member of the form {\tt \#error $\ldots$} which---like other  A pseudo-member of the form {\tt \#error $\ldots$}, which---like other
994  {\tt \#}-items---starts in the first column and extends to the end of  {\tt \#}-items---starts in the first column and extends to the end of
995  the line causes an explicit error message unless it gets excluded by  the line, causes an explicit error message unless it gets excluded by
996  the conditional compilation logic.  The error message is given by the  the conditional compilation logic.  The error message is given by the
997  remainder of the line after the word {\tt error}.  remainder of the line after the word {\tt error}.
998    
# Line 1042  Line 1071 
1071  words, everybody is assumed to have every possible privilege.  CM  words, everybody is assumed to have every possible privilege.  CM
1072  merely reports which privileges "would have been required".  merely reports which privileges "would have been required".
1073    
1074  \section{The pervasive environment and primitive modules}  \section{The pervasive environment}
   
 \subsection{The pervasive environment}  
1075    
1076  The {\em pervasive environment} can be thought of as a library that  The {\em pervasive environment} can be thought of as a compilation
1077  all compilation units implicitly depend upon.  The pervasive  unit that all compilation units implicitly depend upon.  The pervasive
1078  enviroment exports all non-modular bindings (types, values, infix  enviroment exports all non-modular bindings (types, values, infix
1079  operators, overloaded symbols) that are mandated by the specification  operators, overloaded symbols) that are mandated by the specification
1080  for the Standard ML Basis Library~\cite{reppy99:basis}.  (All other  for the Standard ML Basis Library~\cite{reppy99:basis}.  (All other
# Line 1057  Line 1084 
1084  The pervasive environment is the only place where CM conveys  The pervasive environment is the only place where CM conveys
1085  non-modular bindings from one compilation unit to another.  non-modular bindings from one compilation unit to another.
1086    
 \subsection{Primitive modules}  
   
 CM also knows about some ``primitive'' modules.  These modules give  
 access to certain compiler internals which are implemented in a way  
 that is outside the usual CM compilation model.  A user program can  
 access a primitive module by listing its name as one of the members in  
 its CM description files.  However, usage of any primitive module $M$  
 is protected by requiring the client to possess  privilege $M$  
 (see Section~\ref{sec:access}), i.e., a privilege that goes by the  
 same name as the module itself.  
   
 User programs are strongly discouraged to access primitive modules  
 directly. The exact set of primitive modules known to CM is subject to  
 change without notice.  
   
1087  \section{Files}  \section{Files}
1088    
1089  CM uses three kinds of files to store derived information during and  CM uses three kinds of files to store derived information during and
# Line 1093  Line 1105 
1105  \end{enumerate}  \end{enumerate}
1106    
1107  Normally, all these files are stored in a subdirectory of directory  Normally, all these files are stored in a subdirectory of directory
1108  {\tt CM} which itself is a subdirectory of the directory where the  {\tt CM}. {\tt CM} itself is a subdirectory of the directory where the
1109  original ML source file or---in the case of library files---the  original ML source file or---in the case of library files---the
1110  original CM description file is located.  original CM description file is located.
1111    
# Line 1220  Line 1232 
1232    
1233  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
1234  about, then it tries to load a plugin module named $c${\tt -tool.cm}.  about, then it tries to load a plugin module named $c${\tt -tool.cm}.
1235  If it sees a file whose name ends in suffix $s$, for which no member  If it sees a file whose name ends in suffix $s$ for which no member
1236  class has been specified, and for which member classification fails,  class has been specified and for which member classification fails,
1237  then it tries to load a plugin module named $s${\tt -ext.cm}.  The  then it tries to load a plugin module named $s${\tt -ext.cm}.  The
1238  so-loaded module can then register the required tool which enables CM  so-loaded module can then register the required tool which enables CM
1239  to successfully deal with the previously unknown member.  to successfully deal with the previously unknown member.
# Line 1531  Line 1543 
1543  \bibliography{blume,appel,ml}  \bibliography{blume,appel,ml}
1544    
1545  \end{document}  \end{document}
   

Legend:
Removed from v.536  
changed lines
  Added in v.537

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