Initial population.

1 files changed, 309 insertions, 0 deletions

diff --git a/src/Makefile.pamphlet b/src/Makefile.pamphlet
new file mode 100644
index 00000000..1476f831
--- /dev/null
+++ b/src/Makefile.pamphlet
@@ -0,0 +1,309 @@
+%% 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:
+	$(mkinstalldirs) $(OUT)
+	@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
+	$(mkinstalldirs) $(axiom_build_bindir)
+	@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-depsys: all-boot
+	cd interp && $(MAKE) all-depsys
+
+all-interpsys: all-depsys all-lisp
+	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
+	$(mkinstalldirs) $(axiom_build_bindir)
+	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>>=
+ifeq (@axiom_use_x@,yes)
+all-algebra: all-interpsys all-share all-hyper
+else
+all-algebra: all-interpsys all-share
+endif
+	@ $(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>>
+
+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}