%% Oh Emacs, this is a -*- Makefile -*-, so give me tabs.
\documentclass{article}
\usepackage{axiom}

\title{\File{src/Makefile}}
\author{Timothy Daly \and Gabriel Dos~Reis}

\begin{document}
\maketitle

\begin{abstract}
\end{abstract}
\eject

\tableofcontents
\eject

\section{Directory overview}

\subsection{Environment variables}

These variables are used to drive the make, make document, and
make clean processes, respectively.

There is a partial order of the directories which is not apparent.

The [[boot]] must occur first as it builds the boot language
compiler and the [[bootsys]] image.

The [[interp]] must come second because it builds the interpreter
and the [[interpsys]] image, which is the basic algebra engine.

The [[share]] must occur before the [[algebra]] because it
needs to put the databases in the proper location.

The [[algebra]] comes next. It contains the source code for all
of the algebra that Axiom knows.

The [[etc]] must occur after the [[algebra]] because it
builds the databases from all of the [[*.NRLIB]] directories
constructed by [[algebra]].

The [[input]] needs to occur last because it tests
various other parts of the system.

The [[SUBDIRS]] variable is a list of directory targets.
Since this varies from system to system it has been lifted
up to the top level [[configure.ac.pamphlet]]. If you add a new
stanza to this Makefile you should check that list.
<<environment>>=

SUBDIRS = @axiom_src_subdirs@
@

\subsection{The \File{scripts/} directory}

The {\bf scripts} directory contains shell scripts that we use
to simplify system builds. They are generally either generated by
[[confiugure]], or directly copied to the final directory.   We might
want to revisit that design point.

\subsection{The \File{clef/} directory}

The {\bf clef} directory contains an Axiom command that works similar
to GNU Readline.
<<clefdir>>=
all-clef: all-lib
	@$(mkinstalldirs) $(axiom_target_bindir)
	cd clef && ${MAKE}
@

\subsection{The \File{sman/} directory}

Superman (\Tool{sman}) is the master process that runs all of the other
processes including \Tool{axiom}, \Tool{clef}, nagman, graphics, and hyperdoc
<<smandir>>=
all-sman: all-lib
	$(mkinstalldirs) $(axiom_target_bindir)
	$(mkinstalldirs) $(axiom_target_libdir)
	cd sman && ${MAKE}
@

\subsection{The \File{hyper/} directory}

Hyperdoc is the Axiom document browser.
<<hyperdir>>=
util-ht:
	$(mkinstalldirs) $(axiom_target_datadir)
	cd hyper && ${MAKE} util-ht

all-hyper: all-lib
	$(mkinstalldirs) $(axiom_target_bindir)
	$(mkinstalldirs) $(axiom_target_datadir)
	cd hyper && ${MAKE}
@

\subsection{The \File{share/} directory}

The \File{share/} directory files that are shared by all version of the
system.

<<sharedir>>=
all-share:
	$(mkinstalldirs) $(axiom_target_libdir)
	cd share && ${MAKE}
@

\subsection{The \File{paste/} directory}

<<pastedir>>=
all-paste: all-axiomsys all-hyper all-sman all-graph
	cd paste && ${MAKE}
@

\subsection{The \File{booklets/} directory}

The \File{booklets/} directory contains pamphlet files that document
Axiom at a "higher level" than any particular pamphlet file. Booklets
can be stand-alone descriptions (e.g. the Rosetta.pamphlet),
top-down slices thru the system (e.g. the Integration.pamphlet),
or horizontal slices thru the system (e.g. the Matrix.pamphlet).
<<bookletsdir>>=
all-book:
	cd booklets && ${MAKE}
@

\subsection{The \File{lib/} directory}

The \File{lib/} directory is used to build \File{libspad.a} which
contains C code for extending the underlying Common Lisp systems.
It is built early in the process of system building because we
need to make {\bf libspad.a} before we make Lisp image we use.

<<libdir>>=
all-lib:
	@cd lib && ${MAKE}
@

\subsection{The \File{boot/} directory}

Axiom is built in layers. The first layer is contructed into
an image called \Tool{bootsys}. The \Tool{bootsys} image is used
to translate Boot code to Common Lisp code. Since a Boot coded
interpreter is needed to translate the code for the Boot coded
interpreter we have a "boot-strapping" problem. In order to get
the whole process to start we need certain files kept in
common lisp form. This directory contains those files.

<<bootdir>>=
all-boot: all-lisp
	@cd boot && ${MAKE}
@

\subsection{The \File{interp/} directory}

Once \Tool{bootsys} exists we need to build \Tool{depsys}
and \Tool{interpsys}. Since these two images share a lot of
files they are built in the interp subdirectory using the
same Makefile.
<<interpdir>>=
all-interpsys: all-boot
	@echo 25 making interp
	cd interp && ${MAKE} all-interpsys

all-axiomsys: all-asq
	cd interp && $(MAKE) all-axiomsys
@

\subsection{The \File{algebra/} directory}

The algebra directory contains code written in Axiom's computer
algebra language called {\bf spad}. There are two compilers for
this language, the spad compiler and the {\bf Aldor}\cite{1} compiler.

Both of these compilers accept the same input language except for
some platform-dependent differences. The spad compiler is written
in Common Lisp (well, in boot, anyway) and is built into the
interpreter. The Aldor compiler is written in C and runs
stand-alone. Both compile files that will run in Axiom's
interpreter. Files which end in ``.spad'' use the internal
spad compiler. Files which end in ``.as'' use the external
Aldor compiler.

\subsection{The \File{lisp/} directory}

We need a fresh Lisp image to use for building the Boot translator,
the \Tool{Axiom} interpreter and compiler.

<<lispdir>>=
all-lisp: all-lib
	cd lisp && $(MAKE) all-lisp
@


\subsubsection{Making the Makefile}

The main body of the algebra Makefile is extracted from the
Makefile.pamphlet file as usual. It contains generic rules for
making all the .spad files in a series of ``layers'' such that
each layer depends on only those layers that preceed it, beginning
with the bootstap layer. Because the individual .spad files are
grouped into higher-level algebra pamphlet files, the rules for
extracting them are derived from a simple script [[findAlgebraFiles]] which
appends these additional rules to the Makefile.

The [[src/algebra/Makefile]] is specially constructed in two
steps. The first step uses the [[document]] command to extract
the normal Makefile information.

The second step is to extend the [[src/algebra/Makefile]] with
stanzas that describe the steps to extract the algebra from the
[[src/algebra/*.pamphlet]] files into the [[int/algebra/*.spad]] files.
Further details are provided in [[src/algebra/Makefile.dvi]] file.

<<algebradir>>=
all-algebra: all-interpsys all-share util-ht
	@ echo 30b running find-algebra-files
	(cd $(srcdir)/algebra; \
	  . ../scripts/find-algebra-files) \
	    > algebra/tmp-extract-spad.mk
	$(srcdir)/../config/move-if-change \
	   algebra/tmp-extract-spad.mk algebra/extract-spad.mk
	cd algebra && ${MAKE}
@

\subsection{The \File{input/} directory}

The \File{input/} directory contains code used for examples, regression
testing, and bug tracking. In a shipped system the working examples
are collected and documented so a user can learn how to use Axiom's
many domains and packages.

During development the input files can be used for tracking bugs
and testing fixes of known bugs. Once a bug is fixed it is moved
to the regression test set.

Prior to building a shippable system all of the input files are
run with the example code and the regression test code. Regression
test input files are compared against known good results to ensure
that nothing has been broken in the process of fixing bugs.

<<inputdir>>=
all-input: all-axiomsys
	cd input && ${MAKE}
@

\subsection{The \File{etc/} directory}

The \File{etc/} directory contains code used as tools surrounding \Tool{Axiom}.

The \Tool{asq} \cite{2} command, contained in this directory, is useful
for finding detailed information about domains, packages, and
categories from the shell without running Axiom.
<<etcdir>>=
all-asq: all-algebra
	cd etc && ${MAKE}
@

\subsection{The \File{doc/} directory}
The \File{doc/} directory contains code used for documenting Axiom.

<<docdir>>=
all-doc:
	cd doc && ${MAKE}
@

\subsection{The \File{graph/} directory}

<<graphdir>>=
all-graph: all-lib
	cd graph && ${MAKE}
@


\section{The Makefile}
This Makefile gets called by the {\bf libdir} stanza is executed to
build {\bf libspad.a} which contains code needed by the underlying lisp.

The second call will execute the {\bf all} stanza. This stanza walks
all of the lower level directories.
<<*>>=

<<environment>>

pamphlets = Makefile.pamphlet

subdir = src/

.PHONY: all all-ax all-src all-clef all-sman

all: all-ax

all-ax all-src: stamp
	@echo finished $(builddir)

stamp: @axiom_src_all@
	-rm -f stamp
	$(STAMP) stamp

<<clefdir>>
<<smandir>>
<<hyperdir>>
<<sharedir>>
<<pastedir>>
<<docdir>>
<<bookletsdir>>
<<libdir>>
<<lispdir>>
<<bootdir>>
<<interpdir>>
<<algebradir>>
<<inputdir>>
<<etcdir>>
<<graphdir>>

mostlyclean-local:
	-rm -f stamp

clean-local: mostlyclean-local

distclean-local: clean-local

@
\eject
\begin{thebibliography}{99}
\bibitem{1} Watt, Stephen, The Aldor compiler, {\bf www.aldor.org}
\bibitem{2} \$AXIOM/src/etc/asq.c.pamphlet
\bibitem{3} \$AXIOM/src/clef/edible.c.pamphlet
\end{thebibliography}
\end{document}
