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 735, Tue Nov 21 12:15:55 2000 UTC revision 736, Thu Nov 23 01:39:05 2000 UTC
# Line 43  Line 43 
43  \section{Introduction}  \section{Introduction}
44    
45  This manual describes a new implementation of CM, the ``Compilation  This manual describes a new implementation of CM, the ``Compilation
46  and Library Manager'' for Standard ML of New Jersey (SML/NJ).  Like its  and Library Manager'' for Standard ML of New Jersey (SML/NJ).  Like
47  previous version, CM is in charge of managing separate compilation and  its previous incarnation, CM is in charge of managing separate
48  facilitates access to stable libraries.  compilation and facilitates access to stable libraries.
49    
50  Programming projects that use CM are typically composed of separate  Most programming projects that use CM are composed of separate {\em
51  {\em libraries}.  Libraries are collections of ML compilation units  libraries}.  Libraries are collections of ML compilation units.  These
52  and themselves can be internally sub-structured using CM's notion of  collections themselves can be internally sub-structured using CM's
53  {\em library components}.  notion of {\em library components}.
54    
55  CM offers the following features to the programmer:  CM offers the following features to the programmer:
56    
# Line 78  Line 78 
78  \item conditional compilation (at compilation unit granularity)  \item conditional compilation (at compilation unit granularity)
79  \item support for parallel and distributed compilation  \item support for parallel and distributed compilation
80  \item facilities for generating stand-alone ML programs  \item facilities for generating stand-alone ML programs
81  \item a mechanism for deriving dependency information that can be used  \item a mechanism for deriving dependency information for use
82  by other compilation managers such as Unix' {\bf make}  by other compilation managers (e.g., Unix' {\bf make})
83  \item an API to access all these facilities at SML/NJ's interactive  \item an API to access all these facilities at SML/NJ's interactive
84  prompt  prompt or from user programs
85  \end{itemize}  \end{itemize}
86    
87  CM puts emphasis on {\em working with libraries}.  This contrasts with  CM puts emphasis on {\em working with libraries}.  This contrasts with
# Line 137  Line 137 
137  clients.  A library is described by the contents of its {\em  clients.  A library is described by the contents of its {\em
138  description file}.\footnote{The description file may also contain  description file}.\footnote{The description file may also contain
139  references to input files for {\em tools} like {\tt ml-lex} or {\tt  references to input files for {\em tools} like {\tt ml-lex} or {\tt
140  ml-yacc} that produce ML source files.  See section~\ref{sec:tools}.}  ml-yacc} that produce ML source files.  See section~\ref{sec:classes}.}
141    
142  \noindent Example:  \noindent Example:
143    
# Line 218  Line 218 
218  \item For a given symbol, there can be at most one ML source file per  \item For a given symbol, there can be at most one ML source file per
219  library (or---more correctly---one file per library component; see  library (or---more correctly---one file per library component; see
220  Section~\ref{sec:groups}) that defines the symbol at top level.  Section~\ref{sec:groups}) that defines the symbol at top level.
221  \item If more than one sub-library or sub-group is exporting the same  \item If more than one of the listed libraries or components is
222  symbol, then the definition (i.e., the ML source file that actually  exporting the same symbol, then the definition (i.e., the ML source
223  defines the symbol) must be identical in all cases.  file that actually defines the symbol) must be identical in all cases.
224  \label{rule:diamond}  \label{rule:diamond}
225  \item The use of ML's {\bf open} construct is not permitted at the top  \item The use of ML's {\bf open} construct is not permitted at the top
226  level of ML files compiled by CM.  (The use is still ok at the  level of ML files compiled by CM.  (The use is still ok at the
227  interactive top level.)  interactive top level.)
228  \end{enumerate}  \end{enumerate}
229    
230  Note that these rules do not require the exports of sub-groups or  Note that these rules do not require the exports of imported libraries
231  sub-libraries to be distinct from the exports of ML source files in  to be distinct from the exports of ML source files in the current
232  the current library or group.  If an ML source file $f$ re-defines a  library.  If an ML source file $f$ re-defines a name $n$ that is also
233  name $n$ that is also imported from library or library component $l$,  imported from library $l$, then the disambiguating rule is that the
234  then the disambiguating rule is that the definition from $f$ takes  definition from $f$ takes precedence over that from $l$ in all sources
235  precedence over that from $l$ in all sources except $f$ itself.  Free  except $f$ itself.  Free occurences of $n$ in $f$ refer to $l$'s
236  occurences of $n$ in $f$ refer to $l$'s definition.  This rule makes  definition.  This rule makes it possible to easily write code for
237  it possible to easily write code for exporting an ``augmented''  exporting an ``augmented'' version of some module.  Example:
 version of some module.  Example:  
238    
239  \begin{verbatim}  \begin{verbatim}
240    structure A = struct (* defines augmented A *)    structure A = struct (* defines augmented A *)
# Line 245  Line 244 
244  \end{verbatim}  \end{verbatim}
245    
246  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
247  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 library (see
248  library (see section~\ref{sec:multioccur}).  However, it is indeed  section~\ref{sec:multioccur}).  However, it is indeed possible for two
249  possible for two libraries to (re-)export the ``same'' definition  libraries to (re-)export the ``same'' definition provided they both
250  provided they both import that definition from a third library.  For  import that definition from a third library.  For example, let us
251  example, let us assume that {\tt a.cm} exports a structure {\tt X}  assume that {\tt a.cm} exports a structure {\tt X} which was defined
252  which was defined in {\tt x.sml}---one of {\tt a.cm}'s members.  Now,  in {\tt x.sml}---one of {\tt a.cm}'s members.  Now, if both {\tt b.cm}
253  if both {\tt b.cm} and {\tt c.cm} re-export that same structure {\tt  and {\tt c.cm} re-export that same structure {\tt X} after importing
254  X} after importing it from {\tt a.cm}, it is legal for a fourth  it from {\tt a.cm}, it is legal for a fourth library {\tt d.cm} to
255  library {\tt d.cm} to import from both {\tt b.cm} and {\tt c.cm}.  import from both {\tt b.cm} and {\tt c.cm}.
256    
257  The full syntax for library description files also includes provisions  The full syntax for library description files also includes provisions
258  for a simple ``conditional compilation'' facility (see  for a simple ``conditional compilation'' facility (see
# Line 264  Line 263 
263  \subsection{Name visibility}  \subsection{Name visibility}
264    
265  In general, all definitions exported from members (i.e., ML source  In general, all definitions exported from members (i.e., ML source
266  files, subgroups and sublibraries) of a library are visible in all  files, sublibraries, and components) of a library are visible in all
267  other ML source files of that library.  The source code in those  other ML source files of that library.  The source code in those
268  source files can refer to them directly without further qualification.  source files can refer to them directly without further qualification.
269  Here, ``exported'' means either a top-level definition within an ML  Here, ``exported'' means either a top-level definition within an ML
# Line 277  Line 276 
276  Cyclic dependencies among libraries, library components, or ML source  Cyclic dependencies among libraries, library components, or ML source
277  files within a library are detected and flagged as errors.  files within a library are detected and flagged as errors.
278    
279  \subsection{Groups}  \subsection{Library components (groups)}
280  \label{sec:groups}  \label{sec:groups}
281    
282  CM's group model eliminates a whole class of potential naming problems  CM's group model eliminates a whole class of potential naming problems
# Line 294  Line 293 
293  description files and stable library files).  It would be inconvenient  description files and stable library files).  It would be inconvenient
294  if name resolution problems would result in a proliferation of  if name resolution problems would result in a proliferation of
295  additional library files.  Therefore, CM also provides the notion of  additional library files.  Therefore, CM also provides the notion of
296  groups (or: ``library components'').  Name resolution for groups works  library components (``groups'').  Name resolution for groups works
297  like name resolution for entire libraries, but grouping is entirely  like name resolution for entire libraries, but grouping is entirely
298  internal to each library.  internal to each library.
299    
# Line 395  Line 394 
394    
395  CM distinguishes between libraries that are {\em under development}  CM distinguishes between libraries that are {\em under development}
396  and libraries that are {\em stable}.  A stable library is created by a  and libraries that are {\em stable}.  A stable library is created by a
397  call to {\tt CM.stabilize} (see Section~\ref{sec:api:compiling}).  call of {\tt CM.stabilize} (see Section~\ref{sec:api:compiling}).
398    
399  Access to stable libraries is subject to less internal  Access to stable libraries is subject to less internal
400  consistency-checking and touches far fewer file-system  consistency-checking and touches far fewer file-system
# Line 854  Line 853 
853    
854  {\tt CM.Library.osstring} produces a string denoting the given  {\tt CM.Library.osstring} produces a string denoting the given
855  library's description file using the underlying operating system's  library's description file using the underlying operating system's
856  native pathname syntax.  In other words, the result of a call to {\tt  native pathname syntax.  In other words, the result of a call of {\tt
857  CM.Library.osstring} is suitable as an argument to {\tt  CM.Library.osstring} is suitable as an argument to {\tt
858  TextIO.openIn}.  TextIO.openIn}.
859    
# Line 955  Line 954 
954    
955  An existing server can be shut down and detached using {\tt  An existing server can be shut down and detached using {\tt
956  CM.Server.stop} or {\tt CM.Server.kill}.  The argument in either case  CM.Server.stop} or {\tt CM.Server.kill}.  The argument in either case
957  must be the result of an earlier call to {\tt CM.Server.start}.  must be the result of an earlier call of {\tt CM.Server.start}.
958  Function {\tt CM.Server.stop} uses CM's master-slave protocol to  Function {\tt CM.Server.stop} uses CM's master-slave protocol to
959  instruct the server to shut down gracefully.  Only if this fails it  instruct the server to shut down gracefully.  Only if this fails it
960  may become necessary to use {\tt CM.Server.kill}, which will send a  may become necessary to use {\tt CM.Server.kill}, which will send a
# Line 989  Line 988 
988  environment with spurious exports of the extension module.  environment with spurious exports of the extension module.
989    
990  CM itself uses plug-in modules in its member-class subsystem (see  CM itself uses plug-in modules in its member-class subsystem (see
991  section~\ref{sec:classes}).  This makes it possible to add new classes  section~\ref{sec:moretools}).  This makes it possible to add new classes
992  and tools very easily without having to reconfigure or recompile CM,  and tools very easily without having to reconfigure or recompile CM,
993  not to mention modify its source code.  not to mention modify its source code.
994    
# Line 1114  Line 1113 
1113  \subsection{The autoloader}  \subsection{The autoloader}
1114  \label{sec:autoload}  \label{sec:autoload}
1115    
1116  From the user's point of view, a call to {\tt CM.autoload} acts very  From the user's point of view, a call of {\tt CM.autoload} acts very
1117  much like the corresponding call to {\tt CM.make} because the same  much like the corresponding call of {\tt CM.make} because the same
1118  bindings that {\tt CM.make} would introduce into the top-level  bindings that {\tt CM.make} would introduce into the top-level
1119  enviroment are also introduced by {\tt CM.autoload}.  However, most  enviroment are also introduced by {\tt CM.autoload}.  However, most
1120  work will be deferred until some code that is entered later refers to  work will be deferred until some code that is entered later refers to
# Line 1156  Line 1155 
1155  each compilation unit will be executed at most once.  This means that  each compilation unit will be executed at most once.  This means that
1156  the same ``program'' will not see multiple instantiations of the same  the same ``program'' will not see multiple instantiations of the same
1157  compilation unit (where ``program'' refers to the code managed by one  compilation unit (where ``program'' refers to the code managed by one
1158  call to {\tt CM.make} or {\tt CM.autoload}).  Each compilation unit  call of {\tt CM.make} or {\tt CM.autoload}).  Each compilation unit
1159  will be linked at most once during a traversal and private state  will be linked at most once during a traversal and private state
1160  will not be confused with private state of other traversals that might  will not be confused with private state of other traversals that might
1161  be active at the same time.  be active at the same time.
# Line 1950  Line 1949 
1949  stamp}  stamp}
1950    
1951  CM also uses time stamps to decide whether tools such as ML-Yacc or  CM also uses time stamps to decide whether tools such as ML-Yacc or
1952  ML-Lex need to be run (see Section~\ref{sec:tools}).  However, the  ML-Lex need to be run (see Section~\ref{sec:classes}).  However, the
1953  difference is that a file is considered outdated if it is older than  difference is that a file is considered outdated if it is older than
1954  its source.  Some care on the programmers side is necessary since this  its source.  Some care on the programmers side is necessary since this
1955  scheme does not allow CM to detect the situation where a source file  scheme does not allow CM to detect the situation where a source file
1956  gets replaced by an older version of itself.  gets replaced by an older version of itself.
1957    
1958  \section{Tools}  \section{Extending the tool set}
1959  \label{sec:tools}  \label{sec:moretools}
1960    
1961  CM's tool set is extensible: new tools can be added by writing a few  CM's tool set is extensible: new tools can be added by writing a few
1962  lines of ML code.  The necessary hooks for this are provided by a  lines of ML code.  The necessary hooks for this are provided by a
# Line 1967  Line 1966 
1966  \subsection{Adding simple shell-command tools}  \subsection{Adding simple shell-command tools}
1967    
1968  If the tool is implemented as a ``typical'' shell command, then all  If the tool is implemented as a ``typical'' shell command, then all
1969  that needs to be done is a single call to:  that needs to be done is a single call of:
1970    
1971  \begin{verbatim}  \begin{verbatim}
1972    Tools.registerStdShellCmdTool    Tools.registerStdShellCmdTool
# Line 2093  Line 2092 
2092  successfully deal with the previously unknown member.  successfully deal with the previously unknown member.
2093    
2094  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
2095  placing appropriately-named plug-in libraries into a global tool  placing appropriately-named plug-in libraries in some convenient place
2096  repository.  Of course, it will also require a corresponding  and making the corresponding adjustments to the anchor environment.
2097  re-configuration of the anchor environment.  In other words, for  In other words, description files {\tt \$/}$c${\tt -tool.cm} and {\tt
2098  general-purpose tools that are installed in some central place,  \$/}$s${\tt -ext.cm} that correspond to general-purpose tools should
2099  corresponding tool description files {\tt \$/}$c${\tt -tool.cm} and  be registered using the path anchor mechanism.  If this is done,
2100  {\tt \$/}$s${\tt -ext.cm} should be registered using the path anchor  actual description files for the tools' implementations can be placed
2101  mechanism.  If this is done, actual description files can be placed in  in arbitrary locations.
 arbitrary locations.  
2102    
2103  \subsubsection{Explicitly-loaded, local plug-in tools}  \subsubsection{Explicitly-loaded, local plug-in tools}
2104  \label{sec:localtools}  \label{sec:localtools}
# Line 2134  Line 2132 
2132  bar-tool.cm} will also be available.  bar-tool.cm} will also be available.
2133    
2134  The effect of registering classes and classifiers using class {\tt  The effect of registering classes and classifiers using class {\tt
2135  tool} lasts until the end of the current description file.  Moreover,  tool} lasts until the end of the current description file and is
2136  the effect is {\em restricted} to the current description file.  This  restricted to that file.  This means that other description files that
2137  means that other description files that also want to use class {\tt  also want to use class {\tt bar} will have to have their own {\tt
2138  bar} will have to have their own {\tt tool} entry.  tool} entry.
2139    
2140  \noindent{\bf Important:} Registration of classes and classifiers  Local tool classes and suffixes temporarily override any equally-named
2141  happens by link-time side-effect.  If a class or a classifier has been  global classes or suffixes, respectively.
 registered locally via class {\tt tool}, then CM will {\em undo} this  
 registration when finished with the corresponding description file.  
 Therefore, it is important that the required side-effect happens {\em  
 every time} the tool implementation is loaded!  Unfortunately, CM's  
 default treatment of link-time state (see section~\ref{sec:sharing})  
 would defeats this.  Therefore, it is necessary to mark the side-effecting  
 ML code in the tool's implementation as {\em private}.  
2142    
2143  \subsubsection{Locally declared suffixes}  \subsubsection{Locally declared suffixes}
2144  \label{sec:localsuffixes}  \label{sec:localsuffixes}
# Line 2296  Line 2287 
2287  \item[Absolute paths] start either with a percent-sign {\bf \%} or a  \item[Absolute paths] start either with a percent-sign {\bf \%} or a
2288  slash {\bf /}.  The canonical form is the one with the percent-sign:  slash {\bf /}.  The canonical form is the one with the percent-sign:
2289  it specifies the volume name between the {\bf \%} and the first slash.  it specifies the volume name between the {\bf \%} and the first slash.
2290  The common case where the volume name is empty (i.e, {\em always} on  In the common case where the volume name is empty (i.e, {\em always} on
2291  Unix systems), the path starts with {\bf /}.  Unix systems), the path starts with {\bf /}.
2292  \item[Relative paths] are all other paths.  \item[Relative paths] are all other paths.
2293  \end{description}  \end{description}
# Line 2311  Line 2302 
2302  result of applying {\tt Char.ord}).  result of applying {\tt Char.ord}).
2303    
2304  The so-called {\em current} arc is encoded as {\bf .}, the {\em  The so-called {\em current} arc is encoded as {\bf .}, the {\em
2305  parent} arc uses {\bf ..} as its representation.  On some operating  parent} arc uses {\bf ..} as its representation.  It might be that
2306  systems it can happen that although an arc is either {\tt .} or {\tt  under some operating systems the names {\tt .} or {\tt ..} do not
2307  ..}, it still does not actually refer to the current or the parent  actually refer to the current or the parent arc.  In such a case, CM
2308  arc.  In such a case, CM will encode the dots in these names using the  will encode the dots in these names using the \verb|\ddd| method, too.
 \verb|\ddd| method, too.  
2309    
2310  When issuing progress messages, CM shows path names in a form that is  When issuing progress messages, CM shows path names in a form that is
2311  almost the same as the protocol encoding.  The only difference is that  almost the same as the protocol encoding.  The only difference is that

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

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