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 527, Tue Jan 18 04:12:54 2000 UTC
+revision 528, Mon Jan 24 05:03:42 2000 UTC
 Line 697
  string that was originally given to the call of {\tt CM.Server.start}
  used to created the server.
+ \subsubsection*{Plug-ins}
+ As an alternative to {\tt CM.make} or {\tt CM.autoload}, where the
+ main purpose is to subsequently be able to access the library from
+ interactively entered code, one can instruct CM to load libraries
+ ``for effect''.
+ \begin{verbatim}
+   val load_plugin : string -> bool
+ \end{verbatim}
+ Function {\tt CM.load\_plugin} acts exactly like {\tt CM.make} except
+ that even in the case of success no new symbols will be bound in the
+ interactive top-level environment.  That means that link-time
+ side-effects will be visible, but none of the exported definitions
+ become available.  This mechanism can be used for ``plug-in'' modules:
+ a core library provides hooks where additional functionality can be
+ registered later via side-effects; extensions to this core are
+ implemented as additional libraries which, when loaded, register
+ themselves with those hooks.  By using {\tt CM.load\_plugin} instead
+ of {\tt CM.make}, one can avoid polluting the interactive top-level
+ environment with spurious exports of the extension module.
+ CM itself uses plug-in modules in its member-class subsystem (see
+ section~\ref{sec:classes}).  This makes it possible to add new classes
+ and tools very easily without having to reconfigure or recompile CM,
+ not to mention modify its source code.
  \subsection{The autoloader}
  \label{sec:autoload}
-Line 1129
+Line 1157
  write:
  \begin{verbatim}
- val command = Tools.newCmdController ("NYACC", "new-ml-yacc")
  val _ = Tools.registerStdShellCmdTool
    { tool = "New-ML-Yacc",
      class = "nmlyacc",
      suffixes = ["ngrm", "ny"],
-     command = command,
+     cmdStdPath = "new-ml-yacc",
-     extensionStyle = Tools.EXTEND ["sig", "sml"],
+     extensionStyle = Tools.EXTEND [("sig", SOME "sml"),
-     sml = true }
+                                    ("sml", SOME "sml")] }
  \end{verbatim}
  This code can either be packaged as a CM library or entered at the
  interactive top level after loading the {\tt cm-tools.cm} library
- (e.g., via {\tt CM.autoload}).
+ (via {\tt CM.make} or {\tt CM.load\_plugin}).
- The call to {\tt Tools.newCmdController} makes a ``command
+ In our example, the shell command name for our tool is {\tt
- controller'' (a value of type {\tt \{ get: unit -> string,
+ new-ml-yacc}.  When looking for this command in the file system, CM
- set: string -> unit \} }). It can be used to query or set the
+ first tries to treat it as a path anchor (see
- command string for the tool.  Here, the default string is {\tt
+ section~\ref{sec:anchors}).  For example, suppose {\tt new-ml-yacc} is
- new-ml-yacc} and can be customized at startup time using the
+ mapped to {\tt /bin}.  In this case the command to be
- environment variable {\tt CM\_NYACC}.
+ invoked would be {\tt /bin/new-ml-yacc}.  If path anchor resolution
+ fails, then the command name will be used as-is.  Normally this
+ causes the shell's path search mechanism to be used as a fallback.
  {\tt Tools.registerStdShellCmdTool} creates the class and installs the
  tool for it.  The arguments must be specified as follows:
-Line 1159
+Line 1188
  upper-case letters
  \item[suffixes] a list of file name suffixes that let CM automatically
  recognize files of the class
- \item[command] the command controller from above
+ \item[cmdStdPath] the command string from above
  \item[extensionStyle] a specification of how the names of files
  generated by the tool relate to the name of the tool input file; \\
  Currently, there are two possible cases:
  \begin{enumerate}
  \item ``{\tt Tools.EXTEND} $l$'' says that if the tool source file is
- {\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
- output file named {\it file}{\tt .}{\it sfx}.
+ will be one tool output file named {\it file}{\tt .}{\it sfx}.
+ The list $l$ consists of pairs where the first component specifies the
+ suffix string and where the second component can be used to
+ (optionally) specify the member class name of the corresponding
+ derived file.
  \item ``{\tt Tools.REPLACE }$(l_1, l_2)$'' specifies that given the
  base name {\it base} there will be one tool output file {\it base}{\tt
- .}{\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,
- 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
- 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
- that suffix.  Otherwise, the whole file name is taken as {\it base}
+ the name without that suffix.  Otherwise, the whole file name is taken
- (just like in the case of {\tt Tools.EXTEND}).
+ as {\it base} (just like in the case of {\tt Tools.EXTEND}).  As with
+ {\tt Tools.EXTEND}, the second components of the elements of $l_2$ can
+ optionally specify the member class name of the corresponding derived
+ file.
  \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.
  \end{description}
  Less common kinds of rules can also be defined using the generic
  interface {\tt Tools.registerClass}.
+ \subsection{Plug-in Tools}
+ If CM comes across a member class name $c$ that it does not know
+ about, then it tries to load a plugin module named $c${\tt -tool.cm}.
+ If it sees a file whose name ends in suffix $s$, for which no member
+ class has been specified, and for which member classification fails,
+ then it tries to load a plugin module named $s${\tt -ext.cm}.  The
+ so-loaded module can then register the required tool which enables CM
+ to successfully deal with the previously unknown member.
+ This mechanism makes it possible for new tools to be added by simply
+ placing appropriately-named plug-in libraries in such a way that CM
+ can find them.
  \section{Parallel and distributed compilation}
  \label{sec:parmake}

 Legend:



Removed from v.527
 


changed lines


 
Added in v.528
 Legend:



Removed from v.527
 


changed lines


 
Added in v.528
-Removed from v.527
+Added in v.528

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