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 691, Tue Jul 25 07:20:24 2000 UTC revision 692, Thu Jul 27 08:34:53 2000 UTC
# Line 8  Line 8 
8  \columnsep0.25in  \columnsep0.25in
9    
10  \newcommand{\smlmj}{110}  \newcommand{\smlmj}{110}
11  \newcommand{\smlmn}{29}  \newcommand{\smlmn}{30}
12    
13  \author{Matthias Blume \\  \author{Matthias Blume \\
14  Research Institute for Mathematical Sciences \\  Research Institute for Mathematical Sciences \\
# Line 77  Line 77 
77  \item management of (the sharing of) link-time state  \item management of (the sharing of) link-time state
78  \item conditional compilation (at compilation unit granularity)  \item conditional compilation (at compilation unit granularity)
79  \item support for parallel and distributed compilation  \item support for parallel and distributed compilation
80    \item facilities for generating stand-alone ML programs
81    \item a mechanism for deriving dependency information that can be used
82    by other compilation managers such as Unix' {\bf make}
83  \item an API to access all these facilities at SML/NJ's interactive  \item an API to access all these facilities at SML/NJ's interactive
84  prompt  prompt
85  \end{itemize}  \end{itemize}
# Line 989  Line 992 
992  and tools very easily without having to reconfigure or recompile CM,  and tools very easily without having to reconfigure or recompile CM,
993  not to mention modify its source code.  not to mention modify its source code.
994    
995  \subsubsection{Building stand-alone programs}  \subsubsection{Support for stand-alone programs}
996    \label{sec:mlbuild:support}
997    
998  CM can be used to build stand-alone programs. In fact SML/NJ  CM can be used to build stand-alone programs. In fact SML/NJ
999  itself---including CM---is an example of this.  (The interactive  itself---including CM---is an example of this.  (The interactive
# Line 1002  Line 1006 
1006  describes them to the runtime system.  describes them to the runtime system.
1007    
1008  \begin{verbatim}  \begin{verbatim}
1009    val mk_standalone : bool option -> string -> string list option    val mk_standalone : bool option ->
1010                          { project: string, wrapper: string, target: string } ->
1011                          string list option
1012  \end{verbatim}  \end{verbatim}
1013    
1014  Depending on the optional boolean argument, function {\tt  Here, {\tt project} and {\tt wrapper} name description files and {\tt
1015  CM.mk\_standalone} first acts like either {\tt CM.recomp} or {\tt  target} is the name of a heap image---with or without the usual
1016    implicit heap image suffix; see the description of {\tt
1017    SMLofNJ.exportFn} from the (SML/NJ-specific extension of the) Basis
1018    Library~\cite{reppy99:basis}.
1019    
1020    A call of {\tt mk\_standalone} triggers the following three-stage
1021    procedure:
1022    \begin{enumerate}
1023    \item Depending on the optional boolean argument, {\tt project} is
1024    subjected to the equivalent of either {\tt CM.recomp} or {\tt
1025  CM.stabilize}.  {\tt NONE} means {\tt CM.recomp}, and {\tt (SOME $r$)}  CM.stabilize}.  {\tt NONE} means {\tt CM.recomp}, and {\tt (SOME $r$)}
1026  means {\tt CM.stabilize $r$}.  After recompilation (or stabilization)  means {\tt CM.stabilize $r$}.
1027  is successful, {\tt CM.mk\_standalone} constructs a topologically  There are tree ways of how to continue from here:
1028  sorted list of strings that, when written to a file, can be passed to the  \begin{enumerate}
1029  runtime system in order to perform stand-alone linkage of the given  \item If recompilation of {\tt project}
1030  program. Upon failure, {\tt CM.mk\_standalone} returns {\tt NONE}.  failed, then a result of {\tt NONE} will be returned immediately.
1031    \item If everything was up-to-date (i.e, if no ML source had to be compiled
1032  \paragraph*{\bf ml-build:} The programmer should normally have no need  and all these sources were older than the existing {\tt target}), then
1033  to invoke {\tt CM.mk\_standalone} directly.  Instead, SML/NJ provides  a result of {\tt SOME []} will be returned.
1034  a command {\tt ml-build} which does all the work.  To be able to use  \item Otherwise execution proceeds to the next stage.
1035  {\tt ml-build}, one must implement a library exporting a structure  \end{enumerate}
1036  that has some function suitable to be an argument to {\tt  \item The {\em wrapper library} named by {\tt wrapper} is being
1037  SMLofNJ.exportFn}.  Suppose the library is called {\tt myproglib.cm}, the  recompiled (using the equivalent of {\tt CM.recomp}).  If this
1038  structure is called {\tt MyProg}, and the function is called {\tt  fails, {\tt NONE} is returned.  Otherwise execution proceeds to the
1039  MyProg.main}.  If one wishes to produce a heap image file {\tt myprog}  next stage.
1040  one simply has to invoke the following command:  \item {CM.mk\_standalone} constructs a topologically sorted list $l$
1041    of strings that, when written to a file, can be passed to the runtime
1042    system in order to perform stand-alone linkage of the program given by
1043    {\tt wrapper}.  The final result is {\tt SOME $l$}.
1044    \end{enumerate}
1045    
1046  \begin{verbatim}  The idea is that {\tt project} names the library that actually
1047    ml-build myproglib.cm MyProg.main myprog  implements the main program while {\tt wrapper} names an auxiliary
1048  \end{verbatim}  wrapper library responsible for issuing a call of {\tt
1049    SMLofNJ.exportFn} (generating {\tt target}) on behalf of {\tt
1050    project}.
1051    
1052    The programmer should normally never have a need to invoke {\tt
1053    CM.mk\_standalone} directly.  Instead, this function is used by an
1054    auxiliary script called {\tt ml-build} (see
1055    Section~\ref{sec:mlbuild}).
1056    
1057  \subsubsection{Finding all sources}  \subsubsection{Finding all sources}
1058    \label{sec:makedepend:support}
1059    
1060  The {\tt CM.sources} function can be used to find the names of all  The {\tt CM.sources} function can be used to find the names of all
1061  source files that a given library depends on.  It returns the names of  source files that a given library depends on.  It returns the names of
# Line 1069  Line 1096 
1096      (CM.sources (SOME { arch = "$ARCH", os = "$OPSYS" })      (CM.sources (SOME { arch = "$ARCH", os = "$OPSYS" })
1097           "foo.cm");           "foo.cm");
1098  \end{verbatim}  \end{verbatim}
1099    A call of {\tt CM.sources} similar to the one shown here is used by
1100    the auxiliary script {\tt ml-makedepend} (see
1101    Section~\ref{sec:makedepend}).
1102  \item[finding all {\tt noweb} sources:]  \item[finding all {\tt noweb} sources:]
1103  To find all {\tt noweb} sources (see Section~\ref{sec:builtin-tools:noweb}),  To find all {\tt noweb} sources (see Section~\ref{sec:builtin-tools:noweb}),
1104  e.g., to be able to run the document preparation program {\tt noweave}  e.g., to be able to run the document preparation program {\tt noweave}
# Line 2217  Line 2247 
2247  the ``pervasive'' environment) during {\tt CMB.make}.  Therefore, this  the ``pervasive'' environment) during {\tt CMB.make}.  Therefore, this
2248  will always be done locally by the master process.  will always be done locally by the master process.
2249    
2250    \section{The {\tt sml} command line}
2251    
2252    The SML/NJ interactive system---including CM---is started from the
2253    operating system shell by invoking the command {\tt sml}.  This
2254    command accepts a variety of arguments. This section describes those
2255    arguments that concern CM.  CM processes these arguments one-by-one
2256    from left to right.
2257    
2258    \subsection{File arguments}
2259    
2260    Names of ML source files and CM description files can appear as
2261    arguments in any order.
2262    
2263    \begin{description}
2264    \item[ML source files] are recognized by their filename extensions
2265    ({\tt .sig}, {\tt .sml}, or {\tt .fun}) and will be loaded via {\tt
2266    use} at the time the argument is being considered.  Names of ML source
2267    files are specified using the underlying operating system's native
2268    pathname syntax.
2269    \item[CM description files] are recognized by their extension {\tt
2270    .cm}.  They must be specified in CM's {\em standard} pathname syntax.
2271    The corresponding libraries (or groups) will be loaded at the time the
2272    argument is being considered by passing them to either {\tt
2273    CM.autoload} or {\tt CM.make}---depending on which {\em mode switching
2274    flag} ({\tt -a} or {\tt -m}) was specified last.  The default is {\tt
2275    -a} (i.e., {\tt CM.autoload}).
2276    \end{description}
2277    
2278    \subsection{Mode-switching flags}
2279    
2280    By default, CM description files are loaded via {\tt CM.autoload}.
2281    By specifying {\tt -m} somewhere on the command line one can force the
2282    system to use {\tt CM.make} for all following description files up to
2283    the next occurence of {\tt -a}.  The {\tt -a} flag switches back to
2284    the default behavior, using {\tt CM.autoload}, which will be in effect
2285    up to the next occurrence of another {\tt -m}.
2286    
2287    The mode-switching flags {\tt -a} and {\tt -m} can be specified
2288    arbitrarily often on the same command line.
2289    
2290    \subsection{Defining and undefining CM preprocessor symbols}
2291    \label{sec:cmdline:defundef}
2292    
2293    The following options for defining and undefining CM preprocessor
2294    symbols can also occur arbitrarily often.  Their effects accumulate
2295    while processing the command line from left to right.  Their combined
2296    effects eventually become observable in the interactive system.
2297    
2298    \begin{description}
2299    \item[{\tt -D$v$=$n$}] acts like {\tt (\#set (CM.symval "$v$") (SOME $n$))}.
2300    \item[{\tt -D$v$}] is equivalent to {\tt -D$v$=1}.
2301    \item[{\tt -U$v$}] acts like {\tt (\#set (CM.symval "$v$") NONE)}.
2302    \end{description}
2303    
2304    \section{Auxiliary scripts}
2305    
2306    \subsection{Building stand-alone programs}
2307    \label{sec:mlbuild}
2308    
2309    The programmer should normally have no need to invoke {\tt
2310    CM.mk\_standalone} (see Section~\ref{sec:mlbuild:support}) directly.
2311    Instead, SML/NJ provides a command {\tt ml-build} which does all the
2312    work.  To be able to use {\tt ml-build}, one must implement a library
2313    exporting a structure that has some function suitable to be an
2314    argument to {\tt SMLofNJ.exportFn}.  Suppose the library is called
2315    {\tt myproglib.cm}, the structure is called {\tt MyProg}, and the
2316    function is called {\tt MyProg.main}.  If one wishes to produce a heap
2317    image file {\tt myprog} one simply has to invoke the following
2318    command:
2319    
2320    \begin{verbatim}
2321      ml-build myproglib.cm MyProg.main myprog
2322    \end{verbatim}
2323    
2324    The heap image is written only when needed: if a heap image exists and
2325    is newer than all ML sources involved, provided that none of the ML
2326    sources have to be recompiled, {\tt ml-build} will just issue a
2327    message indicating that everything is up-to-date.
2328    
2329    As in the case of {\tt sml}, it is possible to define or undefine
2330    preprocessor symbols using {\tt -D} or {\tt -U} options (see
2331    Section~\ref{sec:cmdline:defundef}).  These options must be specified
2332    before the three regular arguments.  Thus, the full command line
2333    syntax is:
2334    
2335    \begin{verbatim}
2336      ml-build [DU-options] myproglib.cm MyProg.main myprog
2337    \end{verbatim}
2338    
2339    \subsubsection{Bootstrapping: How {\tt ml-build} works}
2340    
2341    Internally, {\tt ml-build} generates a temporary wrapper library
2342    containing a single call of {\tt SMLofNJ.exportFn} as part of the
2343    library's module-initialization code.  Once this is done, CM is
2344    started, {\tt CM.mk\_standalone} is invoked (with the main project
2345    description file, the generated wrapper library file, and the heap
2346    image name as arguments), and a {\em bootlist} file is written.
2347    If all these steps were successful, {\tt ml-build} invokes the (bare)
2348    SML/NJ runtime with a special option, causing it to {\em bootstrap}
2349    using the {\em bootlist} file.
2350    
2351    Each line of the {\em bootlist} file specifies one module to be linked
2352    into the final stand-alone program.  The runtime system reads these
2353    lines one-by-one, loads the corresponding modules, and executes their
2354    initialization code.  Since the last module has been arranged (by way
2355    of using the wrapper library from above) to contain a call of {\tt
2356    SMLofNJ.exportFn}, initialization of this module causes the program's
2357    heap image to be written and the bootstrap procedure to terminate.
2358    
2359    \subsection{Generating dependencies for {\tt make}}
2360    \label{sec:makedepend}
2361    
2362    When ML programs are used as parts of larger projects, it can become
2363    necessary to use CM (or, e.g., {\tt ml-build} as described in
2364    Section~\ref{sec:mlbuild}) in a traditional makefile for Unix' {\bf
2365    make}.  To avoid repeated invocations, the dependency information that
2366    CM normally manages internally must be described externally so that
2367    {\bf make} can process it.
2368    
2369    For this purpose, it is possible to let CM's dependency analyzer
2370    generate a list of files that a given ML program depends on (see
2371    Section~\ref{sec:makedepend:support}).  The {\tt ml-makedepend}
2372    scripts conveniently wraps this functionality in such a way that it
2373    resembles the familiar {\bf makedepend} facility found on many Unix
2374    installations for the use by C projects.
2375    
2376    An invocation of {\tt ml-makedepend} takes two mandatory arguments:
2377    the root description file of the ML program in question and the name
2378    of the target that is to be used by the generated makefile entry.
2379    Thus, a typical command line has the form:
2380    
2381    \begin{verbatim}
2382      ml-makedepend project.cm targetname
2383    \end{verbatim}
2384    
2385    This will cause {\tt ml-makedepend} to first look for a file named
2386    {\tt makefile} and if that cannot be found for {\tt Makefile}.  (An
2387    error message is issued if neither of the two exists.)  After deleting
2388    any previously generated entry for this description-target
2389    combination, the script will invoke CM and add up-to-date dependency
2390    information to the file.
2391    
2392    Using the {\tt -f} option it is possible to force an arbitrary
2393    programmer-specified file to be used in place of {\tt makefile} or
2394    {\tt Makefile}.
2395    
2396    Some of the files a CM-managed program depends on are stable
2397    libraries.  Since the file names for stable libraries vary according
2398    to current CPU architecture and operating system, writing them
2399    directly would require different entries for different systems.  To
2400    avoid this problem (most of the time\footnote{The careful reader may
2401    have noticed that because of CM's conditional compilation it is
2402    possible that dependency information itself varies between different
2403    architectures or operating systems.}), {\tt ml-makedepend} will use
2404    {\bf make}-variables {\tt \$(ARCH)} and {\tt \$(OPSYS)} as
2405    placeholders within the information it generates.  It is the
2406    programmer's responsibility to make sure that these variables are set
2407    to meaningful values at the time {\bf make} is eventually being
2408    invoked.  This feature can be turned off (causing actual file names to
2409    be used) by specifying the {\tt -n} option to {\tt ml-makedepend}.
2410    
2411    In cases where the programmer prefers other strings to be used in
2412    place of {\tt \$(ARCH)} or {\tt \$(OPSYS)} (or both) one can specify
2413    those strings using the {\tt -a} and {\tt -o} options, respectively.
2414    
2415    Like {\tt ml-build} (Section~\ref{sec:mlbuild}) and {\tt sml}
2416    (Section~\ref{sec:cmdline:defundef}), the {\tt ml-makedepend} command
2417    also accepts {\tt -D} and {\tt -U} command line options.
2418    
2419    Thus, the full command line syntax for {\tt ml-makedepend} is:
2420    
2421    \begin{verbatim}
2422      ml-makedepend [DU-options] [-n] [-f makefile] project.cm target
2423      ml-makedepend [DU-options] [-a arch] [-o os] [-f makefile] project.cm target
2424    \end{verbatim}
2425    
2426    (If {\tt -n} is given, then any additional {\tt -a} or {\tt -o}
2427    options---while not illegal---will be ignored.)
2428    
2429  \section{Example: Dynamic linking}  \section{Example: Dynamic linking}
2430  \label{sec:dynlink}  \label{sec:dynlink}
2431    
# Line 2978  Line 3187 
3187  \end{tabular}  \end{tabular}
3188  \end{center}  \end{center}
3189    
   
3190  \pagebreak  \pagebreak
3191    
3192  \bibliography{blume,appel,ml}  \bibliography{blume,appel,ml}

Legend:
Removed from v.691  
changed lines
  Added in v.692

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