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 681, Mon Jul 3 07:13:03 2000 UTC revision 682, Tue Jul 4 06:25:51 2000 UTC
# Line 75  Line 75 
75  \item sharing of code that is common to several programs or code that  \item sharing of code that is common to several programs or code that
76  is common to both user programs and SML/NJ itself  is common to both user programs and SML/NJ itself
77  \item management of (the sharing of) link-time state  \item management of (the sharing of) link-time state
78    \item conditional compilation (at compilation unit granularity)
79  \item support for parallel and distributed compilation  \item support for parallel and distributed compilation
80  \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
81  prompt  prompt
# Line 89  Line 90 
90  \subsection{Basic philosophy}  \subsection{Basic philosophy}
91    
92  The venerable {\bf make} of Unix~\cite{feldman79} is {\em  The venerable {\bf make} of Unix~\cite{feldman79} is {\em
93  target-oriented}: one starts with a main goal (target) and applies  target-oriented}\/: one starts with a main goal (target) and applies
94  production rules (with associated actions such as invoking a compiler)  production rules (with associated actions such as invoking a compiler)
95  until no more rules are applicable. The leaves of the resulting  until no more rules are applicable. The leaves of the resulting
96  derivation tree can be seen as defining the set of source files that  derivation tree\footnote{``Tree'' is figurative speech here since the
97  are used to make the main target.  derivation really yields a DAG.} can be seen as defining the set of
98    source files that are used to make the main target.
99  CM, on the other hand, is largely {\em source-oriented}: Whereas with  
100  {\bf make} one specifies the tree and let the program derive the  CM, on the other hand, is largely {\em source-oriented}\/: Whereas
101  leaves, with CM one specifies the leaves and let the program derive  with {\bf make} one specifies the tree and lets the program derive the
102    leaves, with CM one specifies the leaves and lets the program derive
103  the tree.  Thus, the programmer writes down a list of sources, and CM  the tree.  Thus, the programmer writes down a list of sources, and CM
104  will calculate and then execute a series of steps to make the  will calculate and then execute a series of steps to make the
105  corresponding program.  In {\bf make} terminology, this resulting  corresponding program.  In {\bf make} terminology, this resulting
106  program acts as the ``main goal'', but it does not need to be  program acts as the ``main goal'', but under CM it does not need to be
107  explicitly named.  In fact, since there typically is no corresponding  explicitly named.  In fact, since there typically is no corresponding
108  single file system object, a ``natural'' name for it does not even  single file system object for it, a ``natural'' name does not even
109  exist.  exist.
110    
111  For simple projects it is literally true that all the programmer has  For simple projects it is literally true that all the programmer has
112  to do is to tell CM about the set of sources: a description file lists  to do is tell CM about the set of sources: a description file lists
113  little more than the names of participating ML source files. Larger  little more than the names of participating ML source files. However,
114  projects typically benefit from a hierarchical structuring.  This can  larger projects typically benefit from a hierarchical structuring.
115  be achieved by grouping ML source files into separate libraries and  This can be achieved by grouping ML source files into separate
116  library components.  Dependencies between such libraries have to be  libraries and library components.  Dependencies between such libraries
117  specified explicitly and must form an acyclic directed graph (DAG).  have to be specified explicitly and must form an acyclic directed
118    graph (DAG).
119    
120  CM's own semantics, particularly its dependency analysis, interact  CM's own semantics, particularly its dependency analysis, interact
121  with the ML language in such a way that for any well-formed project  with the ML language in such a way that for any well-formed project
122  there will be exactly one possible interpretation as far as static  there will be exactly one possible interpretation as far as static
123  semantics are concerned.  Only well-formed projects are accepted by  semantics are concerned.  Only well-formed projects are accepted by
124  CM; projects that are not well-formed will cause error messages.  CM; projects that are not well-formed will cause error messages.
125    (Well-formedness is {\em defined} to enforce a unique definition-use
126    relation for ML definitions~\cite{blume:depend99}.)
127    
128  \subsection{Description files}  \subsection{Description files}
129    
# Line 159  Line 164 
164  in this example ({\tt \$/smlnj-lib.cm}) is a library of data  in this example ({\tt \$/smlnj-lib.cm}) is a library of data
165  structures and algorithms that comes bundled with SML/NJ.  structures and algorithms that comes bundled with SML/NJ.
166    
167    \subsection{Invoking CM}
168    
169    Once a library has been set up as shown in the example above, one can
170    load it into a running interactive session by invoking function {\tt
171    CM.make}.  If the name of the library's description file is, say, {\tt
172    fb.cm}, then one would type
173    
174    \begin{verbatim}
175      CM.make "fb.cm";
176    \end{verbatim}
177    
178    at SML/NJ's interactive prompt.  This will cause CM to
179    
180    \begin{enumerate}
181    \item parse the description file {\tt fb.cm},
182    \item locate all its sources and all its sub-libraries,
183    \item calculate the dependency graph,
184    \item issue warnings and errors (and skip the remaining steps) if
185    necessary,
186    \item compile those sources for which that is required,
187    \item execute module initialization code,
188    \item and augment the toplevel environment with bindings for exported
189    symbols, i.e., in our example for {\tt signature BAR} and {\tt
190    structure Foo}.
191    \end{enumerate}
192    
193    CM does not compile sources that are not ``reachable'' from the
194    library's exports.  For every other source, it will avoid
195    recompilation if all of the following is true:
196    
197    \begin{itemize}
198    \item The {\em binfile} for the source exists.
199    \item The binfile has the same time stamp as the source.
200    \item The current compilation environment for the source is precisely
201    the same as the compilation environment that was in effect when the
202    binfile was produced.
203    \end{itemize}
204    
205  \subsection{Members of a library}  \subsection{Members of a library}
206    
207  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
# Line 183  Line 226 
226    
227  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
228  sub-libraries to be distinct from the exports of ML source files in  sub-libraries to be distinct from the exports of ML source files in
229  the current library or group.  If an ML source file re-defines an  the current library or group.  If an ML source file $f$ re-defines a
230  imported name, then the disambiguating rule is that the definition  name $n$ that is also imported from library or library component $l$,
231  from the ML source takes precedence over the definition imported from  then the disambiguating rule is that the definition from $f$ takes
232  the group or library.  precedence over that from $l$ in all sources except $f$ itself.  Free
233    occurences of $n$ in $f$ refer to $l$'s definition.  This rule makes
234    it possible to easily write code for exporting an ``augmented''
235    version of some module.  Example:
236    
237    \begin{verbatim}
238      structure A = struct (* defines augmented A *)
239          open A           (* refers to imported A *)
240          fun f x = B.f x + C.g (x + 1)
241      end
242    \end{verbatim}
243    
244  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
245  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 208  Line 261 
261  \subsection{Name visibility}  \subsection{Name visibility}
262    
263  In general, all definitions exported from members (i.e., ML source  In general, all definitions exported from members (i.e., ML source
264  files, subgroups and sublibraries) of a library are visible in all ML  files, subgroups and sublibraries) of a library are visible in all
265  source files of that library.  The source code in those source files  other ML source files of that library.  The source code in those
266  can refer to them directly without further qualification.  Here,  source files can refer to them directly without further qualification.
267  ``exported'' means either a top-level definition within an ML source  Here, ``exported'' means either a top-level definition within an ML
268  file or a definition listed in a sublibrary's export list.  source file or a definition listed in a sublibrary's export list.
269    
270  If a library is structured into library components using {\em groups}  If a library is structured into library components using {\em groups}
271  (see Section~\ref{sec:groups}), then---as far as name visibility is  (see Section~\ref{sec:groups}), then---as far as name visibility is
# Line 243  Line 296 
296  internal to each library.  internal to each library.
297    
298  When a library is {\em stabilized} (via {\tt CM.stabilize} -- see  When a library is {\em stabilized} (via {\tt CM.stabilize} -- see
299  Section~\ref{sec:api}), the entire library is compiled to a single  Section~\ref{sec:stable}), the entire library is compiled to a single
300  file (hence groups do not result in separate stable files).  file (hence groups do not result in separate stable files).
301    
302  During development, each group has its own description file which will  During development, each group has its own description file which will
# Line 334  Line 387 
387  same library---a group).  same library---a group).
388  \end{itemize}  \end{itemize}
389    
390    \subsection{Stable libraries}
391    \label{sec:stable}
392    
393    CM distinguishes between libraries that are {\em under development}
394    and libraries that are {\em stable}.  A stable library is created by a
395    call to {\tt CM.stabilize} (see Section~\ref{sec:api}).
396    
397    Access to stable libraries is subject to less internal
398    consistency-checking and touches far fewer file-system
399    objects. Therefore, it is typically more efficient.  Stable libraries
400    play an additional semantic role in the context of access control (see
401    Section~\ref{sec:access}).
402    
403    From the client program's point of view, using a stable library is
404    completely transparent.  When referring to a library---regardless of
405    whether it is under development or stable---one {\em always} uses the
406    name of the library's description file.  CM will check whether there
407    is a stable version of the library and provided that is the case use
408    it.  This means that in the presence of a stable version, the
409    library's actual description file does not have to physically exists
410    (even though its name is used by CM to find the corresponding stable
411    file).
412    
413  \subsection{Top-level groups}  \subsection{Top-level groups}
414    
415  Mainly to facilitate some superficial backward-compatibility, CM also  Mainly to facilitate some superficial backward-compatibility, CM also
# Line 347  Line 423 
423    
424  \subsection{Motivation}  \subsection{Motivation}
425    
426  File naming has been an area notorious for its problems and was the  The main difficulty with file naming lies in the fact that files or
427  cause of most of the gripes from CM's users.  With this in mind, CM  even whole directories may move after CM has already partially (but
428  now takes a different approach to file name resolution.  not fully) processed them.  For example, this happens when the {\em
429    autoloader} (see Section~\ref{sec:autoload}) has been invoked and the
430  The main difficulty lies in the fact that files or even whole  session (including CM's internal state) is then frozen (i.e., saved to
431  directories may move after CM has already partially (but not fully)  a file) via {\tt SMLofNJ.exportML}.
432  processed them.  For example, this happens when the {\em autoloader}  
433  (see Section~\ref{sec:autoload}) has been invoked and the session  CM's configurable {\em path anchor} mechanism enables it to resume
434  (including CM's internal state) is then frozen (i.e., saved to a file)  such a session even when operating in a different environment, perhaps
435  via {\tt SMLofNJ.exportML}.  The new CM is now able to resume such a  on a different machine with different file systems mounted, or a
436  session even when operating in a different environment, perhaps on a  different location of the SML/NJ installation.  Evaluation of path
437  different machine with different file system mounted, or a different  anchors always takes place as late as possible, and CM will re-evaluate
438  location of the SML/NJ installation.  path anchors as this becomes necessary due to changes to their
439    configuration.
 To make this possible, CM provides a configurable mechanism for  
 locating file system objects.  Moreover, it invokes this mechanism  
 always as late as possible and is prepared to re-invoke it after the  
 configuration changes.  
440    
441  \subsection{Basic rules}  \subsection{Basic rules}
442  \label{sec:basicrules}  \label{sec:basicrules}
# Line 532  Line 604 
604  \label{sec:api}  \label{sec:api}
605    
606  Functions that control CM's operation are accessible as members of a  Functions that control CM's operation are accessible as members of a
607  structure named {\tt CM}.  This structure itself is exported from a  structure named {\tt CM} which itself is exported from a library
608  library called {\tt \$smlnj/cm/full.cm} (or, alternatively, {\tt  called {\tt \$smlnj/full.cm} (or, alternatively, {\tt
609  \$smlnj/cm.cm}).  This library is pre-registered for auto-loading at  \$smlnj/cm/full.cm}).  This library is pre-registered for auto-loading
610  the interactive top level.  at the interactive top level.
611    
612  Other libraries can exploit CM's functionality simply by putting a  Other libraries can exploit CM's functionality simply by putting a
613  {\tt \$smlnj/cm/full.cm} entry into their own description file.  {\tt \$smlnj/cm.cm} entry into their own description file.
614  Section~\ref{sec:dynlink} shows one interesting use of this feature.  Section~\ref{sec:dynlink} shows one interesting use of this feature.
615    
616  Here is a description of all members:  Here is a description of all members:
# Line 1609  Line 1681 
1681  The following variables will be defined and bound to 1:  The following variables will be defined and bound to 1:
1682  \begin{itemize}  \begin{itemize}
1683  \item depending on the operating system: {\tt OPSYS\_UNIX}, {\tt  \item depending on the operating system: {\tt OPSYS\_UNIX}, {\tt
1684  OPSYS\_WIN32}, {\tt OPSYS\_MACOS}, {\tt OPSYS\_OS2}, or {\tt  OPSYS\_WIN32}, {\tt OPSYS\_MACOS}, {\tt OPSYS\_OS2}, or \linebreak
1685  OPSYS\_BEOS}  {\tt OPSYS\_BEOS}
1686  \item depending on processor architecture: {\tt ARCH\_SPARC}, {\tt  \item depending on processor architecture: {\tt ARCH\_SPARC}, {\tt
1687  ARCH\_ALPHA32}, {\tt ARCH\_MIPS}, {\tt ARCH\_X86}, {\tt ARCH\_HPPA},  ARCH\_ALPHA32}, {\tt ARCH\_MIPS}, {\tt ARCH\_X86}, {\tt ARCH\_HPPA},
1688  {\tt ARCH\_RS6000}, or {\tt ARCH\_PPC}  {\tt ARCH\_RS6000}, or {\tt ARCH\_PPC}
# Line 1753  Line 1825 
1825  \item {\it Skeleton files} are used to store a highly abbreviated  \item {\it Skeleton files} are used to store a highly abbreviated
1826  version of each ML source file's abstract syntax tree---just barely  version of each ML source file's abstract syntax tree---just barely
1827  sufficient to drive CM's dependency analysis.  Skeleton files are much  sufficient to drive CM's dependency analysis.  Skeleton files are much
1828  smaller and easier to read than actual ML source code.  Therefore, the  smaller and (for a program) easier to read than actual ML source code.
1829  existence of valid skeleton files makes CM a lot faster because  Therefore, the existence of valid skeleton files makes CM a lot faster
1830  usually most parsing operations can be avoided that way.  because usually most parsing operations can be avoided that way.
1831  \item {\it Binfiles} are the SML/NJ equivalent of object files.  They  \item {\it Binfiles} are the SML/NJ equivalent of object files.  They
1832  contain executable code and a symbol table for the associated ML  contain executable code and a symbol table for the associated ML
1833  source file.  source file.
# Line 1785  Line 1857 
1857  CPU architecture and {\it os} a string denoting the current operating  CPU architecture and {\it os} a string denoting the current operating
1858  system type.  system type.
1859    
1860  Library files are a bit of an exception in the sense that they do not  As explained in Section~\ref{sec:stable}, library files are a bit of
1861  require any source files or any other derived files of the same  an exception in the sense that they do not require any source files or
1862  library to exist.  As a consequence, the location of such a library  any other derived files of the same library to exist.  As a
1863  file is best described as being relative to ``the location of the  consequence, the location of such a library file should be described
1864  original CM description file if that description file still existed''.  as being relative to ``the location of the original CM description
1865  (Of course, nothing precludes the CM description file from actually  file if that description file still existed''.  (Of course, nothing
1866  existing, but in the presence of a corresponding library file CM will  precludes the CM description file from actually existing, but in the
1867  not take any notice.)  presence of a corresponding library file CM will not take any notice
1868    of that.)
1869    
1870  {\em Note:} As discussed in section~\ref{sec:toolparam}, CM sometimes  {\em Note:} As discussed in section~\ref{sec:toolparam}, CM sometimes
1871  looks for library files in  looks for library files in {\tt CM/}{\it version}{\tt /}{\it arch}{\tt
1872  {\tt CM/}{\it version}{\tt /}{\it arch}{\tt -}{\it os}.  -}{\it os}.  However, library files are never {\em created} there by
1873  However, library files are never {\em created} there by CM.  If  CM.  If several versions of the same library are to be provided, an
 several versions of the same library are to be provided, an  
1874  administrator must arrange the directory hierarchy accordingly ``by  administrator must arrange the directory hierarchy accordingly ``by
1875  hand''.  hand''.
1876    
# Line 1810  Line 1882 
1882  the time stamp on skeleton file and binfile has to be exactly the  the time stamp on skeleton file and binfile has to be exactly the
1883  same\footnote{CM explicitly sets the time stamp to be the same.} as  same\footnote{CM explicitly sets the time stamp to be the same.} as
1884  the one on the ML source file.  This guarantees that all changes to a  the one on the ML source file.  This guarantees that all changes to a
1885  source will be noticed.\footnote{except for the pathological case where  source will be noticed---even those that revert to an older version of
1886  two different versions of the same source file have exactly the same  a source file.\footnote{except for the pathological case where two
1887  time stamp}  different versions of the same source file have exactly the same time
1888    stamp}
1889    
1890  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
1891  ML-Lex need to be run (see Section~\ref{sec:tools}).  However, the  ML-Lex need to be run (see Section~\ref{sec:tools}).  However, the
# Line 1944  Line 2017 
2017  \subsection{Plug-in Tools}  \subsection{Plug-in Tools}
2018    
2019  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
2020  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
2021  -tool.cm} or {\tt ./}$c${\tt -tool.cm}.  If it sees a file whose name  -tool.cm} or {\tt ./}$c${\tt -tool.cm}.  If it sees a file whose name
2022  ends in suffix $s$ for which no explicit member class has been  ends in suffix $s$ for which no explicit member class has been
2023  specified in the CM description file and for which automatic  specified in the CM description file and for which automatic
# Line 2503  Line 2576 
2576  installation procedure of SML/NJ registers this library for  installation procedure of SML/NJ registers this library for
2577  autoloading at the interactive top level.  autoloading at the interactive top level.
2578    
2579    \begin{small}
2580  \begin{verbatim}  \begin{verbatim}
2581  signature CM = sig  signature CM = sig
2582    
# Line 2555  Line 2629 
2629    
2630      val sources :      val sources :
2631          { arch: string, os: string } option ->          { arch: string, os: string } option ->
2632          string -> { file: string, class: string, derived: bool } list option            string ->
2633              { file: string, class: string, derived: bool } list option
2634    
2635      val symval : string -> int option controller      val symval : string -> int option controller
2636      val load_plugin : string -> bool      val load_plugin : string -> bool
# Line 2565  Line 2640 
2640    
2641  structure CM : CM  structure CM : CM
2642  \end{verbatim}  \end{verbatim}
2643    \end{small}
2644    
2645  \section{Listing of all pre-defined CM identifiers}  \section{Listing of all pre-defined CM identifiers}
2646    
# Line 2598  Line 2674 
2674  Default settings are determined at bootstrap time, i.e., the time when  Default settings are determined at bootstrap time, i.e., the time when
2675  the heap image for SML/NJ's interactive system is  the heap image for SML/NJ's interactive system is
2676  built.\footnote{Normally this is the same as installation time, but  built.\footnote{Normally this is the same as installation time, but
2677  for SML/NJ compiler there is also a {\tt makeml} script for the  for SML/NJ compiler hackers there is also a {\tt makeml} script for the
2678  purpose of bootstrapping.}  At bootstrap time, it is possible to  purpose of bootstrapping.}  At bootstrap time, it is possible to
2679  adjust defaults by using a different set of environment variables  adjust defaults by using a different set of environment variables
2680  $v_b$.  If neither $v_s$ nor $v_b$ were set, a hard-wired fallback  $v_b$.  If neither $v_s$ nor $v_b$ were set, a hard-wired fallback

Legend:
Removed from v.681  
changed lines
  Added in v.682

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