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 679, Thu Jun 29 07:03:20 2000 UTC revision 680, Mon Jul 3 06:35:55 2000 UTC
# Line 50  Line 50 
50  Programming projects that use CM are typically composed of separate  Programming projects that use CM are typically composed of separate
51  {\em libraries}.  Libraries are collections of ML compilation units  {\em libraries}.  Libraries are collections of ML compilation units
52  and themselves can be internally sub-structured using CM's notion of  and themselves can be internally sub-structured using CM's notion of
53  {\em groups}.  Using libraries and groups, programs can be viewed as a  {\em library components}.
 {\em hierarchy of modules}.  The organization of large projects tends  
 to benefit from this approach~\cite{blume:appel:cm99}.  
   
 CM uses {\em cutoff} techniques~\cite{tichy94} to minimize  
 recompilation work and provides automatic dependency analysis to free  
 the programmer from having to specify a detailed module dependency  
 graph by hand~\cite{blume:depend99}.  
54    
55  This new version of CM emphasizes {\em working with libraries}.  This  CM offers the following features to the programmer:
56  contrasts with the previous implementation where the focus was on  
57    \begin{itemize}
58    \item separate compilation and type-safe linking~\cite{appel94:sepcomp}
59    \item hierarchical modularity~\cite{blume:appel:cm99}
60    \item automatic dependency analysis~\cite{blume:depend99}
61    \item optimization of the compilation process via {\em
62    cutoff}-recompilation techniques~\cite{tichy94}
63    \item management of program libraries, distinguishing between libraries
64    that are {\em under development} and libraries that are {\em stable}
65    \item operating-system independent file naming (with optional escape
66    to native file names)
67    \item adaptability to changing environments using the {\em path anchor}
68    facility
69    \item an extensible set of auxiliary {\em tools} that lets CM
70    seemlessly interoperate with other program generators, source-control
71    systems, literate-programming facilities, or shell-scripts
72    \item checked version numbers on libraries
73    \item (still rudimentary) support for access control
74    \item access to libraries from the interactive toplevel loop
75    \item sharing of code that is common to several programs or code that
76    is common to both user programs and SML/NJ itself
77    \item management of (the sharing of) link-time state
78    \item support for parallel and distributed compilation
79    \item an API to access all these facilities at SML/NJ's interactive
80    prompt
81    \end{itemize}
82    
83    CM puts emphasis on {\em working with libraries}.  This contrasts with
84    previous compilation managers for SML/NJ where the focus was on
85  compilation management while libraries were added as an afterthought.  compilation management while libraries were added as an afterthought.
 Beginning now, CM takes a very library-centric view of the world.  In  
 fact, the implementation of SML/NJ itself has been restructured to  
 conform to this approach.  
86    
87  \section{The CM model}  \section{The CM model}
88    
89  A CM library is a (possibly empty) collection of ML source files and  \subsection{Basic philosophy}
90  may also contain references to other libraries.  Each library comes  
91  with an explicit export interface which lists all toplevel-defined  The venerable {\bf make} of Unix~\cite{feldman79} is {\em
92  symbols of the library that shall be exported to its clients.  A  target-oriented}: one starts with a main goal (target) and applies
93  library is described by the contents of its {\em description  production rules (with associated actions such as invoking a compiler)
94  file}.\footnote{The description file may also contain references to  until no more rules are applicable. The leaves of the resulting
95  input files for {\em tools} like {\tt ml-lex} or {\tt ml-yacc} that  derivation tree can be seen as defining the set of source files that
96  produce ML source files.  See section~\ref{sec:tools}.}  are used to make the main target.
97    
98    CM, on the other hand, is largely {\em source-oriented}: Whereas with
99    {\bf make} one specifies the tree and let the program derive the
100    leaves, with CM one specifies the leaves and let the program derive
101    the tree.  Thus, the programmer writes down a list of sources, and CM
102    will calculate and then execute a series of steps to make the
103    corresponding program.  In {\bf make} terminology, this resulting
104    program acts as the ``main goal'', but it does not need to be
105    explicitly named.  In fact, since there typically is no corresponding
106    single file system object, a ``natural'' name for it does not even
107    exist.
108    
109    For simple projects it is literally true that all the programmer has
110    to do is to tell CM about the set of sources: a description file lists
111    little more than the names of participating ML source files. Larger
112    projects typically benefit from a hierarchical structuring.  This can
113    be achieved by grouping ML source files into separate libraries and
114    library components.  Dependencies between such libraries have to be
115    specified explicitly and must form an acyclic directed graph (DAG).
116    
117    CM's own semantics, particularly its dependency analysis, interact
118    with the ML language in such a way that for any well-formed project
119    there will be exactly one possible interpretation as far as static
120    semantics are concerned.  Only well-formed projects are accepted by
121    CM; projects that are not well-formed will cause error messages.
122    
123    \subsection{Description files}
124    
125    Technically, a CM library is a (possibly empty) collection of ML
126    source files and may also contain references to other libraries.  Each
127    library comes with an explicit export interface which lists all
128    toplevel-defined symbols of the library that shall be exported to its
129    clients.  A library is described by the contents of its {\em
130    description file}.\footnote{The description file may also contain
131    references to input files for {\em tools} like {\tt ml-lex} or {\tt
132    ml-yacc} that produce ML source files.  See section~\ref{sec:tools}.}
133    
134  \noindent Example:  \noindent Example:
135    
# Line 87  Line 141 
141      bar.sig      bar.sig
142      foo.sml      foo.sml
143      helper.sml      helper.sml
144      $/basis.cm (* or just $basis.cm *)  
145        $/basis.cm
146        $/smlnj-lib.cm
147  \end{verbatim}  \end{verbatim}
148    
149  This library exports two definitions, one for a structure named {\tt  This library exports two definitions, one for a structure named {\tt
# Line 95  Line 151 
151  such exports appear between the keywords {\tt Library} and {\tt is}.  such exports appear between the keywords {\tt Library} and {\tt is}.
152  The {\em members} of the library are specified after the keyword {\tt  The {\em members} of the library are specified after the keyword {\tt
153  is}.  Here we have three ML source files ({\tt bar.sig}, {\tt  is}.  Here we have three ML source files ({\tt bar.sig}, {\tt
154  foo.sml}, and {\tt helper.sml}) as well as a reference to one external  foo.sml}, and {\tt helper.sml}) as well as references to two external
155  library ({\tt \$/basis.cm}).  The entry {\tt \$/basis.cm} typically denotes  libraries ({\tt \$/basis.cm} and {\tt \$/smlnj-lib.cm}).  The entry
156  the description file for the {\it Standard ML Basis  {\tt \$/basis.cm} typically denotes the description file for the {\it
157  Library}~\cite{reppy99:basis}; most programs will want to list it in  Standard ML Basis Library}~\cite{reppy99:basis}; most programs will
158  their own description file(s).  want to list it in their own description file(s).  The other library
159    in this example ({\tt \$/smlnj-lib.cm}) is a library of data
160    structures and algorithms that comes bundled with SML/NJ.
161    
162  \subsection{Library descriptions}  \subsection{Members of a library}
163    
164  Members of a library do not have to be listed in any particular order  Members of a library do not have to be listed in any particular order
165  since CM will automatically calculate the dependency graph.  Some  since CM will automatically calculate the dependency graph.  Some
# Line 133  Line 191 
191  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
192  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
193  library (see section~\ref{sec:multioccur}).  However, it is indeed  library (see section~\ref{sec:multioccur}).  However, it is indeed
194  possible for two libraries to export the ``same'' definition provided  possible for two libraries to (re-)export the ``same'' definition
195  they both import that definition from a third library.  For example,  provided they both import that definition from a third library.  For
196  let us assume that {\tt a.cm} exports a structure {\tt X} which was  example, let us assume that {\tt a.cm} exports a structure {\tt X}
197  defined in {\tt x.sml}---one of {\tt a.cm}'s members.  Now, if both  which was defined in {\tt x.sml}---one of {\tt a.cm}'s members.  Now,
198  {\tt b.cm} and {\tt c.cm} re-export that same structure {\tt X} after  if both {\tt b.cm} and {\tt c.cm} re-export that same structure {\tt
199  importing it from {\tt a.cm}, it is legal for a fourth library {\tt  X} after importing it from {\tt a.cm}, it is legal for a fourth
200  d.cm} to import from both {\tt b.cm} and {\tt c.cm}.  library {\tt d.cm} to import from both {\tt b.cm} and {\tt c.cm}.
201    
202  The full syntax for library description files also includes provisions  The full syntax for library description files also includes provisions
203  for a simple ``conditional compilation'' facility (see  for a simple ``conditional compilation'' facility (see
# Line 313  Line 371 
371    
372  CM uses its own ``standard'' syntax for pathnames which for the most  CM uses its own ``standard'' syntax for pathnames which for the most
373  part happens to be the same as the one used by most Unix-like systems:  part happens to be the same as the one used by most Unix-like systems:
374  path name components are separated by ``{\bf /}'', paths beginning  \begin{itemize}
375  with ``{\bf /}'' are considered {\em absolute} while other paths are  \item Path name components are separated by ``{\bf /}''.
376  {\em relative}.  There is an important third form of standard paths:  \item Special components ``{\bf .}'' and ``{\bf ..}'' denote {\em
377  {\em anchored} paths.  Anchored paths always start with ``{\bf \$}''.  current} and {\em previous} directory, respectively.
378    \item Paths beginning
379    with ``{\bf /}'' are considered {\em absolute}.
380    \item Other paths are {\em relative} unless they start with ``{\bf \$}''.
381    \end{itemize}
382    \noindent There is an important third form of standard paths: {\em
383    anchored} paths.  Anchored paths always start with ``{\bf \$}''.
384    
385  Since this standard syntax does not cover system-specific aspects such  Since this standard syntax does not cover system-specific aspects such
386  as volume names, it is also possible to revert to ``native'' syntax by  as volume names, it is also possible to revert to ``native'' syntax by
387  enclosing the name in double-quotes.  Of course, description files  enclosing a path name in double-quotes.  Of course, description files
388  that use path names in native syntax are not portable across operating  that use path names in native syntax are not portable across operating
389  systems.  systems.
390    
# Line 408  Line 472 
472    
473  The example also demonstrates that {\tt value}-paths can be single  The example also demonstrates that {\tt value}-paths can be single
474  anchors. In other words, the restriction that there has to be at least  anchors. In other words, the restriction that there has to be at least
475  one arc after the anchor does not apply here.  one arc after the anchor does not apply here. This makes it possible
476    to ``rename'' anchors, or, to put it more precisely, for one anchor
477    name to be established as an ``alias'' for another anchor name.
478    
479  \subsection{Anchor configuration}  \subsection{Anchor configuration}
480  \label{sec:anchor:config}  \label{sec:anchor:config}
# Line 421  Line 487 
487  functions {\tt CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see  functions {\tt CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see
488  Section~\ref{sec:api}).  Section~\ref{sec:api}).
489    
490  The default location of the installation-specific configuration file  Although there is a hard-wired default for the installation-specific
491  is {\tt /usr/lib/smlnj-pathconfig}.  However, normally this default  configuration file\footnote{which happens to be {\tt
492  gets replaced (via an environment variable named {\tt  /usr/lib/smlnj-pathconfig}}, this default in rarely being used.
493  CM\_PATHCONFIG\_DEFAULT}) at installation time by a path pointing to  Instead, in a typical installation of SML/NJ the default will be a
494  wherever the installation actually puts the configuration file.  file $r${\tt /lib/pathconfig} where $r$ is the {\it root} directory
495  The user can specify a new location at startup time using the  into which SML/NJ had been installed.  (The installation procedure
496  environment variable {\tt CM\_PATHCONFIG}.  establishes this new default by setting the environment variable {\tt
497    CM\_PATHCONFIG\_DEFAULT} at the time it produces the heap image for
498    the interactive system.)  The user can specify a new location at
499    startup time using the environment variable {\tt CM\_PATHCONFIG}.
500    
501  The default location of the user-specific configuration file is {\tt  The default location of the user-specific configuration file is {\tt
502  .smlnj-pathconfig} in the user's home directory (which must be given  .smlnj-pathconfig} in the user's home directory (which must be given

Legend:
Removed from v.679  
changed lines
  Added in v.680

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