path: root/src/Makefile.pamphlet

%% 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. 

\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>>=
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{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{interpsys}. 
<<interpdir>>=
ifeq (@axiom_use_x@,yes)
all-interpsys: all-boot all-hyper
else
all-interpsys: all-boot
endif
	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 local Lisp image, augmented with specific routines, to use for 
building the \Tool{Axiom} interpreter and compiler.  That Lisp image
comes from the local Lisp image used to initiate \Tool{bootsys}.

<<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 bootstrap 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.

<<algebradir>>=
all-algebra: all-interpsys all-share
	@ $(mkinstalldirs) algebra/strap
	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.
<<*>>=

pamphlets = Makefile.pamphlet

subdir = src/

SUBDIRS = @axiom_src_subdirs@

.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>>
<<docdir>>
<<bookletsdir>>
<<libdir>>
<<lispdir>>
<<bootdir>>
<<interpdir>>
<<algebradir>>
<<inputdir>>
<<etcdir>>
<<graphdir>>

.PHONY: all-check
all-check:
	cd input && $(MAKE) all-check

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}