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/10-moretools.tex
ViewVC logotype

Diff of /sml/trunk/src/cm/Doc/10-moretools.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 742, Thu Nov 30 14:09:32 2000 UTC revision 743, Thu Dec 7 15:31:24 2000 UTC
# Line 125  Line 125 
125  \subsection{Adding other classes}  \subsection{Adding other classes}
126    
127  Adding a new class whose behavior is not covered by the mechanism  Adding a new class whose behavior is not covered by the mechanism
128  described in section~\ref{sec:addshellclass} is also not complicated,  described in section~\ref{sec:addshellclass} is not complicated
129  but it requires a bit more code.  either, but it requires a bit more code.
130    
131  \subsubsection{Adding a class and its rule}  \subsubsection{Adding a class and its rule}
132    
# Line 137  Line 137 
137    val registerClass : class * rule -> unit    val registerClass : class * rule -> unit
138  \end{verbatim}  \end{verbatim}
139    
140  Here, the type {\tt class} is simply synonymous to {\tt string}; a  Here, type {\tt class} is simply synonymous to {\tt string}; a class
141  class string is the name of the class to be registered.  It may not  string is the name of the class to be registered.  It must not contain
142  contain upper-case letters:  upper-case letters:
143    
144  \begin{verbatim}  \begin{verbatim}
145    type class = string    type class = string
146  \end{verbatim}  \end{verbatim}
147    
148  Type {\tt rule} is a function type.  It describes the rule function  Type {\tt rule} is a function type.  It describes the rule function
149  that CM will invoke for every member of the new class.  In essence,  that CM will invoke for every member of the new class. The rule
150  this function maps the {\em specification} of the given member to its  function is responsible for invoking the auxiliary mechanism necessary
151  (partial) {\em expansion}:  to bring its targets up-to-date.  The function result of the rule
152    function describes to CM what the targets are.  Thus, the function
153    maps the {\em specification} of the given member to its (partial) {\em
154    expansion}:
155    
156  \begin{verbatim}  \begin{verbatim}
157    type rule =    type rule =
158      { spec: spec,      { spec: spec, mkNativePath: pathmaker, context: rulecontext } ->
       mkNativePath: pathmaker,  
       context: rulecontext } ->  
159      partial_expansion      partial_expansion
160  \end{verbatim}  \end{verbatim}
161    
162  The specification {\tt spec} is the name of the member together with a  The specification {\tt spec} consists of the name of the member
163  function to convert the name to an abstract path, the member's  together with a function to convert it to an abstract path (should
164  optional class (in case it had been given explicitly), its tool  that be necessary), the member's optional class (in case it had been
165  options, and a boolean flag that tells whether this member was the  given explicitly), its tool options, and a boolean flag that tells
166  result of another tool:  whether this member was the result of another tool:
167    
168  \begin{verbatim}  \begin{verbatim}
169    type spec = { name: string,    type spec = { name: string,
# Line 175  Line 176 
176  \begin{description}  \begin{description}
177  \item[name:] The name is the verbatim member string from the  \item[name:] The name is the verbatim member string from the
178  description file.  Be sure not to use this string directly as a file  description file.  Be sure not to use this string directly as a file
179  name.  Instead, first convert it to an abstract path (see {\tt mkpath}  name (although some tools might use it directly for purposes other
180  below) and convert back to a {\em native} file name string using one  than file names).  Instead, first convert it to an abstract path (see
181  of:  {\tt mkpath} below) and convert back to a {\em native} file name
182    string using one of:
183  \begin{verbatim}  \begin{verbatim}
184    val nativeSpec : srcpath -> string    val nativeSpec : srcpath -> string
185    val nativePre : presrcpath -> string    val nativePre : presrcpath -> string
186  \end{verbatim}  \end{verbatim}
187  \item[mkpath] This is a function that converts the name string to an  \item[mkpath] This is a function of type {\tt pathmaker} that converts
188  abstract path name.  (The same string can denote different paths  the name string to an abstract path name.  CM will pass in different
189  depending on whether it was specified using CM's standard path name  functions here depending on whether {\tt name} was given in CM's
190  syntax or the underlying operating system's native syntax.)  standard path name syntax or in the underlying operating system's
191    native syntax.
192  \begin{verbatim}  \begin{verbatim}
193    type pathmaker = string -> presrcpath    type pathmaker = string -> presrcpath
194  \end{verbatim}  \end{verbatim}
# Line 200  Line 203 
203  in every such name (i.e., that it cannot be just an anchor).  in every such name (i.e., that it cannot be just an anchor).
204  \item[class:] This argument carries the class name if such a class  \item[class:] This argument carries the class name if such a class
205  name was explicitly specified.  If the class was inferred from the  name was explicitly specified.  If the class was inferred from the
206  member name, then this argument is {\tt NONE}.  member name, then it will be set to {\tt NONE}.
207  \item[opts:] Tool options are represented by a data structure  \item[opts:] Tool options are represented by a data structure
208  resembling Lisp lists:  resembling Lisp lists:
209  \begin{verbatim}  \begin{verbatim}
# Line 209  Line 212 
212      | SUBOPTS of { name: string, opts: toolopts }      | SUBOPTS of { name: string, opts: toolopts }
213    withtype toolopts = toolopt list    withtype toolopts = toolopt list
214  \end{verbatim}  \end{verbatim}
215    The nesting of {\tt SUBOPTS} reflects the nesting of sub-option lists
216    in the member's tool option specification.
217  \item[derived:] This flag is set to {\tt true} if the source file  \item[derived:] This flag is set to {\tt true} if the source file
218  represented by the specification is the result of a another, earlier  represented by the specification is the result of a another, earlier
219  tool invocation.  tool invocation.
220  \end{description}  \end{description}
221    
222  The other two arguments ({\tt mkNativePath} and {\tt context}) of a  The other two arguments of a rule function are {\tt mkNativePath} and
223  rule function are:  {\tt context}:
224    
225  \begin{description}  \begin{description}
226  \item[mkNativePath:] This is a function like {\tt mkpath} above.  When  \item[mkNativePath:] This is a function of the same type as {\tt
227  the rule constructs the specification for result files, it must also  mkpath} above.  When the rule constructs the specifications for its
228  provide the corresponding {\tt mkpath} function.  Since most tools  result files, it must provide the corresponding {\tt mkpath} function
229  internally operate on native path names (for example, because they  for those.  Since most tools internally operate on native path names
230  pass these names to other, external programs), this {\tt mkpath}  (for example, because they pass these names to other, external
231  function will have to be {\tt mkNativePath}.  programs), this {\tt mkpath} function will have to be {\tt
232  \item[context:] The context represents the directory that contains the  mkNativePath}.
233  CM description file on whose behalf the rule was invoked.  It is  \item[context:] The context argument of a rule represents the
234  represented as a higher-order function that invokes its function  directory that contains the CM description file on whose behalf the
235  argument after temporarily setting the working directory to the  rule was invoked.  It is represented as a higher-order function that
236  context directory and returns the result of this function invocation  invokes its function argument after temporarily setting the working
237  after restoring the original working directory.  Not all rules  directory to the context directory and returns the result of this
238  require such a temporary change of directories, but those that do  invocation after restoring the original working directory.  Not all
239  should encapsulate all their work into a local function and then pass  rules require such a temporary change of directories, but those that
240  this function to the context.  do should encapsulate all their work into a local function and then
241    pass this function to the context.
242  \begin{verbatim}  \begin{verbatim}
243    type rulefn = unit -> partial_expansion    type rulefn = unit -> partial_expansion
244    type rulecontext = rulefn -> partial_expansion    type rulecontext = rulefn -> partial_expansion
# Line 260  Line 266 
266  Most rules (except those for classes {\tt sml} and {\tt cm}) leave the  Most rules (except those for classes {\tt sml} and {\tt cm}) leave the
267  lists {\tt smlfiles} and {\tt cmfiles} empty.  A tool that produces an  lists {\tt smlfiles} and {\tt cmfiles} empty.  A tool that produces an
268  ML source file or a CM description file as output should put a  ML source file or a CM description file as output should put a
269  specification for it into the specification list of a partial  specification for this file into the specification list of a partial
270  expansion and let the rules for {\tt sml} and {\tt cm} take care of  expansion, letting the rules for classes {\tt sml} and {\tt cm} take
271  the rest.  At this point we will therefore not dwell on explanations  care of the rest.  At this point we will therefore not dwell on
272  for the types of these two values.  explanations for the types of these two fields.
273    
274  The {\tt sources} list is used to implement {\tt CM.sources} (see  The {\tt sources} field is used to implement {\tt CM.sources} (see
275  section~\ref{sec:makedepend:support}).  Therefore, the rule should  section~\ref{sec:makedepend:support}).  Therefore, the rule should
276  include here every file that it consumes and that its implementer  include here every file that it consumes if its implementer wishes to
277  wishes to be reported by {\tt CM.sources}. However, do not include  have it reported by {\tt CM.sources}.  (Do not include source files
278  source files that are {\em produced} by the rule because those will be  that are {\em produced} by the rule because those will be reported by
279  reported by subsequent rules.  subsequent rules.)
280    
281    \subsubsection{Reporting errors from tools}
282    
283  When a rule encounters an error, it should raise the following  When a rule encounters an error, it should raise the following
284  exception, setting {\tt tool} to a string describing the current tool  exception, setting {\tt tool} to a string describing the current tool
# Line 284  Line 292 
292  \subsubsection{Adding a classifier}  \subsubsection{Adding a classifier}
293    
294  A classifier is a mechanism that enables CM to infer a member's class  A classifier is a mechanism that enables CM to infer a member's class
295  form its name.  CM supports two kinds of classifiers: suffix  form its name.  Classifiers are invoked if no explicit class was
296  classifiers and general classifiers.  given.  CM supports two kinds of classifiers: suffix classifiers and
297    general classifiers.
298    
299  \begin{verbatim}  \begin{verbatim}
300    datatype classifier =    datatype classifier =
# Line 294  Line 303 
303  \end{verbatim}  \end{verbatim}
304    
305  Most of the time, classifiers look at the file name suffix as the only  Most of the time, classifiers look at the file name suffix as the only
306  clue.  This is captured by {\tt SFX\_CLASSIFIER} which carries a  clue.  This idea is captured by {\tt SFX\_CLASSIFIER} which carries a
307  partial function from suffixes to class names.  The function should  partial function from suffixes to class names.  The function should
308  return {\tt NONE} if it does not know about the given argument suffix.  return {\tt NONE} if it does not know about the given argument suffix.
309    
310  The {\tt GEN\_CLASSIFIER} carries a similar function---the only  The {\tt GEN\_CLASSIFIER} constructor carries a similar function---the
311  difference being that the entire member name is passed to it.  (Suffix  only difference being that the entire member name is passed to it.
312  classifiers could be implemented as general classifiers, but using  (Suffix classifiers could be implemented as general classifiers, but
313  {\tt SFX\_CLASSIFIER} for them is slightly more efficient.)  using {\tt SFX\_CLASSIFIER} for them is slightly more efficient
314    because CM will extract the suffix from the name only once.)
315    
316  Function {\tt Tools.stdSfxClassifier} is a simple wrapper around {\tt  Function {\tt Tools.stdSfxClassifier} is a simple wrapper around {\tt
317  SFX\_CLASSIFIER} and produces a classifier that looks for precisely  SFX\_CLASSIFIER} and produces a classifier that looks for precisely
# Line 338  Line 348 
348    
349  These values can not only be passed to {\tt  These values can not only be passed to {\tt
350  Tools.registerStdShellCmdTool} but also be used to let CM perform name  Tools.registerStdShellCmdTool} but also be used to let CM perform name
351  extension directly.  This is done by invoking function {\tt  extension directly.  To do so, one must invoke function {\tt
352  Tools.extend}:  Tools.extend}:
353    
354  \begin{verbatim}  \begin{verbatim}
# Line 354  Line 364 
364    val outdated : string -> string list * string -> bool    val outdated : string -> string list * string -> bool
365  \end{verbatim}  \end{verbatim}
366    
367  Here, the first (curried) argument is the name of the tool, the string  In a call {\tt (Tools.outdated $t$ ($l$, $s$))}, $t$ is the name of
368  list is the list of targets (as native file names), and other string  the tool, $l$ is the list of targets (as native file names), and $s$
369  is the source (also as a native file name).  is the source (also as a native file name).
370    
371  An alternative way of checking for outdated sources (in the style of  An alternative way of checking for outdated sources (in the style of
# Line 382  Line 392 
392    val openTextOut : string -> TextIO.outstream    val openTextOut : string -> TextIO.outstream
393  \end{verbatim}  \end{verbatim}
394    
395  To create the directories without opening the file (and without even  To create the same directories without opening the file (and without
396  creating it if it does not exist), one can use function {\tt  even creating it if it does not exist), use function {\tt
397  Tools.makeDirs}:  Tools.makeDirs}:
398    
399  \begin{verbatim}  \begin{verbatim}
# Line 394  Line 404 
404  file!  file!
405    
406  \noindent{\bf Option processing:}  For simple tools, the following  \noindent{\bf Option processing:}  For simple tools, the following
407  function for ``parsing'' tool options can come in handy:  function for ``parsing'' tool options can be useful:
408    
409  \begin{verbatim}  \begin{verbatim}
410    val parseOptions :    val parseOptions :
# Line 404  Line 414 
414    
415  Given a list of accepted keywords, this function scans the tool  Given a list of accepted keywords, this function scans the tool
416  options and collects occurrences of sub-option lists labelled by one  options and collects occurrences of sub-option lists labelled by one
417  of these keywords.  Any sub-option list that that is not recognized  of these keywords.  Any sub-option list that is not recognized and any
418  and any keyword that occurs more than once will be rejected with an  keyword that occurs more than once will be rejected as an error.  The
419  error.  The result consists of a function {\tt matches} that can be  result consists of a function {\tt matches} that can be uses to query
420  uses to query each of the keywords and a list of simple rest options.  each of the keywords.  The function also collects and returns all the
421    {\tt STRING} options.
422  \noindent{\bf Issuing diagnostics:}  Functions {\tt Tools.say} and  
423  {\tt Tools.vsay} both take a list of strings and output the  \noindent{\bf Issuing diagnostics:} Functions {\tt Tools.say} and {\tt
424  concatenation of these strings to {\tt TextIO.stdOut}.  The difference  Tools.vsay} both take a list of strings and output the concatenation
425  between {\tt say} and {\tt vsay} is that the former works  of these strings to the compiler's standard control output stream
426  unconditionally while the latter is controlled by {\tt  (i.e., usually {\tt TextIO.stdOut}).  The difference between {\tt say}
427  CM.Control.verbose} (see section~\ref{sec:registers}).  and {\tt vsay} is that the former works unconditionally while the
428    latter is controlled by {\tt CM.Control.verbose} (see
429    section~\ref{sec:registers}).
430    
431  \noindent{\bf Anchor-configurable strings:} Mainly for the purpose of  \noindent{\bf Anchor-configurable strings:} Mainly for the purpose of
432  implementing anchor-configurable names for auxiliary shell commands  implementing anchor-configurable names for auxiliary shell commands
# Line 428  Line 440 
440  returns $d${\tt /}$m$; otherwise it returns $m$.  returns $d${\tt /}$m$; otherwise it returns $m$.
441    
442  \noindent{\bf Querying the default class of a member:} One can  \noindent{\bf Querying the default class of a member:} One can
443  directly invoke CM's internal classification mechanism using {\tt  directly invoke CM's internal classification mechanism, taking
444  Tools.defaultClassOf}:  advantage of any registered classifiers:
445    
446  \begin{verbatim}  \begin{verbatim}
447    val defaultClassOf : string -> class option    val defaultClassOf : string -> class option
# Line 438  Line 450 
450  \subsection{Plug-in Tools}  \subsection{Plug-in Tools}
451  \label{sec:plugintools}  \label{sec:plugintools}
452    
453  \subsubsection{Automatically-loaded, global plug-in tools}  \subsubsection{Automatically loaded, global plug-in tools}
454    
455  If CM comes across a member class name $c$ that it does not know  If CM encounters a member class name $c$ that it does not know about,
456  about, then it tries to load a plugin module named {\tt \$/}$c${\tt  then it tries to load a plugin module named {\tt \$/}$c${\tt
457  -tool.cm}.  If it sees a file whose name ends in suffix $s$ for which  -tool.cm}.  If it sees a file whose name ends in suffix $s$ for which
458  no explicit member class has been specified in the CM description file  no explicit member class has been specified in the CM description file
459  and for which automatic member classification fails, then it tries to  and for which automatic member classification fails, it will try to
460  load a plugin module named {\tt \$/}$s${\tt -ext.cm}.  The so-loaded  load a plugin module named {\tt \$/}$s${\tt -ext.cm}.  The so-loaded
461  module can then register the required tool which enables CM to  module can then register the required tool, thereby enabling CM to
462  successfully deal with the previously unknown member.  successfully deal with the previously unknown member.
463    
464  This mechanism makes it possible for new tools to be added by simply  This mechanism makes it possible for new tools to be added by simply
465  placing appropriately-named plug-in libraries in some convenient place  placing appropriately named plug-in libraries in some convenient place
466  and making the corresponding adjustments to the anchor environment.  and making the corresponding adjustments to the anchor environment.
467  In other words, description files {\tt \$/}$c${\tt -tool.cm} and {\tt  In other words, description files {\tt \$/}$c${\tt -tool.cm} and {\tt
468  \$/}$s${\tt -ext.cm} that correspond to general-purpose tools should  \$/}$s${\tt -ext.cm} that correspond to general-purpose tools should
469  be registered using the path anchor mechanism.  If this is done,  be registered by modifying either the global or the local path
470  actual description files for the tools' implementations can be placed  configuration file (or by directly invoking functon {\tt
471  in arbitrary locations.  CM.Anchor.anchor}; see section~\ref{sec:api:anchors}).  If this is
472    done, actual description files for the tools' implementations can be
473    placed in arbitrary locations.
474    
475  \subsubsection{Explicitly-loaded, local plug-in tools}  \subsubsection{Explicitly loaded, local plug-in tools}
476  \label{sec:localtools}  \label{sec:localtools}
477    
478  Some projects might want to use their own special-purpose tools for  Some projects might want to use their own special-purpose tools for
# Line 493  Line 507 
507  tool} lasts until the end of the current description file and is  tool} lasts until the end of the current description file and is
508  restricted to that file.  This means that other description files that  restricted to that file.  This means that other description files that
509  also want to use class {\tt bar} will have to have their own {\tt  also want to use class {\tt bar} will have to have their own {\tt
510  tool} entry.  tool} entry.\footnote{Note that CM cannot enforce that the tool
511    library actually register a class or a classifier.  Any side-effects
512    other than registering classes or classifiers are beyond CM's control
513    and will not be undone once processing the current description file is
514    complete.}
515    
516  Local tool classes and suffixes temporarily override any equally-named  Local tool classes and suffixes temporarily override any equally-named
517  global classes or suffixes, respectively.  global classes or suffixes, respectively.
# Line 502  Line 520 
520  \label{sec:localsuffixes}  \label{sec:localsuffixes}
521    
522  It is sometimes convenient to locally add another recognized filename  It is sometimes convenient to locally add another recognized filename
523  suffix to an already registered class.  This is done by using the  suffix to an already registered class.  This is the purpose of the
524  special tool class {\tt suffix}.  For example, a programmer who has  special tool class {\tt suffix}.  For example, a programmer who has
525  named all her ML files in such a way that they end in {\tt .ml}  named all ML files in such a way that file names end in {\tt .ml}
526  could write near the beginning of her description file:  could write near the beginning of the description file:
527    
528  \begin{verbatim}  \begin{verbatim}
529      ml : suffix (sml)      ml : suffix (sml)
530  \end{verbatim}  \end{verbatim}
531    
532  For the remainder of the current description file, all such {\tt  For the remainder of the current description file, all such {\tt
533  .ml}-files will now be classified under {\tt sml}.  .ml}-files will now be treated as members of class {\tt sml}.

Legend:
Removed from v.742  
changed lines
  Added in v.743

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