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 587, Thu Mar 30 09:01:52 2000 UTC revision 588, Fri Mar 31 09:00:02 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.27 and later)} \\  {\it\small (for SML/NJ version 110.26.3 and later)} \\
17  User Manual}  User Manual}
18    
19  \setlength{\parindent}{0pt}  \setlength{\parindent}{0pt}
# Line 884  Line 884 
884  parentheses following the name of the member and the optional member  parentheses following the name of the member and the optional member
885  class.  class.
886    
887  As far as CM's core tool mechanism is concerned, tool parameters are  CM's core mechanism parses these tool options and breaks them up into
888  uninterpreted---they are just list of strings.  Each rule is  a list of items, where each item is either a filename (i.e., {\em
889  responsible for assigning meaning to its own parameters.  looks} like a filename) or a named list of sub-options.  However, CM
890    itself does not interpret the result but passes it on to the tool's
891    rule function.  It is in each rule's own responsibility to assign
892    meaning to its options.
893    
894  The {\tt sml} class accepts one parameter which must be either the  The {\tt sml} class accepts one parameter which must be either the
895  word {\tt shared} or the word {\tt private}.  If {\tt shared} is  word {\tt shared} or the word {\tt private}.  (Technically, the
896  specified, then dynamic state created by the compilation unit at  strings {\tt private} and {\tt shared} fall under the {\em filename}
897  link-time must be shared across invocations of {\tt CM.make} or {\tt  category from above, but the tool ignores that aspect and uses the
898  CM.autoload}.  As explained earlier (Section~\ref{sec:sharing}), the  name directly.) If {\tt shared} is specified, then dynamic state
899  {\tt private} annotation means that dynamic state cannot be shared  created by the compilation unit at link-time must be shared across
900  across such calls to {\tt CM.make} or {\tt CM.autoload}.  invocations of {\tt CM.make} or {\tt CM.autoload}.  As explained
901    earlier (Section~\ref{sec:sharing}), the {\tt private} annotation
902    means that dynamic state cannot be shared across such calls to {\tt
903    CM.make} or {\tt CM.autoload}.
904    
905  The {\tt cm} class does not accept any parameters.  The {\tt cm} class does not accept any parameters.
906    
907    Named sub-option lists are specified by a name string followed by a
908    colon {\bf :} and a parenthesized list of other tool options.  If the
909    list contains precisely one element, the parentheses may be omitted.
910    
911  \subsection{Built-in tools}  \subsection{Built-in tools}
912    
913  \subsubsection*{The ML-Yacc tool}  \subsubsection*{The ML-Yacc tool}
# Line 908  Line 918 
918  $f$, the tool produces two targets $f${\tt .sig} and $f${\tt .sml},  $f$, the tool produces two targets $f${\tt .sig} and $f${\tt .sml},
919  both of which are always treated as ML source files.  Parameters are  both of which are always treated as ML source files.  Parameters are
920  passed on without change to the $f${\tt .sml} file but not to the  passed on without change to the $f${\tt .sml} file but not to the
921  $f${\tt .sig} file.  $f${\tt .sig} file.  This means that the parameter can either be the
922    word {\tt private} or the word {\tt shared}, and that this sharing
923    annotation will apply to the $f${\tt .sml} file.
924    
925  The tool invokes the {\tt ml-yacc} command if the targets are  The tool invokes the {\tt ml-yacc} command if the targets are
926  ``outdated''.  A target is outdated if it is missing or older than the  ``outdated''.  A target is outdated if it is missing or older than the
# Line 962  Line 974 
974  Consider the following example:  Consider the following example:
975    
976  \begin{verbatim}  \begin{verbatim}
977    foo.pp : shell (target=foo.sml options=shared    foo.pp : shell (target:foo.sml options:(shared)
978                          /lib/cpp -P -Dbar=baz %s %t)                          /lib/cpp -P -Dbar=baz %s %t)
979  \end{verbatim}  \end{verbatim}
980    
981  This member specification says that file {\tt foo.sml} can be obtained  This member specification says that file {\tt foo.sml} can be obtained
982  from {\tt foo.pp} by running it through the C preprocessor {\tt cpp}.  from {\tt foo.pp} by running it through the C preprocessor {\tt cpp}.
983  The fact that the target file is given as a tool parameter implies  The fact that the target file is given as a tool parameter implies
984  that the member itself is the source.  The {\tt options=} parameter  that the member itself is the source.  The named parameter {\tt
985  lists the tool parameters to be used for that target.  The command  options} lists the tool parameters to be used for that target. (In the
986  line itself is given by the remaining non-keyword parameters.  Here, a  example, the parentheses around {\tt shared} are optional because it
987  single {\bf \%s} is replaced by the source file name, and a single {\bf  is the only element of the list.) The command line itself is given by
988  \%t} is replaced by the target file name.  the remaining non-keyword parameters.  Here, a single {\bf \%s} is
989    replaced by the source file name, and a single {\bf \%t} is replaced
990    by the target file name; any other string beginning with {\bf \%} is
991    shortened by its first character.
992    
993  In the specification one can swap the positions of source and target  In the specification one can swap the positions of source and target
994  (i.e., let member name be the target) by using a {\tt source=}  (i.e., let member name be the target) by using a {\tt source}
995  parameter:  parameter:
996    
997  \begin{verbatim}  \begin{verbatim}
998    foo.sml : shell (source=foo.pp options=shared    foo.sml : shell (source:foo.pp options:shared
999                           /lib/cpp -P -Dbar=baz %s %t)                           /lib/cpp -P -Dbar=baz %s %t)
1000  \end{verbatim}  \end{verbatim}
1001    
1002  Exactly one of the {\tt source=} and {\tt target=} parameters must be  Exactly one of the {\tt source} and {\tt target} parameters must be
1003  specified; the other one is taken to be the member name itself.  The  specified; the other one is taken to be the member name itself.  The
1004  target class can be given by writing a {\tt class=} parameter.  target class can be given by writing a {\tt class} parameter whose
1005    single sub-option must be the desired class name.
1006    
1007  If the member name is written using {\em native path syntax}, then the  The usual distinction between native and standard filename syntax
1008  source- or target-name in the parameter list is also considered to be  applies to any given {\tt source} or {\tt target} parameters.
 using native syntax.  Although it is possible to enclose tool  
 parameters in double quotes to avoid tokenization at delimiting  
 characters, in this case this does not have the effect of switching  
 from standard to native syntax.  
1009    
1010  For example, if one were working on a Win32 system and the target file  For example, if one were working on a Win32 system and the target file
1011  is supposed to be in the root directory on volume {\tt D:},  is supposed to be in the root directory on volume {\tt D:},
# Line 1001  Line 1013 
1013  would be:  would be:
1014    
1015  \begin{verbatim}  \begin{verbatim}
1016    "D:\\foo.sml" : shell (source=foo.pp options=shared    "D:\\foo.sml" : shell (source : foo.pp options : shared
1017                                 cpp -P -Dbar=baz %s %t)                                 cpp -P -Dbar=baz %s %t)
1018  \end{verbatim}  \end{verbatim}
1019    
1020  \noindent As a result, {\tt foo.pp} is also interpreted as a native  \noindent As a result, {\tt foo.sml} is interpreted using native
1021  path name (although in this case it does not make a difference).  Had  syntax while {\tt foo.pp} uses standard conventions (although in this
1022  we used the {\tt target=} version from above, it would {\em not} be  case it does not make a difference).  Had we used the {\tt target}
1023  sufficient to do the following:  version from above, one would have to write:
1024    
1025  \begin{verbatim}  \begin{verbatim}
1026    foo.pp : shell ("target=D:\\foo.sml" options=shared    foo.pp : shell (target : "D:\\foo.sml" options : shared
1027                                   cpp -P -Dbar=baz %s %t)                                   cpp -P -Dbar=baz %s %t)
1028  \end{verbatim}  \end{verbatim}
1029    
 \noindent Since the member name {\tt foo.pp} is in standard syntax,  
 the target name will also be interpreted this way regardless of the  
 fact that the parameter uses double quotes.  The correct specification  
 is:  
   
 \begin{verbatim}  
   "foo.pp" : shell ("target=D:\\foo.sml" options=shared  
                                 cpp -P -Dbar=baz %s %t)  
 \end{verbatim}  
   
 \noindent Notice that double quotes around the target parameter are still  
 necessary because the name contains delimiters.  
   
1030  The shell tool invokes its command whenever the target is outdated  The shell tool invokes its command whenever the target is outdated
1031  with respect to the source.  with respect to the source.
1032    
# Line 1037  Line 1036 
1036  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
1037  member itself) which is always considered outdated.  As with the Shell  member itself) which is always considered outdated.  As with the Shell
1038  tool, it is possible to specify target class and parameters using the  tool, it is possible to specify target class and parameters using the
1039  {\tt class=} and {\tt options=} keyword parameters.  {\tt class} and {\tt options} keyword parameters.
1040    
1041  The tool invokes the shell command {\tt make} on the target.  Unless  The tool invokes the shell command {\tt make} on the target.  Unless
1042  anchored using the path anchor mechanism~\ref{sec:anchors}, the  anchored using the path anchor mechanism~\ref{sec:anchors}, the
1043  command will be located using the operating system's path search  command will be located using the operating system's path search
1044  mechanism (e.g., the {\tt \$PATH} environment variable).  mechanism (e.g., the {\tt \$PATH} environment variable).
1045    
1046  Any tool parameters beyond the initial {\tt class=} and {\tt options=}  Any parameters other than the {\tt class} and {\tt options}
1047  are given as additional command line arguments to {\tt make}.  The  specifications must be plain strings and are given as additional
1048  target name is always the last command line argument.  command line arguments to {\tt make}.  The target name is always the
1049    last command line argument.
1050    
1051  Example:  Example:
1052    
1053  \begin{verbatim}  \begin{verbatim}
1054    bar-grm : make (class=mlyacc -f bar-grm.mk)    bar-grm : make (class:mlyacc -f bar-grm.mk)
1055  \end{verbatim}  \end{verbatim}
1056    
1057  Here, file {\tt bar-grm} is generated (and kept up-to-date) by  Here, file {\tt bar-grm} is generated (and kept up-to-date) by
# Line 1061  Line 1061 
1061  \end{verbatim}  \end{verbatim}
1062  \noindent The target file is then treated as input for {\tt ml-yacc}.  \noindent The target file is then treated as input for {\tt ml-yacc}.
1063    
1064  Cascading Shell- and Make-tools is tricky but possible.  Here is an  Cascading Shell- and Make-tools is easily possible.  Here is an
1065  example that first uses Make to build {\tt bar.pp} and then filters  example that first uses Make to build {\tt bar.pp} and then filters
1066  the contens of {\tt bar.pp} through the C preprocessor to arrive at  the contens of {\tt bar.pp} through the C preprocessor to arrive at
1067  {\tt bar.sml}:  {\tt bar.sml}:
1068    
1069  \begin{verbatim}  \begin{verbatim}
1070    bar.pp : make (class=shell    bar.pp : make (class:shell
1071                       "options=target=bar.sml cpp -Dbar=baz %s %t"                       options:(target:bar.sml cpp -Dbar=baz %s %t)
1072                   -f bar-pp.mk)                   -f bar-pp.mk)
1073  \end{verbatim}  \end{verbatim}
1074    
# Line 1378  Line 1378 
1378      extensionStyle =      extensionStyle =
1379          Tools.EXTEND [("sig", SOME "sml", fn _ => NONE),          Tools.EXTEND [("sig", SOME "sml", fn _ => NONE),
1380                        ("sml", SOME "sml", fn x => x)],                        ("sml", SOME "sml", fn x => x)],
1381      dflopts = NONE }      dflopts = [] }
1382  \end{verbatim}  \end{verbatim}
1383    
1384  This code can either be packaged as a CM library or entered at the  This code can either be packaged as a CM library or entered at the
# Line 1417  Line 1417 
1417      targets---separated by single spaces---are inserted;      targets---separated by single spaces---are inserted;
1418      if $n$ is not in the range between $0$ and the number of available      if $n$ is not in the range between $0$ and the number of available
1419      targets, then {\bf \%$n$t} expands into itself)      targets, then {\bf \%$n$t} expands into itself)
1420    \item[\%$n$o] the $n$-th option; \\    \item[\%$n$o] the $n$-th tool parameter; \\
1421      ($n$ is specified as a decimal number, counting starts at $1$;      (named sub-option parameters are ignored;
1422         $n$ is specified as a decimal number, counting starts at $1$;
1423       if $n$ is $0$ (or missing), then all options---separated by single       if $n$ is $0$ (or missing), then all options---separated by single
1424       spaces---are inserted;       spaces---are inserted;
1425       if $n$ is not in the range between $0$ and the number of available       if $n$ is not in the range between $0$ and the number of available
# Line 1426  Line 1427 
1427    \item[\%$x$] the character $x$ (where $x$ is neither {\bf c}, nor    \item[\%$x$] the character $x$ (where $x$ is neither {\bf c}, nor
1428      {\bf s}, {\bf t}, or {\bf o})      {\bf s}, {\bf t}, or {\bf o})
1429    \end{description}    \end{description}
1430  If no template string is given it defaults to {\tt "\%c \%s"}.  If no template string is given, then it defaults to {\tt "\%c \%s"}.
1431  \item[extensionStyle] a specification of how the names of files  \item[extensionStyle] a specification of how the names of files
1432  generated by the tool relate to the name of the tool input file; \\  generated by the tool relate to the name of the tool input file; \\
1433  Currently, there are two possible cases:  Currently, there are two possible cases:
# Line 1435  Line 1436 
1436  {\it file} then for each suffix {\it sfx} in {\tt (map \#1 $l$)} there  {\it file} then for each suffix {\it sfx} in {\tt (map \#1 $l$)} there
1437  will be one tool output file named {\it file}{\tt .}{\it sfx}.  The  will be one tool output file named {\it file}{\tt .}{\it sfx}.  The
1438  list $l$ consists of triplets where the first component specifies the  list $l$ consists of triplets where the first component specifies the
1439  suffix string, where the second component optionally specifies the  suffix string, the second component optionally specifies the
1440  member class name of the corresponding derived file, and where the  member class name of the corresponding derived file, and the
1441  third component is a function to calculate tool options for the  third component is a function to calculate tool options for the
1442  target from those of the source. (Argument and result type of these  target from those of the source. (Argument and result type of these
1443  functions is {\tt string list option}.)  functions is {\tt Tools.toolopts option}.)
1444  \item ``{\tt Tools.REPLACE }$(l_1, l_2)$'' specifies that given the  \item ``{\tt Tools.REPLACE }$(l_1, l_2)$'' specifies that given the
1445  base name {\it base} there will be one tool output file {\it base}{\tt  base name {\it base} there will be one tool output file {\it base}{\tt
1446  .}{\it sfx} for each suffix {\it sfx} in {\tt (map \#1 $l_2$)}.  Here,  .}{\it sfx} for each suffix {\it sfx} in {\tt (map \#1 $l_2$)}.  Here,
1447  {\it base} is determined by the following rule: If the name of the  {\it base} is determined by the following rule: If the name of the
1448  tool input file has a suffix that occurs in $l_1$ then {\it base} is  tool input file has a suffix that occurs in $l_1$, then {\it base} is
1449  the name without that suffix.  Otherwise, the whole file name is taken  the name without that suffix.  Otherwise the whole file name is taken
1450  as {\it base} (just like in the case of {\tt Tools.EXTEND}).  As with  as {\it base} (just like in the case of {\tt Tools.EXTEND}).  As with
1451  {\tt Tools.EXTEND}, the second components of the elements of $l_2$ can  {\tt Tools.EXTEND}, the second components of the elements of $l_2$ can
1452  optionally specify the member class name of the corresponding derived  optionally specify the member class name of the corresponding derived
1453  file and the third component maps source options to target options.  file, and the third component maps source options to target options.
1454  \end{enumerate}  \end{enumerate}
1455  \item[dflopts] an optional list of strings which is used for  \item[dflopts] a list of strings which is used for
1456  substituting {\bf \%$n$o} fields in {\tt template} (see above) if no  substituting {\bf \%$n$o} fields in {\tt template} (see above) if no
1457  options were specified.  (Note that the value of {\tt dflopts} is never  options were specified.  (Note that the value of {\tt dflopts} is never
1458  passed to the option mappers in {\tt Tools.EXTEND} or {\tt  passed to the option mappers in {\tt Tools.EXTEND} or {\tt

Legend:
Removed from v.587  
changed lines
  Added in v.588

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