%% 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. <>= 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 <>= all-sman: all-lib all-driver $(mkinstalldirs) $(axiom_target_bindir) $(mkinstalldirs) $(axiom_target_libdir) cd sman && ${MAKE} @ \subsection{The \File{hyper/} directory} Hyperdoc is the Axiom document browser. <>= 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. <>= all-share: $(mkinstalldirs) $(axiom_target_libdir) cd share && ${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. <>= 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. <>= all-boot: all-lisp @cd boot && $(MAKE) $@ @ \subsection{The \File{interp/} directory} Once \Tool{bootsys} exists we need to build \Tool{interpsys}. <>= all-interpsys: all-boot all-hyper-pre 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}. <>= 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. <>= all-algebra: all-interpsys all-share all-hyper-pre @ $(mkinstalldirs) algebra/strap cd algebra && ${MAKE} all-hyper-pre: all-lib cd hyper && $(MAKE) all-hyper-pre @ \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. <>= 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. <>= all-asq: all-hyper-post cd etc && ${MAKE} all-hyper-post: all-algebra cd hyper && $(MAKE) all-hyper-post @ \subsection{The \File{doc/} directory} The \File{doc/} directory contains code used for documenting Axiom. <>= all-doc: cd doc && ${MAKE} @ \subsection{The \File{graph/} directory} <>= 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-driver all: all-ax all-ax all-src: stamp @echo finished $(builddir) stamp: @axiom_src_all@ all-driver -rm -f stamp $(STAMP) stamp all-driver: @cd driver && $(MAKE) $@ <> <> <> <> <> <> <> <> <> <> <> <> <> .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}