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 592, Mon Apr 3 07:04:12 2000 UTC revision 632, Sat Apr 29 15:50:42 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.26.3 and later)} \\  {\it\small (for SML/NJ version 110.28 and later)} \\
17  User Manual}  User Manual}
18    
19  \setlength{\parindent}{0pt}  \setlength{\parindent}{0pt}
# Line 319  Line 319 
319  system location that they referred to when they were first seen.  system location that they referred to when they were first seen.
320  \end{itemize}  \end{itemize}
321    
322    \subsection{Explicitly anchored paths}
323    
324    It is possible to specify paths that are explicitly anchored.  For
325    this, the first component of a ``standard'' path must start with a
326    dollar symbol {\bf \$}.  The string between {\bf \$} and the first
327    {\bf /} is taken to be the name of the anchor and the string after
328    that {\bf /} is the path relative to the anchor.  An error is
329    signalled whenever the anchor name does not correspond to an existing
330    anchor.
331    
332    Any ``implicitly anchored'' path {\tt foo/bar/baz} (as described above)
333    can alternatively be written {\tt \$foo/foo/bar/baz}.  The advantage
334    of the latter version is that it is clearly stating the {\em
335    intention} that the path be an anchored path.
336    
337    Moreover, the explicit form is slightly more expressive as it permits
338    names such as {\tt \$a/b/c} where the anchor name and the first arc do
339    not coincide.
340    
341    One can abbreviate the frequent case where they do coincide without
342    resorting to implicit syntax by writing {\tt \$/foo/bar/baz} instead
343    of the lengthier {\tt \$foo/foo/bar/baz}.
344    
345    If an explicitly anchored path has only one component and the
346    component coincides with the anchor name, then one can abbreviate it
347    further by writing just {\tt \$foo} instead of {\tt \$/foo} or even
348    {\tt \$foo/foo}.
349    
350  \subsection{Anchor configuration}  \subsection{Anchor configuration}
351  \label{sec:anchors}  \label{sec:anchors}
352    
# Line 583  Line 611 
611  there is no legal syntax to name it.)  there is no legal syntax to name it.)
612    
613  \subsubsection*{Library registry}  \subsubsection*{Library registry}
614    \label{sec:libreg}
615    
616  To be able to share associated data structures, CM maintains an  To be able to share associated data structures, CM maintains an
617  internal registry of all stable libraries that it has encountered  internal registry of all stable libraries that it has encountered
# Line 596  Line 625 
625      val descr : lib -> string      val descr : lib -> string
626      val osstring : lib -> string      val osstring : lib -> string
627      val dismiss : lib -> unit      val dismiss : lib -> unit
628        val unshare : lib -> unit
629    end    end
630  \end{verbatim}  \end{verbatim}
631    
# Line 624  Line 654 
654  Sharing of link-time state created by the library is {\em not}  Sharing of link-time state created by the library is {\em not}
655  affected by this.  affected by this.
656    
657    {\tt CM.Library.unshare} is used to remove a stable library from CM's
658    internal registry, and---at the same time---to inhibit future sharing
659    with its existing link-time state.  Any future references to this
660    library will see newly created state (which will then be properly
661    shared again).  ({\bf Warning:} {\it This feature is not the preferred
662    way of creating unshared state; use functors for that.  However, it
663    can come in handy when two different (and perhaps incompatible)
664    versions of the same library are supposed to coexist---especially if
665    one of the two versions is used by SML/NJ itself.  Normally, only
666    programmers working on SML/NJ's compiler are expected to be using this
667    facility.})
668    
669  \subsubsection*{Internal state}  \subsubsection*{Internal state}
670    
671  For CM to work correctly, it must maintain an up-to-date picture of  For CM to work correctly, it must maintain an up-to-date picture of
# Line 759  Line 801 
801  runtime system in order to perform stand-alone linkage of the given  runtime system in order to perform stand-alone linkage of the given
802  program. Upon failure, {\tt CM.mk\_standalone} returns {\tt NONE}.  program. Upon failure, {\tt CM.mk\_standalone} returns {\tt NONE}.
803    
804    \subsubsection*{Support for {\tt make}}
805    
806    CM has some limited support for generating dependency information that
807    is usable by other compilation management tools, in particular, the
808    {\tt make} program found in {\sc Unix}.
809    
810    \begin{verbatim}
811      val makedepend :
812          { group: string, targetname: string, outstream: TextIO.outstream }
813          -> bool
814    \end{verbatim}
815    
816    A call to {\tt CM.makedepend} writes a dependency entry for target
817    {\tt targetname} to the specified output stream.  The syntax is the
818    one used by {\tt make}'s makefiles. The actual dependencies are those
819    implicitly given by library {\tt group}, while the targetname is an
820    arbitrary, uninterpreted string.
821    
822    Source items that appear in the dependency list can be:
823    \begin{itemize}
824    \item ML source file names which are members of non-stable libraries,
825    \item CM description file names for non-stable libraries and groups, or
826    \item names of files containing stable libraries.
827    \end{itemize}
828    
829    Note that names of stable libraries vary depending on operation system
830    and CPU type.
831    
832  \subsection{The autoloader}  \subsection{The autoloader}
833  \label{sec:autoload}  \label{sec:autoload}
834    
# Line 838  Line 908 
908  a user program running under control of the interactive system, then  a user program running under control of the interactive system, then
909  CM will let them share code and dynamic state.  CM will let them share code and dynamic state.
910    
911    \section{Version numbers}
912    \label{sec:versions}
913    
914    A CM library can carry a version number.  Version numbers are
915    specified in parentheses after the keyword {\tt Library} as non-empty
916    dot-separated sequences of non-negative integers.  Example:
917    
918    \begin{verbatim}
919    Library (1.4.1.4.2.1.3.5)
920            structure Sqrt2
921    is
922            sqrt2.sml
923            basis.cm
924    \end{verbatim}
925    
926    \subsection{How versions are compared}
927    
928    Version numbers are compared lexicographically, dot-separated
929    component by dot-separated component, from left to right.  The
930    components themselves are compared numerically.
931    
932    \subsection{Version checking}
933    
934    An importing library or library component can specify which version of
935    the imported library it would like to see.  See the discussion is
936    section~\ref{sec:toolparam} for how this is done.  Where a version
937    number is requested, an error is signalled if one of the following is
938    true:
939    
940    \begin{itemize}
941    \item the imported library does not carry a version number
942    \item the imported library's version number is smaller than the
943    one requested
944    \item the imported library's version number has a first component
945    (known as the ``major'' version number) that is greater than the one
946    requested
947    \end{itemize}
948    
949    A warning (but no error) is issued if the imported library has the
950    same major version but the version as a whole is greater than the one
951    requested.
952    
953    Note: {\it Version numbers should be incremented on every change to a
954    library.  The major version number should be increased on every change
955    that is not backward-compatible.}
956    
957  \section{Member classes and tools}  \section{Member classes and tools}
958  \label{sec:classes}  \label{sec:classes}
959    
# Line 877  Line 993 
993  ordinary ML source files and {\tt cm} is the class of CM library or  ordinary ML source files and {\tt cm} is the class of CM library or
994  group description files.  group description files.
995    
996  CM automatically classifies file with a {\tt .sml} or {\tt .sig}  CM automatically classifies files with a {\tt .sml} suffix, a {\tt
997  suffix as ML-source, file names ending in {\tt .cm}] as CM  .sig} suffix, or a {\tt .fun} suffix as ML-source, file names ending
998  descriptions.  in {\tt .cm}] as CM descriptions.\footnote{Suffixes that are not known
999    and for which no plugin module can be found are treated as ML source
1000    code.  However, as new tools are added there is no guarantee that
1001    this behavior will be preserved in future versions of CM.}
1002    
1003  \subsection{Tool parameters}  \subsection{Tool parameters}
1004    \label{sec:toolparam}
1005    
1006  In many cases the name of the member that caused a rule to be invoked  In many cases the name of the member that caused a rule to be invoked
1007  is the only input to that rule.  However, rules can be written in such  is the only input to that rule.  However, rules can be written in such
# Line 908  Line 1028 
1028  means that dynamic state cannot be shared across such calls to {\tt  means that dynamic state cannot be shared across such calls to {\tt
1029  CM.make} or {\tt CM.autoload}.  CM.make} or {\tt CM.autoload}.
1030    
1031  The {\tt cm} class does not accept any parameters.  The {\tt cm} class accepts one named parameter, labelled by the string
1032    {\tt version}.  The parameter itself must have the format of a version
1033    number.  CM will interpret this as a version request, thereby insuring
1034    that the imported library is not too old or too new. (See
1035    section~\ref{sec:versions} for more on this topic.)
1036    
1037  Named sub-option lists are specified by a name string followed by a  Named sub-option lists are specified by a name string followed by a
1038  colon {\bf :} and a parenthesized list of other tool options.  If the  colon {\bf :} and a parenthesized list of other tool options.  If the
1039  list contains precisely one element, the parentheses may be omitted.  list contains precisely one element, the parentheses may be omitted.
1040    Example:
1041    
1042    \begin{verbatim}
1043        euler.cm (version:2.71828)
1044        pi.cm    (version:3.14159)
1045    \end{verbatim}
1046    
1047    Normally, CM looks for stable library files in directory
1048    {\tt CM/}{\it arch}{\tt -}{\it os} (see section~\ref{sec:files}).
1049    However, if an explicit version has been requested, it will first try
1050    directory {\tt CM/}{\it version}{\tt /}{\it arch}{\tt -}{\it os}
1051    before looking at the default location.  This way it is possible to
1052    keep several versions of the same library in the file system.
1053    
1054    However, CM normally does {\em not} permit the simultaneous use of
1055    multiple versions of the same library in one session.  The
1056    disambiguating rule is that the version that gets loaded first
1057    ``wins''; subsequent attempts to load different versions result in
1058    warnings or errors.  (See the discussion of {\tt CM.unshare} in
1059    section~\ref{sec:libreg} for how to to circumvent this restriction.)
1060    
1061  \subsection{Built-in tools}  \subsection{Built-in tools}
1062    
# Line 1291  Line 1435 
1435  non-modular bindings from one compilation unit to another.  non-modular bindings from one compilation unit to another.
1436    
1437  \section{Files}  \section{Files}
1438    \label{sec:files}
1439    
1440  CM uses three kinds of files to store derived information during and  CM uses three kinds of files to store derived information during and
1441  between sessions:  between sessions:
# Line 1337  Line 1482 
1482  existing, but in the presence of a corresponding library file CM will  existing, but in the presence of a corresponding library file CM will
1483  not take any notice.)  not take any notice.)
1484    
1485    {\em Note:} As discussed in section~\ref{sec:toolparam}, CM sometimes
1486    looks for library files in
1487    {\tt CM/}{\tt version}{\tt /}{\it arch}{\tt -}{\it os}.
1488    However, library files are never {\em created} there by CM.  If
1489    several versions of the same library are to be provided, an
1490    administrator must arrange the directory hierarchy accordingly ``by
1491    hand''.
1492    
1493  \subsection{Time stamps}  \subsection{Time stamps}
1494    
1495  For skeleton files and binfiles, CM uses file system time stamps to  For skeleton files and binfiles, CM uses file system time stamps to

Legend:
Removed from v.592  
changed lines
  Added in v.632

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