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
 [smlnj] / sml / trunk / src / cm / Doc / manual.tex

# Diff of /sml/trunk/src/cm/Doc/manual.tex

revision 672, Mon Jun 19 04:40:29 2000 UTC revision 673, Wed Jun 21 08:57:07 2000 UTC
# Line 358  Line 358
358  \$/}$p$. \$/}$p$.
359  \end{description}  \end{description}
360
361    \subsection{Anchor environments}
362    \label{sec:anchor:env}
363
364    Anchor names are resolved in the {\em anchor environment} that is in
365    effect at the time the anchor is read.
366
367    The basis for all anchor environments is the {\em root environment}.
368    Conceptually, the root environments is a fixed mapping that binds
369    every possible anchor to a mutable location.  The location can store a
370    native directory name or can be marked undefined''.  Most locations
371    initially start out undefined.  The contents of each location is
372    configurable (see Section~\ref{sec:anchor:config}).
373
374    At the time a CM description file $a${\tt .cm} refers to another
375    library's or library component's description file $b${\tt .cm}, it can
376    augment the current anchor environment with new bindings.  The new
377    bindings are in effect while $b${\tt .cm} (including any description
378    files {\it it}\/ mentions!) is being processed.  If a new binding
379    binds an anchor name that was already bound in the current
380    environment\footnote{which is technically always the case given our
381    explanation of the root environment}, then the old binding is being
382    hidden.  The effect is scoping for anchor names.
383
384    Using CM's {\em tool parameter} mechanism (see
385    Section~\ref{sec:toolparam}), a new binding is specified as a pair of
386    anchor name and anchor value.  The value has the form of another path
387    name (standard or native). Example:
388
389    \begin{verbatim}
390      a.cm (bind:(anchor:lib value:$mystuff/a-lib) 391 bind:(anchor:support value:$lib)
392            bind:(anchor:utils value:/home/bob/stuff/ML/utils))
393    \end{verbatim}
394
395    As shown in this example, it is perfectly legal for the specification
396    of the value to involve the use of another anchor.  That anchor will
397    be resolved in the original anchor environment. Thus, a path anchored
398    at {\tt \$lib} in {\tt a.cm} will be resolved using the binding for 399 {\tt \$mystuff} that is currently in effect.  The point here is that a
400    re-configuration of the root environment that affects {\tt \$mystuff} 401 now also affects how {\tt \$lib} is resolved as it occurs within {\tt
402    a.cm}.
403
404    The list of {\tt bind:}-directives is processed in parallel,'' which
405    means that {\tt \$support} is {\em not} being bound to\linebreak {\tt 406 \$mystuff/a-lib/asupport} but will refer to the original meaning of
407    {\tt \$lib}. 408 409 The example also demonstrates that {\tt value:}-paths can be single 410 anchors. In other words, the restriction that there has to be at least 411 one arc after the anchor does not apply here. 412 413 \subsection{Anchor configuration} \subsection{Anchor configuration} 414 \label{sec:anchors} \label{sec:anchor:config} 415 416 The association of path name anchors with their corresponding Anchor configuration is concerned with the values that are stored in 417 directory names is a simple one-way mapping. At startup time, this the root anchor environment. At startup time, the root environment is 418 mapping is initialized by reading two configuration files: an initialized by reading two configuration files: an 419 installation-specific one and a user-specific one. After that, the installation-specific one and a user-specific one. After that, the 420 mapping can be maintained using CM's interface functions {\tt contents of root locations can be maintained using CM's interface 421 CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see functions {\tt CM.Anchor.anchor} and {\tt CM.Anchor.reset} (see 422 Section~\ref{sec:api}). Section~\ref{sec:api}). 423 424 The default location of the installation-specific configuration file The default location of the installation-specific configuration file # Line 591 Line 643 643 then it will be expanded by prepending the name of the current working then it will be expanded by prepending the name of the current working 644 directory. directory. 645 646 {\tt CM.Anchor.reset} erases the entire existing path configuration {\tt CM.Anchor.reset} erases the entire existing path configuration. 647 mapping. After a call of this function has completed, all root environment 648 locations are marked as being undefined''. 649 650 \subsubsection*{Setting CM variables} \subsubsection*{Setting CM variables} 651 # Line 926 Line 979 979 loop. loop. 980 981 As far as sharing is concerned, the rule is that during one traversal As far as sharing is concerned, the rule is that during one traversal 982 each compilation unit will be executed at most once. In other words, each compilation unit will be executed at most once. This means that 983 the same program'' will not see multiple instantiations of the same the same program'' will not see multiple instantiations of the same 984 compilation unit (where program'' refers to the code managed by one compilation unit (where program'' refers to the code managed by one 985 call to {\tt CM.make} or {\tt CM.autoload}). Each compilation unit call to {\tt CM.make} or {\tt CM.autoload}). Each compilation unit # Line 941 Line 994 994 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 995 private} or {\em shared}. This is done by adding a {\em tool private} or {\em shared}. This is done by adding a {\em tool 996 parameter} specification for the file in the library- or group parameter} specification for the file in the library- or group 997 description file (see Section~\ref{sec:classes}). In other words, to description file (see Section~\ref{sec:classes}). To mark an ML file 998 mark an ML file as {\em private}, follow the file name with the word as {\em private}, follow the file name with the word {\tt private} in 999 {\tt private} in parentheses. For {\em shared} ML files, replace {\tt parentheses. For {\em shared} ML files, replace {\tt private} with 1000 private} with {\tt shared}. {\tt shared}. 1001 1002 An ML source file that is not annotated will typically be treated as An ML source file that is not annotated will typically be treated as 1003 {\em shared} unless it statically depends on some other {\em private} {\em shared} unless it statically depends on some other {\em private} # Line 1083 Line 1136 1136 means that dynamic state cannot be shared across such calls to {\tt means that dynamic state cannot be shared across such calls to {\tt 1137 CM.make} or {\tt CM.autoload}. CM.make} or {\tt CM.autoload}. 1138 1139 The {\tt cm} class accepts one named parameter, labelled by the string The {\tt cm} class understands two kinds of parameters. The first is 1140 {\tt version}. The parameter itself must have the format of a version a named parameter labeled by the string {\tt version}. It must have 1141 number. CM will interpret this as a version request, thereby insuring the format of a version number. CM will interpret this as a version 1142 that the imported library is not too old or too new. (See request, thereby insuring that the imported library is not too old or 1143 section~\ref{sec:versions} for more on this topic.) too new. (See section~\ref{sec:versions} for more on this topic.) 1144 1145 Named sub-option lists are specified by a name string followed by a All named sub-option lists (for any class) are specified by a name 1146 colon {\bf :} and a parenthesized list of other tool options. If the string followed by a colon {\bf :} and a parenthesized list of other 1147 list contains precisely one element, the parentheses may be omitted. tool options. If the list contains precisely one element, the 1148 Example: parentheses may be omitted. Example: 1149 1150 \begin{verbatim} \begin{verbatim} 1151 euler.cm (version:2.71828) euler.cm (version:2.71828) # Line 1113 Line 1166 1166 warnings or errors. (See the discussion of {\tt CM.unshare} in warnings or errors. (See the discussion of {\tt CM.unshare} in 1167 section~\ref{sec:libreg} for how to to circumvent this restriction.) section~\ref{sec:libreg} for how to to circumvent this restriction.) 1168 1169 The second kind of parameter understood by {\tt cm} is a named 1170 parameter labeled by the string {\tt bind} (see 1171 Section~\ref{sec:anchor:env}). It can occur arbitrarily many times 1172 and each occurence must be a suboption-list of the form {\tt 1173 (anchor:$a$value:$v$)}. The set of {\tt bind}-parameters augments 1174 the current anchor environment to form the environment that is used 1175 while processing the contents of the named CM description file. 1176 1177 \subsection{Built-in tools} \subsection{Built-in tools} 1178 \label{sec:builtin-tools} \label{sec:builtin-tools} 1179 # Line 1131 Line 1192 1192 The tool invokes the {\tt ml-yacc} command if the targets are The tool invokes the {\tt ml-yacc} command if the targets are 1193 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 1194 source. Unless anchored using the path anchor mechanism (see source. Unless anchored using the path anchor mechanism (see 1195 Section~\ref{sec:anchors}), the command {\tt ml-yacc} will be located Section~\ref{sec:anchor:env}), the command {\tt ml-yacc} will be located 1196 using the operating system's path search mechanism (e.g., the {\tt using the operating system's path search mechanism (e.g., the {\tt 1197 \$PATH} environment variable).  \$PATH} environment variable). 1198 # Line 1146 Line 1207 1207 1208 The tool invokes the {\tt ml-lex} command if the target is outdated The tool invokes the {\tt ml-lex} command if the target is outdated 1209 (just like in the case of ML-Yacc). Unless anchored using the path (just like in the case of ML-Yacc). Unless anchored using the path 1210 anchor mechanism (see Section~\ref{sec:anchors}), the command {\tt anchor mechanism (see Section~\ref{sec:anchor:env}), the command {\tt 1211 ml-lex} will be located using the operating system's path search ml-lex} will be located using the operating system's path search 1212 mechanism (e.g., the {\tt \$PATH} environment variable).  mechanism (e.g., the {\tt \$PATH} environment variable). 1213 # Line 1161 Line 1222 1222 1223 The tool invokes the {\tt ml-burg} command if the target is outdated. The tool invokes the {\tt ml-burg} command if the target is outdated. 1224 Unless anchored using the path anchor mechanism (see Unless anchored using the path anchor mechanism (see 1225 Section~\ref{sec:anchors}), the command {\tt ml-lex} will be located Section~\ref{sec:anchor:env}), the command {\tt ml-lex} will be located 1226 using the operating system's path search mechanism (e.g., the {\tt using the operating system's path search mechanism (e.g., the {\tt 1227 \$PATH} environment variable).  \$PATH} environment variable). 1228 # Line 1245 Line 1306 1306 {\tt class} and {\tt options} keyword parameters. {\tt class} and {\tt options} keyword parameters. 1307 1308 The tool invokes the shell command {\tt make} on the target. Unless The tool invokes the shell command {\tt make} on the target. Unless 1309 anchored using the path anchor mechanism~\ref{sec:anchors}, the anchored using the path anchor mechanism~\ref{sec:anchor:env}, the 1310 command will be located using the operating system's path search command will be located using the operating system's path search 1311 mechanism (e.g., the {\tt \$PATH} environment variable).  mechanism (e.g., the {\tt \\$PATH} environment variable).
1312
# Line 1650  Line 1711
1711  In our example, the shell command name for our tool is {\tt  In our example, the shell command name for our tool is {\tt
1712  new-ml-yacc}.  When looking for this command in the file system, CM  new-ml-yacc}.  When looking for this command in the file system, CM
1713  first tries to treat it as a path anchor (see  first tries to treat it as a path anchor (see
1714  section~\ref{sec:anchors}).  For example, suppose {\tt new-ml-yacc} is  section~\ref{sec:anchor:env}).  For example, suppose {\tt new-ml-yacc} is
1715  mapped to {\tt /bin}.  In this case the command to be  mapped to {\tt /bin}.  In this case the command to be
1716  invoked would be {\tt /bin/new-ml-yacc}.  If path anchor resolution  invoked would be {\tt /bin/new-ml-yacc}.  If path anchor resolution
1717  fails, then the command name will be used as-is.  Normally this  fails, then the command name will be used as-is.  Normally this

Legend:
 Removed from v.672 changed lines Added in v.673