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 507, Fri Dec 10 09:18:23 1999 UTC revision 528, Mon Jan 24 05:03:42 2000 UTC
# Line 697  Line 697 
697  string that was originally given to the call of {\tt CM.Server.start}  string that was originally given to the call of {\tt CM.Server.start}
698  used to created the server.  used to created the server.
699    
700    \subsubsection*{Plug-ins}
701    
702    As an alternative to {\tt CM.make} or {\tt CM.autoload}, where the
703    main purpose is to subsequently be able to access the library from
704    interactively entered code, one can instruct CM to load libraries
705    ``for effect''.
706    
707    \begin{verbatim}
708      val load_plugin : string -> bool
709    \end{verbatim}
710    
711    Function {\tt CM.load\_plugin} acts exactly like {\tt CM.make} except
712    that even in the case of success no new symbols will be bound in the
713    interactive top-level environment.  That means that link-time
714    side-effects will be visible, but none of the exported definitions
715    become available.  This mechanism can be used for ``plug-in'' modules:
716    a core library provides hooks where additional functionality can be
717    registered later via side-effects; extensions to this core are
718    implemented as additional libraries which, when loaded, register
719    themselves with those hooks.  By using {\tt CM.load\_plugin} instead
720    of {\tt CM.make}, one can avoid polluting the interactive top-level
721    environment with spurious exports of the extension module.
722    
723    CM itself uses plug-in modules in its member-class subsystem (see
724    section~\ref{sec:classes}).  This makes it possible to add new classes
725    and tools very easily without having to reconfigure or recompile CM,
726    not to mention modify its source code.
727    
728  \subsection{The autoloader}  \subsection{The autoloader}
729  \label{sec:autoload}  \label{sec:autoload}
730    
# Line 1129  Line 1157 
1157  write:  write:
1158    
1159  \begin{verbatim}  \begin{verbatim}
 val command = Tools.newCmdController ("NYACC", "new-ml-yacc")  
1160  val _ = Tools.registerStdShellCmdTool  val _ = Tools.registerStdShellCmdTool
1161    { tool = "New-ML-Yacc",    { tool = "New-ML-Yacc",
1162      class = "nmlyacc",      class = "nmlyacc",
1163      suffixes = ["ngrm", "ny"],      suffixes = ["ngrm", "ny"],
1164      command = command,      cmdStdPath = "new-ml-yacc",
1165      extensionStyle = Tools.EXTEND ["sig", "sml"],      extensionStyle = Tools.EXTEND [("sig", SOME "sml"),
1166      sml = true }                                     ("sml", SOME "sml")] }
1167  \end{verbatim}  \end{verbatim}
1168    
1169  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
1170  interactive top level after loading the {\tt cm-tools.cm} library  interactive top level after loading the {\tt cm-tools.cm} library
1171  (e.g., via {\tt CM.autoload}).  (via {\tt CM.make} or {\tt CM.load\_plugin}).
1172    
1173  The call to {\tt Tools.newCmdController} makes a ``command  In our example, the shell command name for our tool is {\tt
1174  controller'' (a value of type {\tt \{ get: unit -> string,  new-ml-yacc}.  When looking for this command in the file system, CM
1175  set: string -> unit \} }). It can be used to query or set the  first tries to treat it as a path anchor (see
1176  command string for the tool.  Here, the default string is {\tt  section~\ref{sec:anchors}).  For example, suppose {\tt new-ml-yacc} is
1177  new-ml-yacc} and can be customized at startup time using the  mapped to {\tt /bin}.  In this case the command to be
1178  environment variable {\tt CM\_NYACC}.  invoked would be {\tt /bin/new-ml-yacc}.  If path anchor resolution
1179    fails, then the command name will be used as-is.  Normally this
1180    causes the shell's path search mechanism to be used as a fallback.
1181    
1182  {\tt Tools.registerStdShellCmdTool} creates the class and installs the  {\tt Tools.registerStdShellCmdTool} creates the class and installs the
1183  tool for it.  The arguments must be specified as follows:  tool for it.  The arguments must be specified as follows:
# Line 1159  Line 1188 
1188  upper-case letters  upper-case letters
1189  \item[suffixes] a list of file name suffixes that let CM automatically  \item[suffixes] a list of file name suffixes that let CM automatically
1190  recognize files of the class  recognize files of the class
1191  \item[command] the command controller from above  \item[cmdStdPath] the command string from above
1192  \item[extensionStyle] a specification of how the names of files  \item[extensionStyle] a specification of how the names of files
1193  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; \\
1194  Currently, there are two possible cases:  Currently, there are two possible cases:
1195  \begin{enumerate}  \begin{enumerate}
1196  \item ``{\tt Tools.EXTEND} $l$'' says that if the tool source file is  \item ``{\tt Tools.EXTEND} $l$'' says that if the tool source file is
1197  {\it file} then for each suffix {\it sfx} in $l$ there will be one tool  {\it file} then for each suffix {\it sfx} in {\tt (map \#1 $l$)} there
1198  output file named {\it file}{\tt .}{\it sfx}.  will be one tool output file named {\it file}{\tt .}{\it sfx}.
1199    The list $l$ consists of pairs where the first component specifies the
1200    suffix string and where the second component can be used to
1201    (optionally) specify the member class name of the corresponding
1202    derived file.
1203  \item ``{\tt Tools.REPLACE }$(l_1, l_2)$'' specifies that given the  \item ``{\tt Tools.REPLACE }$(l_1, l_2)$'' specifies that given the
1204  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
1205  .}{\it sfx} for each suffix {\it sfx} in $l_2$.  Here, {\it base} is  .}{\it sfx} for each suffix {\it sfx} in {\tt (map \#1 $l_2$)}.  Here,
1206  determined by the following rule:  If the name of the tool input file  {\it base} is determined by the following rule: If the name of the
1207  has a suffix that occurs in $l_1$ then {\it base} is the name without  tool input file has a suffix that occurs in $l_1$ then {\it base} is
1208  that suffix.  Otherwise, the whole file name is taken as {\it base}  the name without that suffix.  Otherwise, the whole file name is taken
1209  (just like in the case of {\tt Tools.EXTEND}).  as {\it base} (just like in the case of {\tt Tools.EXTEND}).  As with
1210    {\tt Tools.EXTEND}, the second components of the elements of $l_2$ can
1211    optionally specify the member class name of the corresponding derived
1212    file.
1213  \end{enumerate}  \end{enumerate}
 \item[sml] a boolean flag that indicates whether or not the tool  
 output is always to be considered ML source code; \\  
 If the flag is set to {\tt false}, then CM will take the names of the  
 output files and apply its usual classification mechanism---possibly  
 resulting in cascaded tool application.  
1214  \end{description}  \end{description}
1215    
1216  Less common kinds of rules can also be defined using the generic  Less common kinds of rules can also be defined using the generic
1217  interface {\tt Tools.registerClass}.  interface {\tt Tools.registerClass}.
1218    
1219    \subsection{Plug-in Tools}
1220    
1221    If CM comes across a member class name $c$ that it does not know
1222    about, then it tries to load a plugin module named $c${\tt -tool.cm}.
1223    If it sees a file whose name ends in suffix $s$, for which no member
1224    class has been specified, and for which member classification fails,
1225    then it tries to load a plugin module named $s${\tt -ext.cm}.  The
1226    so-loaded module can then register the required tool which enables CM
1227    to successfully deal with the previously unknown member.
1228    
1229    This mechanism makes it possible for new tools to be added by simply
1230    placing appropriately-named plug-in libraries in such a way that CM
1231    can find them.
1232    
1233  \section{Parallel and distributed compilation}  \section{Parallel and distributed compilation}
1234  \label{sec:parmake}  \label{sec:parmake}
1235    

Legend:
Removed from v.507  
changed lines
  Added in v.528

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