\documentstyle[12pt]{article}

% Use full page
\topmargin 0pt
\advance \topmargin by -\headheight
\advance \topmargin by -\headsep
\textheight 8.9in
\oddsidemargin 0pt
\evensidemargin \oddsidemargin
\marginparwidth 0.5in
\textwidth 6.5in

% Useful environments
\newenvironment{indenttext}{%
\begin{list}{}{%
\leftmargin=0.5in%
\rightmargin=0in%
\labelsep=0pt%
\labelwidth=0pt%
\listparindent=\parindent%
}%
\item%
}{%
\end{list}%
}

\newenvironment{syntax}{%
\subsection*{\hspace{0.25in}Syntax}%
\begin{indenttext}
}{%
\end{indenttext}%
}

\newenvironment{overview}{%
\subsection*{\hspace{0.25in}Overview}%
\begin{indenttext}
}{%
\end{indenttext}%
}

\newenvironment{options}{%
\subsection*{\hspace{0.25in}Options}%
\begin{indenttext}
\begin{tabular}{@{\hspace{\tabcolsep}\tt}lp{4.4in}}%
}{%
\end{tabular}%
\end{indenttext}%
}

\newenvironment{comments}{%
\subsection*{\hspace{0.25in}Comments}%
\begin{indenttext}
}{%
\end{indenttext}%
}

\title{Using Portable CLU}
\date{February 10, 1992}
\author{Sanjay Ghemawat\\Stephen Garland\\Dorothy Curtis}

\begin{document}

\maketitle

\noindent This document explains how to use portable CLU to compile
and link CLU programs to produce executables.

\section{Overview}

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 \verb|.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 \verb|.equ|.

\section{Using the Compiler}

There are several steps in compiling a CLU program. First, we create
an interface library that contains the interface specifications of all
of the modules that will make up the program. Then we compile the
modules against this library. (Portable CLU differs from earlier
non-portable CLU compilers in that the interfaces of all modules must
be extracted into an interface library before any module is compiled
with portable CLU.  Earlier compilers were more relaxed about this
requirement.)  Finally we link the resulting object files together
into an executable program.

Keep in mind that the format of interface libraries and object files
produced by portable CLU is different from that produced by earlier
compilers. Therefore, you should not mix libraries and object files
generated by different compilers.

The default of the pclu compiler is to produce debugging code.
Use the optimize flag if optimization, rather than debugging is desired.

If the program should allow debugging, then the \verb|-debug| flag
should be supplied consistently to each pclu invocation.

Section~\ref{section:syntax} describes how to use pclu to generate an
executable program from CLU source files.

\section{Syntax}
\label{section:syntax}

\subsection{Creating a type library}

\begin{syntax}
\verb|pclu -spec <source>.clu ... -dump <file>.lib|
\end{syntax}

\begin{overview}
  Checks the interface specifications of the specified source files
  and dumps the resulting interface information into the library file
  \verb|<file>.lib|
\end{overview}

\begin{options}
-ce <foo>.equ&Use equates from specified file\\
-use <foo>.lib&Read type info from library before compiling\\
\end{options}

\begin{comments}
Multiple \verb|.lib| files and equate files can be specified.
\end{comments}

\subsection{Compiling CLU files}

\begin{syntax}
\verb|pclu -compile <source>.clu ...|
\end{syntax}

\begin{overview}
Generates \verb|<source>.o| for each specified CLU file \verb|<source>.clu|.
\end{overview}

\begin{options}
-optimize&Generate optimized output\\
-ce <foo>.equ&Use equates from specified file\\
-merge <foo>.lib&Read type info from library before compiling\\
\end{options}

\begin{comments}
If \verb|-optimize| is specified, optimized code will be generated, if
not, debugging code will be generated.
Multiple \verb|.lib| files and equate files can be specified.
\end{comments}

\subsection{Linking a program}

\begin{syntax}
\verb+plink -o <program> [<object>.o] [<object-library>.a] ...+
\end{syntax}

\begin{overview}
Links the specified \verb|.o| and \verb|.a| files together and creates
executable \verb|<program>|.  \verb|.o| files are generated by pclu
(and various other compilers).  \verb|.a| files contain a number of
different \verb|.o| files and can be generated via the \verb|ar|
program.
\end{overview}

\begin{options}
-opt&Generate optimized output\\
\end{options}

\begin{comments}
If \verb|-optimize| is specified, then an optimized program is generated,
otherwise, as the default, a debugging program is generated.
\end{comments}

\subsection{Spec-checking CLU files}

\begin{syntax}
\verb|pclu -spec <source>.clu ...|
\end{syntax}

\begin{overview}
Spec checks each source file \verb|<source>.clu|
\end{overview}

\begin{options}
-ce <foo>.equ&Use equates from specified file\\
-merge <foo>.lib&Read type info from library before compiling\\
\end{options}

\begin{comments}
Multiple \verb|.lib| files and equate files can be specified.
\end{comments}

\subsection{Examples}

The first example demonstrates how to compile a CLU program with all
code in a single file. We first need to create a type library for the
program.

\begin{indenttext}
\verb|pclu -spec factorial.clu -dump factorial.lib|
\end{indenttext}

\noindent Now we compile the file against the type library created
during the last step.

\begin{indenttext}
\verb|pclu -merge factorial.lib -compile factorial.clu|
\end{indenttext}

\noindent Now link the program together.

\begin{indenttext}
\verb|plink factorial factorial.o|
\end{indenttext}

\noindent Suppose we have a multiple file program with an equate file that we
wish to compile with optimization enabled. Here are the three pclu
invocations that achieve that goal.

\begin{indenttext}
  \verb|pclu -ce define.equ -spec main.clu support.clu -dump prog.lib|\\
  \verb|pclu -merge prog.lib -ce define.equ -opt -compile main.clu support.clu|\\
  \verb|plink -opt -o prog main.o support.o|
\end{indenttext}

\subsection{A More Complicated Example}

Suppose somebody else implemented some abstractions and provided me
with an interface library and object files for those abstractions.
Suppose the supplied interface library is called \verb|ps9.lib|, the
supplied object files are \verb|graph.o| and \verb|tree.o|, and all of
these files are stored in some directory \verb|<dir>|. I write code
that uses these supplied abstractions and put my code in two CLU files
\verb|main.clu| and \verb|spanning.clu|. In addition, I create an
equate file \verb|x.equ| containing some common abbreviations. First I
need to create an interface library for the whole program. I do this
by using the supplied interface library and also checking the two CLU
files I wrote. (The backslash in the following text is a shell
convention that indicates that the next line is part of the command
started on this line.)

\begin{indenttext}
\begin{verbatim}
pclu -merge <dir>/ps9.lib -ce x.equ main.clu spanning.clu -dump my.lib
\end{verbatim}
\end{indenttext}

\noindent Now I can compile my CLU files against the interface library
I just generated. Note that I do not need to mention the original
interface library in this step because the contents of that interface
library were copied into my library by the first step. However, the
equate file is specified for all compiler invocations (except the last
linking phase). This will be true both of equates files I write, and
equate files supplied by somebody else.

\begin{indenttext}
  \verb|pclu -merge my.lib -ce x.equ -co main.clu spanning.clu|
\end{indenttext}

\noindent Finally, I link everything (including the supplied object
files) together.

\begin{indenttext}
  \verb|plink -o program main.o spanning.o <dir>/graph.o <dir>/tree.o|
\end{indenttext}

\section{Using Makefiles}

This section describes how to write makefiles for CLU programs that
are intended to be compiled by the portable CLU compiler. If you don't
know what a makefile is or what the program \verb|make| does, then
skip this section. You can come back to it when you know more about
\verb|make|.

Makefiles can be used to automate the process of compiling CLU
programs. This can be useful for two different reasons. First, the
example given above was quite complicated. Automating the compilation
process can reduce the tedium and complexity of typing in long
compilation commands over and over again.

Second, using \verb|make| can sometimes help us avoid unnecessary
recompilation.  Because of certain peculiarities in CLU compilers,
this feature of \verb|make| cannot be utilized to its full extent for
CLU programs.  Therefore, I will not stress the use of \verb|make| to
void recompilation. I will focus more on the automation of the
compilation process.

Let us try and write a makefile to perform the task described in the
previous example where some of the code was supplied by someone else.
I will describe this task in a top-down manner.  The main goal of the
makefile should be to produce the executable \verb|program|. The files
required to generate \verb|program| are \verb|main.o| and
\verb|spanning.o|. (I will assume that the supplied object files
will always exists and therefore my makefile does not have to create
them).

\begin{indenttext}
\begin{verbatim}
program: main.o spanning.o
        plink program main.o spanning.o \
                <dir>/graph.o <dir>/tree.o
\end{verbatim}
\end{indenttext}

\noindent If \verb|main.o| and \verb|spanning.o| exist, then
\verb|make| will produce \verb|program| by linking the specified
object files together. Otherwise, it will have to generate
\verb|main.o| and \verb|spanning.o|. So let us write down the
rules for generating these files.

\begin{indenttext}
\begin{verbatim}
main.o: main.clu my.lib
        pclu -merge my.lib -ce x.equ -co main.clu

spanning.o: spanning.clu my.lib
        pclu -merge my.lib -ce x.equ -co spanning.clu
\end{verbatim}
\end{indenttext}

\noindent Now we have to tell \verb|make| how and when to create
\verb|my.lib|.

\begin{indenttext}
\begin{verbatim}
my.lib: main.clu spanning.clu
        pclu -merge <dir>/ps9.lib -ce x.equ -spec main.clu spanning.clu \
		-dump my.lib
\end{verbatim}
\end{indenttext}

\noindent We can combine all these rules and put them into a file
named \verb|Makefile|.

\begin{indenttext}
\begin{verbatim}
program: main.o spanning.o
        plink -o program main.o spanning.o \
                <dir>/graph.o <dir>/tree.o

main.o: main.clu my.lib
        pclu -merge my.lib -ce x.equ -co main.clu

spanning.o: spanning.clu my.lib
        pclu -merge my.lib -ce x.equ -co spanning.clu

my.lib: main.clu spanning.clu
        pclu -merge <dir>/ps9.lib -ce x.equ -co main.clu spanning.clu \
             -dump my.lib
\end{verbatim}
\end{indenttext}

\noindent The command \verb|make| issued to the shell will perform any
necessary recompilations and produce an executable file called
\verb|program|.

\end{document}