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 684, Tue Jul 11 04:57:48 2000 UTC revision 685, Tue Jul 11 08:54:09 2000 UTC
# Line 392  Line 392 
392    
393  CM distinguishes between libraries that are {\em under development}  CM distinguishes between libraries that are {\em under development}
394  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
395  call to {\tt CM.stabilize} (see Section~\ref{sec:api}).  call to {\tt CM.stabilize} (see Section~\ref{sec:api:compiling}).
396    
397  Access to stable libraries is subject to less internal  Access to stable libraries is subject to less internal
398  consistency-checking and touches far fewer file-system  consistency-checking and touches far fewer file-system
# Line 557  Line 557 
557  installation-specific one and a user-specific one.  After that, the  installation-specific one and a user-specific one.  After that, the
558  contents of root locations can be maintained using CM's interface  contents of root locations can be maintained using CM's interface
559  functions {\tt CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see  functions {\tt CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see
560  Section~\ref{sec:api}).  Section~\ref{sec:api:anchors}).
561    
562  Although there is a hard-wired default for the installation-specific  Although there is a hard-wired default for the installation-specific
563  configuration file\footnote{which happens to be {\tt  configuration file\footnote{which happens to be {\tt
# Line 615  Line 615 
615    
616  Here is a description of all members:  Here is a description of all members:
617    
618  \subsubsection*{Compiling}  \subsubsection{Compiling}
619    \label{sec:api:compiling}
620    
621  Two main activities when using CM are to compile ML source code and to  Two main activities when using CM are to compile ML source code and to
622  build stable libraries:  build stable libraries:
# Line 649  Line 650 
650  The boolean result of {\tt CM.recomp} and {\tt CM.stabilize} indicates  The boolean result of {\tt CM.recomp} and {\tt CM.stabilize} indicates
651  success or failure of the operation ({\tt true} = success).  success or failure of the operation ({\tt true} = success).
652    
653  \subsubsection*{Linking}  \subsubsection{Linking}
654    
655  In SML/NJ, linking means executing top-level code (i.e., module  In SML/NJ, linking means executing top-level code (i.e., module
656  creation and initialization code) of each compilation unit.  The  creation and initialization code) of each compilation unit.  The
# Line 687  Line 688 
688  failure of the {\em registration}.  (It does not know yet whether  failure of the {\em registration}.  (It does not know yet whether
689  loading will actually succeed.)  loading will actually succeed.)
690    
691  \subsubsection*{Registers}  \subsubsection{Registers}
692    
693  Several internal registers control the operation of CM.  A register of  Several internal registers control the operation of CM.  A register of
694  type $T$ is accessible via a variable of type $T$ {\tt controller},  type $T$ is accessible via a variable of type $T$ {\tt controller},
# Line 760  Line 761 
761  The default ({\em false}) can be overridden at startup by the  The default ({\em false}) can be overridden at startup by the
762  environment variable {\tt CM\_CONSERVE\_MEMORY}.  environment variable {\tt CM\_CONSERVE\_MEMORY}.
763    
764  \subsubsection*{Path anchors}  \subsubsection{Path anchors}
765    \label{sec:api:anchors}
766    
767  Structure {\tt CM} also provides functions to explicitly manipulate  Structure {\tt CM} also provides functions to explicitly manipulate
768  the path anchor configuration.  These functions are members of  the path anchor configuration.  These functions are members of
# Line 788  Line 790 
790  After a call of this function has completed, all root environment  After a call of this function has completed, all root environment
791  locations are marked as being ``undefined''.  locations are marked as being ``undefined''.
792    
793  \subsubsection*{Setting CM variables}  \subsubsection{Setting CM variables}
794    
795  CM variables are used by the conditional compilation system (see  CM variables are used by the conditional compilation system (see
796  Section~\ref{sec:cmvars}).  Some of these variables are predefined,  Section~\ref{sec:cmvars}).  Some of these variables are predefined,
# Line 817  Line 819 
819  not accessible\footnote{from within CM's description files} because  not accessible\footnote{from within CM's description files} because
820  there is no legal syntax to name it.)  there is no legal syntax to name it.)
821    
822  \subsubsection*{Library registry}  \subsubsection{Library registry}
823  \label{sec:libreg}  \label{sec:libreg}
824    
825  To be able to share associated data structures such as symbol tables  To be able to share associated data structures such as symbol tables
# Line 877  Line 879 
879  programmers working on SML/NJ's compiler are expected to be using this  programmers working on SML/NJ's compiler are expected to be using this
880  facility.})  facility.})
881    
882  \subsubsection*{Internal state}  \subsubsection{Internal state}
883    
884  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
885  the state of the surrounding world (as far as that state affects CM's  the state of the surrounding world (as far as that state affects CM's
# Line 911  Line 913 
913  with pre-loaded libraries.  It may be a useful tool for determining  with pre-loaded libraries.  It may be a useful tool for determining
914  the amount of space taken up by the internal state, though.  the amount of space taken up by the internal state, though.
915    
916  \subsubsection*{Compile servers}  \subsubsection{Compile servers}
917    
918  On Unix-like systems, CM supports parallel compilation.  For computers  On Unix-like systems, CM supports parallel compilation.  For computers
919  connected using a LAN, this can be extended to distributed compilation  connected using a LAN, this can be extended to distributed compilation
# Line 959  Line 961 
961  string that was originally given to the call of\linebreak {\tt  string that was originally given to the call of\linebreak {\tt
962  CM.Server.start} used to created the server.  CM.Server.start} used to created the server.
963    
964  \subsubsection*{Plug-ins}  \subsubsection{Plug-ins}
965    
966  As an alternative to {\tt CM.make} or {\tt CM.autoload}, where the  As an alternative to {\tt CM.make} or {\tt CM.autoload}, where the
967  main purpose is to subsequently be able to access the library from  main purpose is to subsequently be able to access the library from
# Line 987  Line 989 
989  and tools very easily without having to reconfigure or recompile CM,  and tools very easily without having to reconfigure or recompile CM,
990  not to mention modify its source code.  not to mention modify its source code.
991    
992  \subsubsection*{Building stand-alone programs}  \subsubsection{Building stand-alone programs}
993    
994  CM can be used to build stand-alone programs. In fact SML/NJ  CM can be used to build stand-alone programs. In fact SML/NJ
995  itself---including CM---is an example of this.  (The interactive  itself---including CM---is an example of this.  (The interactive
# Line 1026  Line 1028 
1028    ml-build myproglib.cm MyProg.main myprog    ml-build myproglib.cm MyProg.main myprog
1029  \end{verbatim}  \end{verbatim}
1030    
1031  \subsubsection*{Finding all sources}  \subsubsection{Finding all sources}
1032    
1033  The {\tt CM.sources} function can be used to find the names of all  The {\tt CM.sources} function can be used to find the names of all
1034  source files that a given library depends on.  It returns the names of  source files that a given library depends on.  It returns the names of
# Line 1068  Line 1070 
1070           "foo.cm");           "foo.cm");
1071  \end{verbatim}  \end{verbatim}
1072  \item[finding all {\tt noweb} sources:]  \item[finding all {\tt noweb} sources:]
1073  To find all {\tt noweb} sources (see Section~\ref{sec:builtin-tools}),  To find all {\tt noweb} sources (see Section~\ref{sec:builtin-tools:noweb}),
1074  e.g., to be able to run the document preparation program {\tt noweave}  e.g., to be able to run the document preparation program {\tt noweave}
1075  on them, one can simply look for entries of the {\tt noweb} class.  on them, one can simply look for entries of the {\tt noweb} class.
1076  Here, one would probably want to include derived sources:  Here, one would probably want to include derived sources:
# Line 1130  Line 1132 
1132    
1133  % Need a good example here.  % Need a good example here.
1134    
1135  \subsubsection*{Sharing annotations}  \subsubsection{Sharing annotations}
1136    
1137  ML source files in CM description files can be specified as being {\em  ML source files in CM description files can be specified as being {\em
1138  private} or {\em shared}.  This is done by adding a {\em tool  private} or {\em shared}.  This is done by adding a {\em tool
# Line 1145  Line 1147 
1147  source.  It is an error, checked by CM, for a {\em shared} source to  source.  It is an error, checked by CM, for a {\em shared} source to
1148  depend on a {\em private} source.  depend on a {\em private} source.
1149    
1150  \subsubsection*{Sharing with the interactive system}  \subsubsection{Sharing with the interactive system}
1151    
1152  The SML/NJ interactive system, which includes the compiler, is itself  The SML/NJ interactive system, which includes the compiler, is itself
1153  created by linking modules from various libraries. Some of these  created by linking modules from various libraries. Some of these
# Line 1182  Line 1184 
1184    
1185  An importing library or library component can specify which version of  An importing library or library component can specify which version of
1186  the imported library it would like to see.  See the discussion is  the imported library it would like to see.  See the discussion is
1187  section~\ref{sec:toolparam} for how this is done.  Where a version  section~\ref{sec:toolparam:cm} for how this is done.  Where a version
1188  number is requested, an error is signalled if one of the following is  number is requested, an error is signalled if one of the following is
1189  true:  true:
1190    
# Line 1266  Line 1268 
1268  rule function.  It is in each rule's own responsibility to assign  rule function.  It is in each rule's own responsibility to assign
1269  meaning to its options.  meaning to its options.
1270    
1271  \subsubsection*{Parameters for class {\tt sml}}  \subsubsection{Parameters for class {\tt sml}}
1272    
1273  The {\tt sml} class accepts two optional parameters.  One is the {\em  The {\tt sml} class accepts two optional parameters.  One is the {\em
1274  sharing annotation} that was explained earlier (see  sharing annotation} that was explained earlier (see
# Line 1310  Line 1312 
1312  to them, and neither can code that in the future might be entered at  to them, and neither can code that in the future might be entered at
1313  top level.  top level.
1314    
1315  \subsubsection*{Parameters for class {\tt cm}}  \subsubsection{Parameters for class {\tt cm}}
1316    \label{sec:toolparam:cm}
1317    
1318  The {\tt cm} class understands two kinds of parameters.  The first is  The {\tt cm} class understands two kinds of parameters.  The first is
1319  a named parameter labeled by the string {\tt version}.  It must have  a named parameter labeled by the string {\tt version}.  It must have
# Line 1353  Line 1356 
1356  \subsection{Built-in tools}  \subsection{Built-in tools}
1357  \label{sec:builtin-tools}  \label{sec:builtin-tools}
1358    
1359  \subsubsection*{The ML-Yacc tool}  \subsubsection{ML-Yacc}
1360    
1361  The ML-Yacc tool is responsible for files that are input to the  The ML-Yacc tool is responsible for files that are input to the
1362  ML-Yacc parser generator.  Its class name is {\tt mlyacc}.  Recognized  ML-Yacc parser generator.  Its class name is {\tt mlyacc}.  Recognized
# Line 1379  Line 1382 
1382  using the operating system's path search mechanism (e.g., the {\tt  using the operating system's path search mechanism (e.g., the {\tt
1383  \$PATH} environment variable).  \$PATH} environment variable).
1384    
1385  \subsubsection*{ML-Lex}  \subsubsection{ML-Lex}
1386    
1387  The ML-Lex tool governs files that are input to the ML-Lex lexical  The ML-Lex tool governs files that are input to the ML-Lex lexical
1388  analyzer generator~\cite{appel89:lex}.  Its class name is {\tt mllex}.  analyzer generator~\cite{appel89:lex}.  Its class name is {\tt mllex}.
# Line 1394  Line 1397 
1397  ml-lex} will be located using the operating system's path search  ml-lex} will be located using the operating system's path search
1398  mechanism (e.g., the {\tt \$PATH} environment variable).  mechanism (e.g., the {\tt \$PATH} environment variable).
1399    
1400  \subsubsection*{ML-Burg}  \subsubsection{ML-Burg}
1401    
1402  The ML-Burg tool deals with files that are input to the ML-Burg  The ML-Burg tool deals with files that are input to the ML-Burg
1403  code-generater generator~\cite{mlburg93}.  Its class name is {\tt  code-generater generator~\cite{mlburg93}.  Its class name is {\tt
# Line 1409  Line 1412 
1412  using the operating system's path search mechanism (e.g., the {\tt  using the operating system's path search mechanism (e.g., the {\tt
1413  \$PATH} environment variable).  \$PATH} environment variable).
1414    
1415  \subsubsection*{Shell}  \subsubsection{Shell}
1416    
1417  The Shell tool can be used to specify arbitrary shell commands to be  The Shell tool can be used to specify arbitrary shell commands to be
1418  invoked on behalf of a given file.  The name of the class is {\tt  invoked on behalf of a given file.  The name of the class is {\tt
# Line 1480  Line 1483 
1483  The shell tool invokes its command whenever the target is outdated  The shell tool invokes its command whenever the target is outdated
1484  with respect to the source.  with respect to the source.
1485    
1486  \subsubsection*{Make}  \subsubsection{Make}
1487    
1488  The Make tool (class {\tt make}) can (almost) be seen as a specialized  The Make tool (class {\tt make}) can (almost) be seen as a specialized
1489  version of the Shell tool.  It has no source and one target (the  version of the Shell tool.  It has no source and one target (the
# Line 1522  Line 1525 
1525                   -f bar-pp.mk)                   -f bar-pp.mk)
1526  \end{verbatim}  \end{verbatim}
1527    
1528  \subsubsection*{Noweb}  \subsubsection{Noweb}
1529    \label{sec:builtin-tools:noweb}
1530    
1531  The {\tt noweb} class handles sources written for Ramsey's {\it noweb}  The {\tt noweb} class handles sources written for Ramsey's {\it noweb}
1532  literate programming facility~\cite{ramsey:simplified}.  Files ending  literate programming facility~\cite{ramsey:simplified}.  Files ending
# Line 1867  Line 1871 
1871  presence of a corresponding library file CM will not take any notice  presence of a corresponding library file CM will not take any notice
1872  of that.)  of that.)
1873    
1874  {\em Note:} As discussed in section~\ref{sec:toolparam}, CM sometimes  {\em Note:} As discussed in section~\ref{sec:toolparam:cm}, CM sometimes
1875  looks for library files in {\tt CM/}{\it version}{\tt /}{\it arch}{\tt  looks for library files in {\tt CM/}{\it version}{\tt /}{\it arch}{\tt
1876  -}{\it os}.  However, library files are never {\em created} there by  -}{\it os}.  However, library files are never {\em created} there by
1877  CM.  If several versions of the same library are to be provided, an  CM.  If several versions of the same library are to be provided, an

Legend:
Removed from v.684  
changed lines
  Added in v.685

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