\documentstyle[12pt]{article} \textwidth=5.75in \textheight=7.875in \hoffset=-.4in \voffset=-.75in \parskip=.1in plus 1pt minus 1pt \leftmargini=12pt \topsep=0pt \partopsep=0pt \itemsep=0pt \marginparwidth=0.7in \tolerance=1000 \pretolerance=900 \hyphenpenalty=200 \newcommand{\dir}[1]{{\em #1}} \newcommand{\proc}[1]{{\em #1}} \newcommand{\cludir}[1]{\dir{\~{}CLU}{\em #1}} \newcommand{\fname}[1]{{\em #1}} \newenvironment{boxdisplay}{\begin{center}\begin{tabular}{|l|}\hline}{\hline\end{tabular}\end{center}} \title{CLU User's Guide} \author{Dorothy Curtis and Stephen Garland\\ MIT Laboratory for Computer Science} \begin{document} \thispagestyle{empty} \maketitle This guide describes how to use the portable compiler and debugger for CLU. This compiler and debugger make CLU available on a wider variety of architectures than the earlier native CLU compilers that ran only on Vaxes and 6800's. The CLU language is described in the book {\em Abstraction and Specification in Program Development} by Barbara Liskov and John Guttag (MIT Press, 1986), and also in the {\em CLU Reference Manual} by Liskov {\it et al} (Springer-Verlag, 1981). \section{The CLU compiler} \label{clu} A CLU program consists of one or more modules, also known as {\em abstractions}. The {\em interface specification} for an abstraction completely describes how clients (i.e., other abstractions) see the abstraction and how they can use it. The interface specification for a procedural or iteration abstraction is determined by the header for that procedure or iterator; the interface specification for a data abstraction (i.e., a cluster) is determined by the header for the cluster together with the headers for the operations named in the cluster header. The implementation of each abstraction is theoretically invisible to its clients. Generally, the code for each module is kept in a separate file, the name of which ends with \fname{.clu}. Sometimes it is convenient for several modules to employ common declarations for compile-time constants, e.g., $maxLen = 100$ or $intSeq = seq[int]$. Such ``equates'' are generally kept in a separate file, the name of which ends with \fname{.equ}. \subsection{Setting up your environment} To make it easy to use CLU, you should customize your Unix environment as follows. Let \cludir{} be the directory in which CLU is installed. This directory may be \dir{/usr/clu}, \dir{/usr/pclu}, \dir{/usr/local/lib/clu}, or some other directory. Check with your system administrator to find where \cludir{} is. \begin{itemize} \item Put the command {\tt setenv CLUHOME clu-location} in your \fname{.cshrc} file, where \cludir{} is located at {\tt clu-location}. This enables various parts of the CLU system to find the information they need in \cludir{}. \item Put {\tt \$CLUHOME/exe} on your Unix search path, e.g., by adding it to the {\tt set path} command in your \fname{.cshrc} file. This allows you to invoke the CLU compiler (\fname{pclu}) and the CLU indenter (\fname{cludent}). \end{itemize} \subsection{Compiler commands} The CLU compiler compiles \fname{.clu} files into \fname{.c} files, which must then be compiled and linked using the C compiler.\footnote{Earlier native CLU compilers for Vaxes and 6800's compiled \fname{.clu} into object \fname{.bin} files, which were linked by a CLU linker. The portable compiler compiles into C rather than into machine language.} The CLU compiler can be invoked from the Unix shell by the command {\tt pclu}. Useful compiler commands include the following. \begin{center} \begin{tabular}{|l|l|} \hline Command & Effect\\ \hline {\tt ce} & create a compilation environment\\ {\tt xce} & extend a compilation environment\\ {\tt spec} & add interface specifications to the type library\\ & (ignoring implementations)\\ {\tt check} & check syntax and semantics without generating a \fname{.c} file\\ {\tt compile}& check and generate a \fname{.c} file (if there are no errors)\\ {\tt dump} & dump the type library to a \fname{.lib} file\\ {\tt merge} & read a type library from a \fname{.lib} file\\ {\tt optimize} & turn on optimization\\ {\tt optimize false} & turn off optimization\\ {\tt ext false} & turn off reporting of external abstractions\\ {\tt help} & provide a summary of all compiler commands\\ {\tt quit} & exit from the compiler\\ \hline \end{tabular} \end{center} \subsection{How the compiler works} The CLU compiler maintains a type library and a compilation environment (CE). The type library contains specifications of abstractions; initially, it contains the specifications for CLU's built-in modules. The CE contains ``equate'' information; it is initially empty. In order to do proper type checking between abstractions, the CLU compiler adds interface specifications to its type library. When it processes an abstraction, the compiler remembers the interface of the abstraction in the type library and uses it in future type checking. When an abstraction is successfully compiled, two messages may follow the compilation. The first lists undefined abstractions, that is, abstractions that do not have specifications in the type library. Undefined abstractions should be avoided, because they make it impossible for the compiler to perform complete type-checking. The second message lists abstractions used in the file being processed whose specifications are known. (This message can be suppressed by issuing the command {\tt ext false} to the compiler.) There are three commonly used ways to get specifications into the type library. \begin{enumerate} \item {\tt merge} in an appropriate type library (\fname{.lib} file). \item {\tt spec}, {\tt check}, or {\tt compile} the \fname{.clu} file containing the abstraction. \item {\tt spec} a \fname{.spc} file containing the interface specification for the abstraction. (A \fname{.spc} file differs from a \fname{.clu} file in that it contains procedure and cluster headers, but no implementations.) \end{enumerate} The top most procedure must be named {\tt start\_up}. \subsection{Command Descriptions} Following are descriptions of the most commonly used compiler commands. Each command can be abbreviated to two or more characters (e.g., {\tt compile} can be abbreviated to {\tt co}). \begin{itemize} \item {\tt ce} {\it filename} \{ , {\it filename} ... \} The {\tt ce} command creates a compilation environment from the named \fname{.equ} files. Any previously existing compilation environment is forgotten. (See {\tt xce} comand.) The compiler will supply the suffix \fname{.equ} if it is not part of {\it filename}. Each file named in this command must contain only equates. \item {\tt xce} {\it filename} \{ , {\it filename} ... \} The {\tt xce} command adds the equates in the named \fname{.equ} files to the current compilation environment. \item {\tt check} {\it filename} \{ , {\it filename} ... \} The {\tt check} command checks for syntax and type errors in the named \fname{.clu} files. The compiler will supply the suffix \fname{.clu} if it is not part of {\it filename}. \item {\tt compile} {\it filename} \{ , {\it filename} ... \} The {\tt compile} command compiles the named \fname{.clu} files into \fname{.c} files. The compiler will supply the suffix \fname{.clu} if it is not part of {\it filename}. A \fname{.c} file is produced only if there are no errors. Hence, if a \fname{.c} file is produced, any messages are warnings, not errors. The compiler generally produces \fname{.c} files that are suitable for use with the CLU debugger. Once a program has been debugged, more efficient \fname{.c} files can be produced by issuing the {\tt opt} command to the compiler before the {\tt compile} command. \item {\tt spec} {\it filename} \{ , {\it filename} ... \} The {\tt spec} command enters the interfaces of the abstractions in the named \fname{.spc} or \fname{.clu} files into the type library without type-checking any implementation bodies. The compiler will supply the suffix \fname{.spc} or \fname{.clu} if it is not part of {\it filename}. The type library initially contains the interfaces for the modules defined in the CLU reference manual. Every module that is processed successfully with a {\tt command}, {\tt check}, or {\tt spec} command has its interface added to the library. However, the compiler makes only a single pass over a file, so references within one module in a file to a module defined later in the file will not be type-checked unless the interface of the referenced module is already in the library. To get complete type-checking, it is generally necessary to {\tt spec} or {\tt check} all modules/files in a program before compiling them. \item {\tt dump} {\it filename} The compiler retains in the type library the interface of every module it sees. This library can be dumped to a \fname{.lib} file with the {\tt dump} command and later reloaded with the {\tt merge} command. The compiler will supply the suffix \fname{.lib} if it is not part of {\it filename}. Libraries make complete type-checking much easier and faster, particularly for very large programs. \item {\tt merge} {\it filename} \{ , {\it filename}, ... \} \nopagebreak[4] The {\tt merge} command loads libraries from the given \fname{.lib} files and merges them with the current type library. The compiler will supply the suffix \fname{.lib} if it is not part of {\it filename}. If the current library already contains an interface for a module in the library being loaded, the new interface will replace the old. \item {\tt optimize} [ {\tt false} ] The {\tt optimize} command turns code optimization on or off. Optimized code runs faster. Unoptimized code provides more information when used with the CLU debugger. \end{itemize} \subsection{Producing an executable program} After you have successfully compiled your \fname{.clu} files into \fname{.c} files, you must compile and link these files using the C compiler. The easiest way to do this is to use the Unix {\tt make} facility, which can also be used to compile your \fname{.clu} files. To use {\tt make}, you generally construct a file named \fname{Makefile} and type the shell command {\tt make}. To use a makefile named \fname{myMakefile}, type {\tt make -f myMakefile}. Figure~\ref{makeA} contains a sample makefile that can be used to compile the file named \fname{factorial.clu} into a program that can be used with the CLU debugger.\footnote{The three indented lines in the makefile begin with a {\tt tab} character. The {\tt make} program will not work if these {\tt tab} characters are replaced by spaces.} \begin{figure}[hbt] \small \begin{boxdisplay} \verb`# Sample CLU makefile`\\ \verb``\\ \verb`CLU = ${CLUHOME}/exe/pclu # CLU compiler`\\ \verb`CFLAGS = -I${CLUHOME}/include/debug -w -g -G 0 # C compiler flags`\\ \verb`LDFLAGS = -L${CLUHOME}/code -lpclu_debug -lgc -lm # C linker flags`\\ \verb`DEBUG = ${CLUHOME}/debug/*.o # debugger support`\\ \verb``\\ \verb`factorial: factorial.o`\\ \verb` ${CC} -o factorial factorial.o ${DEBUG} ${LDFLAGS}`\\ \verb``\\ \verb`factorial.c: factorial.clu`\\ \verb` rm -f factorial.c`\\ \verb` ${CLU} -ext false -spec factorial -compile factorial`\\ \verb``\\ \verb`clean:`\\ \verb` rm -f factorial factorial.o factorial.c`\\ \end{boxdisplay} \caption{Sample makefile for creating programs for CLU debugger} \label{makeA} \end{figure} The makefile specifies that the executable file \fname{factorial} depends on the object file \fname{factorial.o}, which in turn depends (by default) on the C source file \fname{factorial.c}, which in turn depends on the CLU source file \fname{factorial.clu}. The makefile performs the following actions when it is invoked. \begin{enumerate} \item If \fname{factorial.clu} is newer than \fname{factorial.c}, or if \fname{factorial.c} does not exist, then the makefile invokes the CLU compiler with the following commands. \begin{center} \begin{tabular}{l|l} Command & Effect\\ \hline {\tt ext false} & turns off reporting of external abstractions\\ {\tt spec factorial} & enters interface specifications in type library\\ {\tt compile factorial} & compiles \fname{factorial.clu} into \fname{factorial.c} \end{tabular} \end{center} \noindent It is important to {\tt spec} the source file before compiling it, so that specifications for abstractions that occur later in the file (e.g., a procedure named \proc{factorial}) can be used to type-check routines that occur earlier (e.g., the \proc{start\_up} procedure). \item If \fname{factorial.c} is newer than \fname{factorial.o}, or if \fname{factorial.o} does not exist, then the makefile invokes the C compiler with the specified {\tt CFLAGS}, that is, with the command \begin{center} {\tt cc -I\$\{CLUHOME\}/include -w -g -G 0 factorial.c} \end{center} \noindent This produces a \fname{factorial.o}.\footnote{The flags {\tt -G 0} are needed for DECstations and other Mips machines, but should not be used for Sparcs.} \item If \fname{factorial} is newer than \fname{factorial.o}, or if \fname{factorial} does not exist, then the makefile invokes the C linker with the command \begin{center} \verb` cc -o factorial factorial.o ${CLUHOME}/debug/*.o \`\\ \verb` -L${CLUHOME}/code -lpclu -lgc -lm}` \end{center} \noindent to link \fname{factorial.o} with the CLU debugger and library files to produce an executable file named \fname{factorial}. \end{enumerate} Because the above commands are tedious and difficult to type correctly, programmers are strongly encouraged to put them into makefiles and not to type them by hand. Once the program \fname{factorial} has been debugged, the makefile in Figure~\ref{makeB} can be used to produce an optimized version of the program.\footnote{As above, the flags {\tt -G 4} are appropriate only for DECstations and other Mips machines.} Before typing {\tt make} with this makefile, you must type {\tt make clean} to remove the files created for use with the debugger. \begin{figure}[hbt] \small \begin{boxdisplay} \verb`# Sample CLU makefile`\\ \verb``\\ \verb`CLU = ${CLUHOME}/exe/pclu # CLU compiler`\\ \verb`CFLAGS = -I${CLUHOME}/include -w -G 4 -O # C compiler flags`\\ \verb`LDFLAGS = -L${CLUHOME}/code -lpclu -lgc -lm # C linker flags`\\ \verb``\\ \verb`factorial: factorial.o`\\ \verb` ${CC} -o factorial factorial.o ${LDFLAGS}`\\ \verb``\\ \verb`factorial.c: factorial.clu`\\ \verb` rm -f factorial.c`\\ \verb` ${CLU} -ext false -spec factorial -opt -comp factorial`\\ \verb``\\ \verb`clean:`\\ \verb` rm -f factorial factorial.o factorial.c`\\ \end{boxdisplay} \caption{Sample makefile for creating optimized programs} \label{makeB} \end{figure} \subsection{Managing larger programs} The two makefiles in the previous section are appropriate for small programs. For larger programs, more sophisticated makefiles can save time in several ways. \begin{itemize} \item They can be used to avoid recompiling all modules whenever a single module changes. \item They can shorten the time needed to create a type library by using the {\tt merge} command instead of the {\tt spec} command. \end{itemize} Figure~\ref{makeC} contains a sample makefile for managing a moderate size program. Definitions at the beginning of the makefile describe where to find the modules that must be compiled and linked to build an executable program: \begin{figure} \small \begin{boxdisplay} \verb`### Sample Makefile for multimodule program`\\ \verb``\\ \verb`CLU = ${CLUHOME}/exe/pclu # CLU compiler`\\ \verb`CFLAGS = -I${CLUHOME}/include/debug -w -g -G 0 # C compiler flags`\\ \verb`LDFLAGS = -L${CLUHOME}/code -lpclu_debug -lgc -lm # C linker flags`\\ \verb`CLULIBS = ${CLUHOME}/lib/*.lib # CLU libraries`\\ \verb`DEBUG = ${CLUHOME}/debug/*.o # debugger support`\\ \verb``\\ \verb`EQUATES = Equates.equ`\\ \verb`SOURCES = collection.clu countWords.clu getWord.clu lowercase.clu`\\ \verb`LIBRARY = countWords.lib`\\ \verb`CFILES = collection.c countWords.c getWord.c lowercase.c`\\ \verb`OBJECTS = collection.o countWords.o getWord.o lowercase.o`\\ \verb`PROGRAM = countWords`\\ \verb``\\ \verb`.SUFFIXES: .c .clu`\\ \verb``\\ \verb`.clu.c:`\\ \verb` rm -f $*.c`\\ \verb` ${CLU} -ext false -merge ${LIBRARY} -ce ${EQUATES} \`\\ \verb` -compile $<`\\ \verb``\\ \verb`.clu.o:`\\ \verb` rm -f $*.c`\\ \verb` ${CLU} -ext false -merge ${LIBRARY} -ce ${EQUATES} \`\\ \verb` -compile $<`\\ \verb` ${CC} ${CFLAGS} -c $*.c`\\ \verb``\\ \verb`${PROGRAM}: ${OBJECTS}`\\ \verb` ${CC} -o ${PROGRAM} ${OBJECTS} ${DEBUG} ${LDFLAGS}`\\ \verb``\\ \verb`${LIBRARY}: ${EQUATES} ${SOURCES}`\\ \verb` make library`\\ \verb``\\ \verb`library:`\\ \verb` ${CLU} -ext false -merge ${CLULIBS} -ce ${EQUATES} \`\\ \verb` -spec ${SOURCES} -dump ${LIBRARY}`\\ \verb``\\ \verb`all: ${LIBRARY} ${PROGRAM}`\\ \verb``\\ \verb`clean:`\\ \verb` rm -f ${LIBRARY} ${CFILES} ${OBJECTS} ${PROGRAM}`\\ \end{boxdisplay} \caption{Makefile for multimodule program} \label{makeC} \end{figure} \begin{itemize} \item {\tt SOURCES} contains a list of the four source \fname{.clu} files for the program. \item {\tt EQUATES} is the name of an \fname{.equ} file containing equates (such as $strSeq = sequence[string]$) that are used in several of the source files. \item {\tt LIBRARY} is the name of a CLU type library that will be constructed from the interface specifications in the source files. \item {\tt CFILES} contains a list of the four \fname{.c} files that will be produced from the \fname{.clu} files by the CLU compiler. \item {\tt OBJECTS} contains a list of the four \fname{.o} files that will be produced from the \fname{.c} files by the C compiler. \item {\tt PROGRAM} is the name of the executable program that will be produced from the \fname{.o} files and the CLU libraries by the C linker. \end{itemize} The {\tt .SUFFIXES:} line in the makefile declares that \fname{.c} files can be built from \fname{.clu} files, and the three lines beginning with the one that contains {\tt .clu.c:} instruct the makefile to do this using the following commands: \begin{center} \begin{tabular}{l|l} Command & Effect\\ \hline {\tt ext false} & turns off reporting of external abstractions\\ {\tt merge \$\{LIBRARY\}} & creates a type library from \fname{countWords.lib}\\ {\tt ce \$\{EQUATES\}} & creates a compilation environment from \fname{Equates.equ}\\ {\tt compile \$<} & compiles the \fname{.clu} file into a \fname{.c} file \end{tabular} \end{center} \noindent The {\tt make} facility knows itself how to build \fname{.o} files from \fname{.c} files. However, the four lines in the makefile that begin with the one that contains {\tt .clu.o:} are required to describe how to build \fname{.o} files directly from \fname{.clu} files when the intermediate \fname{.c} files do not already exist. The remainder of the makefile describes the actions it will take in response to user commands. \begin{itemize} \item The first use of the makefile should be via the command {\tt make all}, which causes the makefile to build the type library \fname{countWords.lib} and then to build the executable program \fname{countWords}. \item Afterwards, whenever there is a change in the implementation of a procedure in one of the source \fname{.clu} files, the command {\tt make} (or {\tt make countWords}) should be typed to rebuild the executable program \fname{countWords}. The makefile will determine automatically which \fname{.c} and \fname{.o} files are out of date with respect to the recently changed \fname{.clu} files, and it will recompile only those files before relinking \fname{countWords}. It is precisely this behavior of the {\tt make} facility that makes it so attractive: when you change a small part of a large system, {\tt make} notices exactly which files you've changed, and it updates just that the part of the system that depends on those files. \item Whenever there is a change to a procedure or cluster interface in one of the source \fname{.clu} files, the command {\tt make all} must reissued to remake the type library before remaking the executable program. \end{itemize} There are two important limitations of makefiles such as this: \begin{enumerate} \item Because \fname{.clu} files contain implementations for procedures in addition to headers for clusters and procedures, there is no way for the makefile to determine when a change in a \fname{.clu} file affects an interface and when it affects only the implementation of an interface. Hence, to avoid remaking the \fname{.lib} interface library every time an implementation changes, the makefile requires an explicit {\tt make library} command whenever an interface changes. \item The makefile starts a separate CLU compilation to remake each out-of-date \fname{.c} file. More sophisticated makefiles can be constructed that start a single compilation to remake all out-of-date \fname{.c} files; these makefiles save time because they read \fname{.lib} type libraries and build compilation environments from \fname{.equ} files just once, rather than several times. But they are much more complicated than the makefile shown here, and are not necessary for moderate-sized projects. \end{enumerate} \section{Using Emacs with CLU} \label{emacs} The \fname{emacs} editor provides convenient facilities for preparing and compiling CLU source files. A special {\it clu-mode} allows you to access information about CLU using the \fname{emacs} help facility, and it allows you to run the CLU compiler and indenter under \fname{emacs}. It also automatically indents lines in a CLU program as you enter them. In order to use \fname{emacs} with CLU, you should edit your \fname{.emacs} file (if you do not have one, create one) to load a library that defines a {\it clu-mode}. You can do this by inserting the file \cludir{/emacs/.emacs} into your \fname{.emacs} file. \subsection{Using Emacs to prepare CLU programs} The \fname{emacs} editor should go into {\it clu-mode} automatically when you visit any file with a name that ends in {\it .clu}. Once in {\it clu-mode}, the following commands are available: \begin{description} \item[{\tt \&}] Runs the CLU compiler. When typed in a buffer named \fname{test.clu}, {\tt \&} causes \fname{emacs} to propose running the CLU compiler with the command {\tt pclu test.cu}. You can edit this command line, or you can replace it with the command {\tt make}, before typing {\tt }; \fname{emacs} will then run {\tt pclu} or {\tt make} and display the results in a separate compilation buffer. You can also edit the command line to {\tt pclu} alone, and then enter compiler commands by positioning the cursor at the compiler prompt in the compilation buffer. \item[{\tt C-X C-K}] Kills a running CLU compiler. \item[{\tt C-X $`$}] Locates errors after a CLU compile. If there were errors in a CLU compilation, {\tt C-X $`$} will position the first error message at the top of the compiler window and put the cursor at the beginning of the line containing the error. Each successive {\tt C-X $`$} will move to the next error. \item[{\tt }] Indents the current buffer. This command indents the file in a more CLU-like fashion than is done automatically in {\it clu-mode}. \end{description} At any time while in \fname{emacs}, you can return the display back to one window by entering either {\tt C-X 1} or {\tt C-X 0}. {\tt C-X 1} returns the entire display to the window in which the cursor is presently in. {\tt C-X 0} returns the entire display to the other window. {\tt C-X b} can be used to move to any buffer. \subsection{CLU help from Emacs} You can use the \fname{emacs} help facility to view information in the CLU reference manual. To get CLU help, type {\tt C-h} (the help key) followed by one of the keys: \begin{itemize} \item {\tt d} for help on CLU symbols such as {\tt int\$mul}, {\tt array}, {\tt ARRAY\$LOW}, {\tt FILE\_NAME}, {\tt string\$s2ac}, {\tt stream\$primary\_output}. \item {\tt g} for general CLU information on topics such as {\tt terminal\_i/o} , {\tt file}, {\tt own\_variables}, {\tt CLUSTERS}, {\tt syntactic\_sugar}. \item {\tt /} for CLU apropos. Give a partial name, like {\tt file}, and get a list of all the CLU symbols and topics that include that name. \end{itemize} For example, if you type {\tt C-h d}, \fname{emacs} will prompt you with {\tt Describe CLU symbol: } If you type {\tt oneof\$make\_ }, \fname{emacs} splits your screen and gives help about the CLU operation {\it oneof\$make\_}. You can request information using uppercase, lowercase, or a mixture of uppercase and lowercase. Symbol completion works (hit the {\tt } key); for example, if you type {\tt array\$} followed by {\tt }, you'll get a list of possible completions (all the operations on the CLU {\it array} abstraction in this case). If the cursor is placed on a CLU symbol when you type {\tt C-h d}, {\it emacs} will propose giving help about that symbol; for example, if your cursor is placed someplace on {\tt array[foo]\$low} in your file, and you type {\tt C-h d}, \fname{emacs} will prompt you with {\tt Describe CLU symbol (default array\$low): }; typing {\tt } selects this default help topic. To be reminded of this information, you can type {\tt M-x clu-doc-help} (i.e., {\tt META-x clu-doc-help}). \section{The debugger} The CLU debugger enables users to monitor execution of a program. Users can single step a program, executing one line at a time, or they can set {\em breakpoints} in the program. The debugger suspends execution of a program whenever it reaches a breakpoint, so that the user can determine how control reached that breakpoint and/or examine the values of program variables. Whenever a procedure is invoked, information about the invocation is pushed onto a runtime {\em stack}. This information is known as a {\em stack frame}. By examining the stack when a breakpoint is reached, the user can determine how control reached the current procedure. The debugger enables users to print the values of program variables, which are CLU objects. Users can control how much of the representations for objects are displayed. The printing {\em depth} is the maximum number of levels of nesting of an object that will be displayed. The printing {\em width} is the maximum number of components of an object that are displayed at each depth. The greater the width, the more elements in an array and the more fields in a record that are printed. The greater the depth, the more information about each element in an array or each field in a record that is displayed. \subsection{Command overview} A debugger command consists of a command name followed by a sequence of arguments separated by spaces. The following describes related groups of debugger commands. The next section contains an alphabetical list of all debugger commands and describes them in detail. \begin{itemize} \item{\bf Running} The {\tt run} and {\tt continue} commands cause the program to run continuously. The {\tt next} command causes execution of a single program line. \item{\bf Breakpoints} The {\tt break} command sets breakpoints. The {\tt show} command shows the current breakpoints. The {\tt delete} command deletes breakpoints. The {\tt step} command turns on single stepping for a procedure. The {\tt unstep} command turns off single stepping for a procedure. The {\tt trace} command turns on tracing for exceptions. The {\tt untrace} command turns off tracing for exceptions. \item{\bf The stack} The {\tt where} command displays the stack. The {\tt up} and {\tt down} commands select different frames in the stack. \item{\bf Printing} The {\tt print} command displays the values of variables. The {\tt width} and {\tt depth} commands control how much of the value is displayed. \item{\bf Invocation} The {\tt eval} command evaluates procedure invocations. \item{\bf Source code} The {\tt list} command displays source code. The {\tt func} command selects a procedure to be displayed. Reaching a breakpoint also selects the procedure containing as the one to be displayed. Moving up and down the stack changes the procedure to be displayed. \item{\bf Miscellaneous} The {\tt help} command gives brief information on debugger commands. All commands can be displayed via {\tt help all}. The {\tt quit} command terminates the debugger. \end{itemize} \subsection{Commands} This section describes each command in detail. Commands are listed alphabetically. Users can repeat execution of the {\tt continue}, {\tt eval}, {\tt up}, {\tt list}, {\tt down}, {\tt next} commands simply by pressing the {\tt } key. \begin{itemize} \item {\tt break} \{{\it breakpoint ...}\} The {\tt break} command instructs the debugger to stop when a particular procedure or iterator is entered or exited or before a particular line in a file is executed. Each {\it breakpoint} is either the name of a procedure, the name of an iterator, or a line number, which refers to a line in the file containing the current procedure (or iterator). Note that the {\tt func}, {\tt up}, and {\tt down} commands change the current procedure. Some examples: \begin{verbatim} break start_up % sets breakpoints on entry to and % exit from the top-most procedure \end{verbatim} \begin{verbatim} break 10 % sets a breakpoint at line 10 % in the current procedure \end{verbatim} \begin{verbatim} break 10 20 % sets breakpoints at lines 10 and 20 % in the current procedure \end{verbatim} \begin{verbatim} break t$op1 t$op2 % sets breakpoints on entry to and % exit from procedures t$op1 and t$op2 \end{verbatim} \begin{verbatim} break t$op1 t$op2 10 % sets breakpoints on entry to and % exit from procedures t$op1 and t$op2 % and at line 10 in the current procedure % (which may not be either t$op1 or t$op2) \end{verbatim} \begin{verbatim} func t$op1 % select function t$op1 break 10 % sets a breakpoint at line 10 in t$op1 \end{verbatim} Whenever the debugger reaches a breakpoint, it displays the corresponding line in the source file and stops before executing that line. \item {\tt continue} The {\tt continue} command directs the debugger to continue running the program, either until the next breakpoint or until the next instruction in a procedure (or iterator) that is being single-stepped. It terminates any single-stepping set by the {\tt next} command in the current procedure (or iterator). \item {\tt delete} {\it breakpoint} \{{\it breakpoint ...}\} The {\tt delete} command removes the specified breakpoints. (Note: If there are two breakpoints with the same line number, only the first will be deleted.) The argument {\tt all} causes all breakpoints to be removed. Some examples: \begin{verbatim} delete t$op1 % deletes the breakpoints on entry to % and exit from the procedure t$op1 \end{verbatim} \begin{verbatim} delete all % deletes all breakpoints \end{verbatim} \item {\tt depth} \{{\it integer}\} The {\tt depth} command controls the printing depth for objects printed by the {\tt print} command. If the {\tt depth} command has no argument, the debugger prints the current depth. See also the {\tt width} command. \item {\tt down} \{{\it integer}\} The {\tt down} command moves down the specified number of stack frames. If no argument is specified, then 1 is assumed. See also the {\tt where} command and the {\tt up} command. \item {\tt eval} {\it expression} The {\tt eval} command evaluates the specified expression. The following section describes the legal expressions. Some examples: \begin{verbatim} eval a = "xyz" % sets the variable a to "xyz" eval po = stream$primary_output() % sets po to % the primary output stream eval stream$putl(po, a) % prints a on po \end{verbatim} \noindent The assignment to the variable {\tt a} in the example above changes the value of the variable {\tt a} in the current stack frame, if such a variable exists. Otherwise, it creates a debugger variable named {\tt a} and assigns the value of the expression to that variable. \item {\tt func} \{{\it name}\} The {\tt func} specifies the named procedure (or iterator) to be the one of current interest, either for listing source code or for setting breakpoints at line numbers. If no argument is given, the current line is printed, along with the five preceding and five succeeding lines \begin{verbatim} func t$op1 % select function t$op1 list % list lines surrounding t$op1 break 10 % set a breakpoint at line 10 in % the file containing t$op1 \end{verbatim} \item {\tt help} \{{\it command}\} The {\tt help} command, with no arguments, gives a summary of command names. When a command name is present as an argument, the {\tt help} command will give a short description of the specified command. If the argument is the keyword {\tt all}, short descriptions of all commands are displayed. \item {\tt list} \{{\it integer ...}\} The {\tt list} command displays source code in the current procedure (or iterator). By default, the current procedure is the routine that last reached a breakpoint. When the debugger first starts up, the {\tt start\_up} procedure is selected as the current procedure. The {\tt func}, {\tt up}, and {\tt down} commands change the current procedure to the specified procedure. The arguments to {\tt list} specify the line numbers of interest (use a space to separate the line numbers). The {\tt where} command can be used to show the current line numbers in the currently active procedures. \begin{verbatim} list % list lines at current breakpoint func t$op1 % select function t$op1 list % list lines surrounding t$op1 \end{verbatim} \item {\tt next} \{{\it integer}\} The {\tt next} command directs the debugger to single step to the next line in the current procedure. When a numeric argument $n$ is present, the debugger executes the next $n$ lines in the current procedure and prints out the corresponding source code as each line is executed. \item {\tt print} {\it variable} The {\tt print} command prints the values of variables, procedure arguments, and {\bf own} variables. Uninitialized variables are printed as {\tt ???}. \item {\tt quit} The {\tt quit} command causes the debugger to terminate. \item {\tt rebuild} The {\tt rebuild} command causes the debugger to run {\tt make} and then the program. \item {\tt restart} The {\tt restart} command causes the debugger to restart the program: a new process is created, causing {\bf own} variables to be initialized and the stack to be empty. \item {\tt run} The {\tt run} command causes the debugger to continue running the program. \item {\tt show} The {\tt show} command displays the location of the current breakpoints. \item {\tt step} {\it name} The {\tt step} command turns on single stepping for the specified procedure. \item {\tt trace} {\it name} The {\tt trace} command turns on tracing for the named signal. \begin{verbatim} trace bounds % trace the bounds exception trace all % trace all exceptions \end{verbatim} \item {\tt unstep} {\it name} The {\tt unstep} command turns off single stepping for the specified procedure. \item {\tt trace} {\it name} The {\tt untrace} command turns off tracing for the named signal. \begin{verbatim} untrace bounds % stop tracing the bounds exception untrace all % do not trace any exceptions \end{verbatim} \item {\tt up} \{{\tt integer}\} The {\tt up} command moves up the specified number of stack frames. If no argument is specified, 1 is assumed. See also the {\tt where} command and the {\tt down} command. \item {\tt where} \{{\tt integer}\} The {\tt where} command displays the frames on the stack. A numeric argument $n$ limits the output to the last $n$ frames pushed on the stack. \item {\tt width} \{{\tt integer}\} The {\tt width} command controls the printing width for objects printed by the {\tt print} command. If the {\tt width} command has no argument, the debugger prints the current width. See also the {\tt depth} command. \end{itemize} \subsection{Expressions} The {\tt eval} command currently accepts the following expressions: \begin{itemize} \item{Constants:} \begin{itemize} \item{booleans: {\tt 0} for false, {\tt 1} for true} \item{characters: {\tt $'$a$'$}} \item{strings: {\tt "abc"}} \item{integers: {\tt 1}} \item{reals: {\tt 1.2}} \end{itemize} \item{Variables:} The debugger first looks for a debugger variable with the given name, then for a local variable in the current procedure (or iterator), then for an {\bf own} variable in the current procedure (or iterator) and finally for an {\bf own} variable in the current type. The current version of the debugger does not always print the value of the variable that one expects: if two parallel scopes use the same name to denote variables of different types, the first declaration determines the print operation. \item{Invocations:} The programmer may invoke stand-alone procedures and procedures from parameterized or unparameterized clusters. Arguments to procedures can be constants or variables, as described above. The current debugger does not recognize sugars: users must type {\tt eval int\$add(1,2)} rather than {\tt eval 1+2}. The debugger does not type-check arguments for procedure invocations; irrecoverable errors may result if arguments do not have the appropriate types. Some support has been added to ease access to components of complex objects. Instead of {\tt eval record[f1:int, f2: string]\$get\_f1(r1)}, the user may type {\tt eval rep\$get\_f1(r1)}. \end{itemize} \subsection{Operational notes} \subsubsection{Interrupting the debugger} When a program is running, typing {\tt control-c} (i.e., holding down the control or ctrl key and then pressing the letter {\tt c}), will cause control to be passed back to the debugger. This assumes that {\tt control-c} is your {\tt INTR} (interrupt) character. (See {\em man (2) stty}.) For {\tt control-c} to take effect, the program must pass through a procedure entry/exit point or a procedure with line breakpoints set in it (these lines do not need to be executed). A program in an infinite loop, which does not call a procedure, will not respond to {\tt control-c}. To kill off such a program, type {\tt control-z} (or your {\tt SUSP} (suspend) character), use the {\tt jobs} shell command to locate the errant program, and type \begin{verbatim} kill -9 %number_associated_with_program \end{verbatim} You may need to use the {\tt reset} shell command to restore normal tty behavior. \subsubsection{Auxiliary files} When a program is executed under the debugger, an auxiliary file with symbol information is created. If the program is named \fname{ps1}, then the file is named \fname{ps1.sym}. To preserve break point settings between debugging sessions, the debugger maintains the current breakpoints in a file. If the program is named \fname{ps1}, then the file is named \fname{ps1.bkpts}. \subsubsection{A note on stacks} When an iterator is active, the invoking procedure will appear on the stack twice: once for the invocation and once for the body of the {\bf for} statement. Also, low-level routines that are in-lined may not appear on the stack, so setting breakpoints at such low-level routines may have no effect. Own initialization is not traceable and does not appear on the stack. \subsubsection{Capturing output} The (Unix) {\tt script} command provides a method for capturing output created during a debugging session. \subsubsection{Fatal errors} When running a program, a fatal error may occur and result in a Unix {\tt Segmentation Violation} or {\tt Bus Error}. When this happens, the debugger executes a {\tt where} command to display the stack and then terminates. These errors are frequently caused by uninitialized variables. If a program accesses uninitialized variables without triggering a fatal error, the state of the debugger may be corrupted. If a circularly-linked object is printed, the debugger may terminate when the stack fills up. \subsubsection{How Printing Works} When printing an object of type t, the debugger uses {\tt t\$print}, if it exists and takes an object of type t (or cvt) as its first argument and a pstream as its second argument. If such an operation does not exist, {\tt rep\$print} for type t is used. \section{Line editing} The debugger and compiler support a limited amount of line editing. The following files are used to specify key bindings for line editing: \fname{\~{}/.lineedit.keys} and \fname{\~{}/.inputrc}. These files override the default settings given by the following table. \begin{center} \begin{tabular}{|l|l|l|}\hline Key & Action &Alternative key\\ \hline ctrl-A & move to beginning of the line &ESC\\ ctrl-B & move back (left) one character &left-arrow on lk-201's\\ ctrl-D & delete current character &\\ ctrl-E & move to end of current line &\\ ctrl-F & move forward (right) one character &right-arrow on lk-201's\\ ctrl-J & complete entry &\\ ctrl-K & delete to the end of the line &remove-key on lk-201's\\ ctrl-M & complete entry &\\ ctrl-N & move to next history item &down-arrow on lk-201's\\ ctrl-P & move to previous history item &up-arrow on lk-201's\\ ctrl-U & delete line &\\ ctrl-W & delete word &\\ del & delete previous character &\\ & move forward one word & next-screen on lk-201's\\ & move back one word & prev-screen on lk-201's\\ \hline \end{tabular} \end{center} \end{document}