% todo: isac, no BDigits

\documentstyle{maintain}

\title{SACLIB Maintainer's Guide}

\author[M. J. Encarnaci\'on]{MARK J. ENCARNACI\'ON\thanks{
Department of Computer Science, University of the Philippines,
Quezon City 1101, Philippines.
$\langle${\tt mje@engg.upd.edu.ph}$\rangle$}}

\date{23 August 1995}

\font\ninerm=cmr9
\let\mc=\ninerm % medium caps
\def\CEE/{{\mc C\spacefactor1000}}
\def\SACLIB/{{\mc SACLIB\spacefactor1000}}

\def\argu#1{{$\langle${\em #1\/}$\rangle$}}

\hyphenation{sac-lib}

\begin{document}

\maketitle

\begin{abstract}
Various routine SACLIB maintenance chores are described.
Unless you plan to maintain SACLIB, you need not
read further.
\end{abstract}

%%  \section{Directory structure}
%%  
%%  Here are the directories in the directory \verb|$saclib|.
%%  
%%  \begin{tabbing}
%%  X \= XXXXXXX \= \kill
%%  \verb|RCS| \> \> --- RCS log files\\
%%  \verb|bin| \> \> --- shell scripts\\
%%  \verb|doc| \> \> --- documentation\\
%%    \> \verb|guide| \> --- \LaTeX\ sources\\
%%  \verb|example| \> \> --- example programs\\
%%  \verb|include| \> \> --- header files\\
%%  \verb|isac| \> \> --- interface programs sources, header files, and executables\\
%%  \verb|lib| \> \> --- the compiled libraries\\
%%    \> \verb|objd| \> --- the debugging object files\\
%%    \> \verb|objo| \> --- the optimized object files\\
%%  \verb|pardep| \> \> --- parameter dependent sources\\
%%    \> \verb|W_32_Z_29| \> --- sources that require 32-bit words,
%%  				 with $\verb|ZETA|=29$\\
%%  \verb|src| \> \> --- the source files\\
%%  \verb|sysdep| \> \>  --- system dependent files\\
%%  \verb|times| \> \> --- timings for various functions
%%  \end{tabbing}

\section{Adding new functions}

To add a new function, say {\tt NEWF.c}, to \SACLIB/, do the
following.


\begin{enumerate}
\item[(1)] Put {\tt NEWF.c} in the directory {\tt \$saclib/src}.
\item[(2)] Check-in {\tt NEWF.c} using the script {\tt sci}. \ (See
Section~\ref{section:rcs}.)
\item[(3)]  {\tt mkproto}
\item[(4)]  {\tt mkmake}
\item[(5)]  {\tt mklib all}
\item[(6)]  {\tt mkisac}
\item[(7)]  {\tt mkdesc}
\end{enumerate}


I assume here that the environment variable {\tt saclib} has
been properly set to the main directory of \SACLIB/, so that
\verb|$saclib| is a shorthand for that directory.


If you are adding more than one function, then do steps
(1)~and~(2), in that order, for each new function.
Steps (3)--(7) only need to be done after adding all the new
functions.
Steps (3), (4), (5), and~(6) should be done in that order.


Step~(3) creates {\tt \$saclib/include/sacproto.h}, which
contains a prototype of each function in \SACLIB/.


Step~(4) creates new {\tt makefile}s in the directories {\tt
\$saclib/lib/objd} and {\tt \$saclib/\-lib/objo}.


Step~(5) {\tt make}s the optimized library {\tt
\$saclib/lib/saclibo.a} and the debugging library {\tt
\$saclib/lib/saclibd.a}.
Alternatively, {\tt mklib opt} ({\tt mklib deb})
{\tt make}s only the optimized (debugging) library.
Under normal circumstances, you should type {\tt mklib all} to
{\tt make} both libraries.

Step~(6) {\tt make}s the interface progam {\tt isac}.

Step~(7) creates the file {\tt \$saclib/doc/desc.doc}, which is
used by the script {\tt sdesc}.


Each of Steps (3)--(7) may take a minute or two to finish.


\section{Modifying functions}
Before modifying a \SACLIB/ file, you should first check-in the
file so that the modification can be ``undone''.
See Section~\ref{section:rcs} for details and an example.

\section{Deleting functions}

To delete a file, say {\tt OLDF.c}, from \SACLIB/, do the
following.
\begin{itemize}
\item[(1)] If {\tt OLDF.c} does not have an RCS file, then
check it in. \ (See Section~\ref{section:rcs}.)
\item[(2)] Edit {\tt OLDF.c} so that `{\tt [ removed from library
]}' is the first line of the file {\tt OLDF.c}.
\item[(3)] Check-in the modified {\tt OLDF.c} with \argu{state}
set to {\tt del}.
\item[(4)]  {\tt rm \$saclib/src/OLDF.c}
\item[(5)]  {\tt cd \$saclib/lib}
\item[(6)]  {\tt ar d saclibd.a OLDF.o}
\item[(7)]  {\tt ar ts saclibd.a}
\item[(8)]  {\tt ar d saclibo.a OLDF.o}
\item[(9)]  {\tt ar ts saclibo.a}
\item[(10)]  {\tt rm objo/OLDF.o objd/OLDF.o}
\item[(11)]  {\tt mkproto}
\item[(12)]  {\tt mkmake}
\item[(13)]  {\tt mkdesc}
\item[(14)]  {\tt mkisac}
\end{itemize}

Note that the libraries do not have to be recompiled, but {\tt
isac} should be remade.


Steps~(6) and~(8) delete the specified object file from the
specified library, and Steps~(7) and~(9) update the symbol table
of the specified library.

If you are deleting more than one file, then Steps~(6)--(9) may
be performed only once by listing all the files to be deleted.
For example, if you are deleting {\tt OLDF1.c} and {\tt
OLDF2.c}, then you may do instead:
\begin{itemize}
\item[(6)]  {\tt ar d saclibd.a OLDF1.o OLDF2.o}
\item[(7)]  {\tt ar ts saclibd.a}
\item[(8)]  {\tt ar d saclibo.a OLDF1.o OLDF2.o}
\item[(9)]  {\tt ar ts saclibo.a}
\end{itemize}


As an alternative to Steps~(11), (12), and ~(13), you can
manually remove the corresponding lines in the files
\begin{itemize}
\item[] \verb|$saclib/include/sacproto.h|,
\item[] \verb|$saclib/lib/objd/makefile|,
\item[] \verb|$saclib/lib/objo/makefile|, and
\item[] \verb|$saclib/doc/desc.doc|.
\end{itemize}
This alternative will be somewhat quicker, but will require more
work on your part and is prone to error.




\section{Revision control} \label{section:rcs}

I've used the Revision Control System (RCS) for keeping track of
the changes that have been made to \SACLIB/.\footnote{The RCS
system is available at {\tt ftp.cs.purdue.edu} in the directory
{\tt pub/RCS}.}

The script {\tt sci} allows you to ``check-in'' a revision.
Before making any changes to a file, that file should first be
checked in so that the original revision of the file can be
retrieved.
For example, suppose I want to make changes to the algorithm of
{\tt IPFAC.c}.  Before making the changes, I would {\tt cd} to
{\tt \$saclib/src} and type {\tt sci IPFAC.c init saclib}.  I
will then get a message on the screen that looks like:
\begin{verbatim}
/usr/local/saclib/saclib2.1/RCS/IPFAC.c,v  <--  IPFAC.c
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>>
\end{verbatim}
At the prompt {\tt >>}, I will now type the description of {\tt
IPFAC.c}:
\begin{verbatim}
>> Integral polynomial factorization.
>> .
\end{verbatim}
The period `{\tt .}' terminates the input. \ (If the
backspace key does not work while the prompt {\tt >>} is active,
then use CTRL-h instead.) \
The RCS file {\tt \$saclib/RCS/IPFAC.c,v} will now have been
created.
All future changes that are made to {\tt IPFAC.c} and that are
recorded using {\tt sci} will be stored in that RCS file.


After making my changes to {\tt IPFAC.c}, I should now check-in
the changes.
To do so, I type {\tt sci IPFAC.c algo Mark}.  I will then get a
message like:
\begin{verbatim}
/usr/local/saclib/saclib2.1/RCS/IPFAC.c,v  <--  IPFAC.c
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>>
\end{verbatim}
At the {\tt >>} prompt, I type in a short description of the
changes that were made.
For example, I might type:
\begin{verbatim}
>> Introduced heuristic that searches for a variable of
>> degree 1 or 2 so that the polynomial can be factored
>> by formula.
\end{verbatim}

If I make further changes to {\tt IPFAC.c}, for example, if I
fix a bug in {\tt IPFAC.c}, then I would type {\tt sci IPFAC.c
bug Mark}.  Note that I should not type {\tt sci IPFAC.c init
saclib} beforehand; that command should only be issued once for
each file.


The general form of the {\tt sci} command is:
 {\tt sci} \argu{filename} \argu{state} \argu{author}.
The argument \argu{filename} should include the extension (`{\tt
.c}', for instance).
The argument \argu{state} should be one of the following:
\begin{tabbing}
XX \= {\tt algooo} \= \kill
\> {\tt algo}   \>  algorithm change\\
\> {\tt bug}    \>  bug fix\\
\> {\tt del}    \>  deleted from library\\
\> {\tt embe}   \>  embellishment\\
\> {\tt init}   \>  initial revision\\
\> {\tt new}    \>  new file\\
\> {\tt typo}   \>  typographical correction\\
\> {\tt spec}   \>  specification correction
\end{tabbing}
The argument \argu{author} should be the name of the person who
made the change.  The \SACLIB/ maintainer will be the only
person checking in revisions, but \argu{author} should be the
name of the person proposing the change (so you know whom to
blame!).


The revision history of a file can be viewed using the script
{\tt slog}.  For example, {\tt slog IPFAC.c} will produce
something like:
{\small
\begin{verbatim}
=============================================================================
IPFAC.c
Integral polynomial factorization.
----------------------------
revision 1.2    locked by: saclib;
date: 1995/08/11 09:40:49;  author: Mark;  state: algo;  lines: +48 -17
Introduced heuristic that searches for a variable of
degree 1 or 2 so that the polynomial can be factored
by formula.
----------------------------
revision 1.1
date: 1995/08/11 09:35:37;  author: saclib;  state: init;
Initial revision
=============================================================================
\end{verbatim}
}

The original revision of {\tt IPFAC.c} can be retrieved by typing
{\tt slog IPFAC.c 1.1}; this will cause the original revision of
{\tt IPFAC.c} to printed on the screen.
You can save the original revision of {\tt IPFAC.c} to a file by
redirection: {\tt slog IPFAC.c 1.1 > oIPFAC.c} will produce the
file {\tt oIPFAC.c}, which will contain the original revision of
{\tt IPFAC.c}.
In general, any particular revision of a file can be retrieved in
this way by giving the appropriate revision number (in place of
`{\tt 1.1}' in the example above) as given in the output of {\tt
slog}.


\section{Deleting revisions}

In some cases, you may want to delete a revision from an RCS
file.
A typical example is the following.
Suppose I have a new version of {\tt IPFAC.c} that I want to put
into \SACLIB/.
While developing the new version of {\tt IPFAC.c}, I used a
header file that I wrote, and this header file is {\tt
\#include}d by the new {\tt IPFAC.c}.
Now I check-in the new {\tt IPFAC.c}, but I neglect to change
the {\tt \#include} statement.
The erroneous new {\tt IPFAC.c} is now recorded in the RCS file
{\tt \$saclib/RCS/IPFAC.c,v} as {\tt revision 1.3}, say.
What should I do?
One option would be to simply fix {\tt IPFAC.c} and check-in
this new revision as {\tt revision 1.4}.
This solution is not satisfactory because the silly mistake of
not changing the {\tt \#include} statement will be recorded.


To delete the erroneous revision, do the following.

\begin{itemize}
\item[(1)] {\tt cd \$saclib/RCS}
\item[(2)] {\tt chmod 600 IPFAC.c,v}
\item[(3)] {\tt rcs -u1.3 IPFAC.c,v}
\item[(4)] {\tt rcs -o1.3 IPFAC.c,v}
\item[(5)] {\tt rcs -l1.2 IPFAC.c,v}
\item[(6)] {\tt chmod 444 IPFAC.c,v}
\end{itemize}

Step~(2) changes the file permissions so that you can write to
the RCS file.

Step~(3) unlocks revision 1.3 so that you can delete it.

Step~(4) outdates (deletes) revision 1.3 from the RCS file.

Step~(5) locks revision 1.2.  You will not be able to check-in
later revisions unless the last revision is locked by you.

Step~(6) makes the file only readable, and not writable.
I decided to set these permissions to avoid inadvertently
changing the RCS files.


\section{Listing the changes}

To list the changes that have been made to the current version
of \SACLIB/, I wrote the script {\tt slist}, that takes one
argument chosen from {\tt algo}, {\tt bug}, {\tt del}, {\tt
new}.
For instance, {\tt slist new} will list the names of all new
files.

Finally, when a new version number is given to \SACLIB/, don't
forget to modify \verb|$saclib/src/external.c|, where the
version number is defined.


\section*{Appendix: quick reference}

\medskip

\begin{tabbing}
XXXXXXXX \= \kill
{\tt mkdesc} \> Creates the file \verb|$saclib/doc/desc.doc|. \\[1em]
{\tt mklib \argu{lib}} \> Recompiles the libraries
         \verb|$saclib/lib/saclib[do].a|. \\
	 \> \argu{lib} is one of {\tt all}, {\tt deb}, {\tt opt}. \\[1em]
{\tt mkmake} \> Creates the files \verb|$saclib/lib/obj[do]/makefile|. \\[1em]
{\tt mkproto} \> Creates the file \verb|$saclib/include/sacproto.h|.\\[1em]
{\tt sci} \argu{filename} \argu{state} \argu{author}\\
 \> Checks in a revision of \argu{filename} modified by \argu{author}.\\
 \> \argu{state} is one of {\tt algo}, {\tt bug}, {\tt embe},
                {\tt init}, {\tt new}, {\tt typo}, {\tt spec}. \\[1em]
{\tt slist} \argu{type} 
\> Lists changes.  \argu{type} is one of {\tt algo}, {\tt bug},
{\tt del}, {\tt new}. \\[1em]
{\tt slog} \argu{filename} [\argu{ver}]\\
 \> Displays revision history of \argu{filename}.  If the
optional argument \argu{ver}\\
 \> is given, displays version \argu{ver} of \argu{filename}.
\end{tabbing}



\end{document}
