aboutsummaryrefslogtreecommitdiff
path: root/src/Makefile.pamphlet
blob: 060293713919a262b6e86cdf2f7710f0e37590ee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
%% 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{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>>
<<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}