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 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

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