Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 561 lines (452 sloc) 25.307 kb
8ca0a6d @daly 20081221 tpd src/axiom-website/patches.html 20081221.01.tpd.patch
authored
1 "What matters the most is what you do for free" -- John Gorka
2
8e534f8 20090212 tpd src/interp/format.boot move sayExample, cleanupLine
root authored
3 "...even more important, for the progress of mathematics in the computer
4 age, is the beaver, who will build the needed infrastructure of computer
5 mathematics, that would eventually enable us to solve many outstanding
6 open problems, and many new ones. Consequently, the developers of computer
7 algebra systems, and creators of algorithms, are even more important than
8 both birds and frogs." --Doron Zeilberger
9 (http://www.math.rutgers.edu/~zeilberg/Opinion95.html)
10
11
12
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
13 You've unpacked the Axiom source code to some directory. In this
14 document we'll call that directory /home/me/axiom. Note that the path
15 cannot contain uppercase characters or spaces. This is a porting
16 limitation as not all systems can handle dual case characters.
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
17
18 =======================================================================
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
19 ================= MAKING AXIOM ========================================
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
20 =======================================================================
21
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
22 Axiom builds a system-specific version based on a string we'll call
23 the SYSNAME. Currently recognized SYSNAME strings can be found on the
24 Axiom website at:
25 <http://axiom.axiom-developer.org/axiom-website/download.html>
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
26
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
27 Replace SYSNAME below with the likely name of your system.
28
29 We also assume that you downloaded AXIOM to someplace. Suppose
30 that place is /home/me/axiom, then:
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
31
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
32 cd /home/me/axiom << where you unpacked the sources
33 export AXIOM=/home/me/axiom/mnt/SYSNAME << which axiom to build
34 export PATH=$AXIOM/bin:$PATH
35 make << build the system
36
37 A system build takes 2+ hours at 2Ghz machine.
38
39 A recent cause of likely build failures is SELinux.
40 See the faq file for possible solutions.
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
41
42 When the make completes you'll have an executable called $AXIOM/bin/axiom
43
44 =======================================================================
45 ================= INSTALLING AXIOM ====================================
46 =======================================================================
47
48 You can install Axiom on your system by typing (as root):
49
50 make install
51
52 This will put Axiom into /usr/local/axiom
53 and the axiom command in /usr/local/bin/axiom
54
55 You can change these defaults to anything thus:
56
57 make INSTALL=/home/me/myaxiom COMMAND=/home/me/bin/myaxiom install
58
59
60 =====================================================================
61
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
62 Documentation can be found at various places in the system or on the
63 Axiom website: <http://axiom.axiom-developer.org>
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
64
65 There is a book (available on Amazon.com):
66 Jenks, Richard D. and Sutor, Robert S. "Axiom, The Scientific Computation
67 System" Springer-Verlag, NY, 1992, ISBN 0-387-97855-0
68
69 The book is automatically built as part of the make and lives in:
70
71 (yourpath)/axiom/mnt/linux/doc/book.dvi
72
73 In general every directory will contain a Makefile.dvi file.
74 These files document facts about how Axiom is built.
75 The directory mnt/linux/doc will contain .dvi files as they are written.
76
77 Axiom is free and open source software. It is copyrighted code that
78 is released under the Modified BSD license. Much debate about this
79 topic has already been archived on the axiom-legal and axiom-developer
80 mailing lists. The mail archives are available at the Axiom website:
81 http://savannah.gnu.org/projects/axiom
82
83
84 Questions and comments should be sent to:
85 axiom-developer@nongnu.org
86
87 Tim Daly
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
88 daly@axiom-developer.org
89
90 =====================================================================
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
91
92 Philosophy
93
94 Scratchpad was a large, general purpose computer algebra system that
95 was originally developed by IBM under the direction of Richard Jenks.
96 The project started in 1971 and evolved slowly. Barry Trager was key
97 to the technical direction of the project. Scratchpad developed over a
98 20 year stretch and was basically considered as a research platform
99 for developing new ideas in computational mathematics. In the 1990s,
100 as IBM's fortunes slid, the Scratchpad project was renamed to Axiom,
101 sold to the Numerical Algorithms Group (NAG) in England and became a
102 commercial system. As part of the Scratchpad project at IBM in
103 Yorktown I worked on all aspects of the system and eventually helped
104 transfer the product to NAG. For a variety of reasons it never became
105 a financial success and NAG withdrew it from the market in October,
106 2001.
107
108 NAG agreed to release Axiom as free software. The basic motivation was
109 that Axiom represents something different from other programs in a lot
110 of ways. Primarily because of its foundation in mathematics the Axiom
111 system will potentially be useful 30 years from now. In its current
112 state it represents about 30 years and 300 man-years of research
113 work. To strive to keep such a large collection of knowledge alive
114 seems a worthwhile goal.
115
116 However, keeping Axiom alive means more than just taking the source
117 code and dumping it onto a public server. There are a lot of things
118 about the system that need to change if it is going to survive and
119 thrive for the next 30 years.
120
121 The system is complex and difficult to build. There are few people who
122 know how it is structured and why it is structured that way. Somehow
123 it needs to be documented deeply so others can contribute.
124
125 The mathematics is difficult. Unlike other free software you can't
126 just reach for the old saying ``read the source code''. The source
127 code is plain, clear and about as close to the mathematical theory as
128 is practical. Unfortunately the mathematical theory is enshrined in
129 some research library where few people will have access. Somehow this
130 must change. The research work, the mathematics, the published papers,
131 and the source code have all got to be kept together for the next
132 generation to read, understand and modify.
133
134 The mathematics is narrow and very focused. This was due to the fact
135 that, while Axiom is a great research platform, we only had a limited
136 number of visitors at IBM Research. So there is very little in the way
137 of, say, infinite group theory in Axiom. We can add it. Doing so will
138 show up shortcomings in the system. For example, how do you represent
139 an infinite object? There are many possible representations and they
140 depend on your goals. The system will have to change, expand, and,
141 hopefully, become cleaner as more thought is applied. Scratchpad
142 changed continuously while it was being used for research and we
143 expect Axiom to do the same.
144
145 The language (spad and/or aldor) is designed to let you write
146 algorithms that are very close to the mathematics. However, the
147 algorithms as presented in the current system have never been shown or
148 proven (an important distinction) to be correct. It is vital that we
149 undertake the huge effort of verifying and validating the code. How
150 else can we trust the results and of what use is a system this complex
151 without trust? Somehow we have to extend the system to integrate
152 program proof techniques. That is, we have to make computational
153 mathematics hold to the same standard as the rest of mathematics.
154
155 All of which seems to integrate into a requirement for better
156 documentation. The key change which developers of Axiom will find with
157 this version is that the documentation is primary and the code is
158 secondary. Taking direction from Knuth and Dijkstra the system is now
159 in a literate programming style. The hope is that the next generation
160 of developers and users will be able to understand, maintain and
161 extend the system gracefully. And that eventually papers submitted to
162 journals (an Axiom Journal?) will be easily imported into the system
163 with their running code made available automatically.
164
165 There is no guarantee that this attempt to change the culture of
166 computational mathematicians is going to succeed. But it is our firm
167 belief that current systems have reached a complexity plateau and we
168 need to find new techniques to push the envelope.
169
170 In general, we need to consider changes to the system with a 30 year
171 horizon rather than the current write-ship-debug mentality of software
172 development. This is, after all, mathematics, the queen of the
173 sciences. It deserves all of the time, talent and attention we can
174 bring to bear on the subject.
175
176 Tim Daly -- September 3, 2002
177
178 Contributions
179
180 All of these people have, in some way or other, been associated with
181 Scratchpad and Axiom. If you contribute, add your name. The names are
182 in alphabetical order as we make no attempt to quantify the relative
183 merit of the contributions.
184
185 In src/interp/setq.lisp.pamphlet is a variable called credits
186 which contains this list. Typing
187 )credits
188 at the axiom command prompt will prettyprint the list.
189
a893017 @daly 20081124 tpd src/interp/setq.lisp remove date information for releases
authored
190 "An alphabetical listing of contributors to AXIOM:"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
191 "Cyril Alberga Roy Adler Christian Aistleitner"
192 "Richard Anderson George Andrews S.J. Atkins"
193 "Henry Baker Stephen Balzac Yurij Baransky"
194 "David R. Barton Gerald Baumgartner Gilbert Baumslag"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
195 "Jay Belanger David Bindel Fred Blair"
196 "Vladimir Bondarenko Mark Botch"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
197 "Alexandre Bouyer Peter A. Broadbery Martin Brock"
198 "Manuel Bronstein Florian Bundschuh Luanne Burns"
199 "William Burge"
200 "Quentin Carpent Robert Caviness Bruce Char"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
201 "Ondrej Certik Cheekai Chin David V. Chudnovsky"
202 "Gregory V. Chudnovsky Josh Cohen Christophe Conil"
203 "Don Coppersmith George Corliss Robert Corless"
204 "Gary Cornell Meino Cramer Claire Di Crescenzo"
205 "David Cyganski"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
206 "Timothy Daly Sr. Timothy Daly Jr. James H. Davenport"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
207 "Didier Deshommes Michael Dewar"
208 "Jean Della Dora Gabriel Dos Reis Claire DiCrescendo"
209 "Sam Dooley Lionel Ducos Martin Dunstan"
210 "Brian Dupee Dominique Duval"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
211 "Robert Edwards Heow Eide-Goodman Lars Erickson"
212 "Richard Fateman Bertfried Fauser Stuart Feldman"
213 "Brian Ford Albrecht Fortenbacher George Frances"
214 "Constantine Frangos Timothy Freeman Korrinn Fu"
215 "Marc Gaetano Rudiger Gebauer Kathy Gerber"
a13c911 @daly 20080704 tpd readme add Samantha Goldrich to credits
authored
216 "Patricia Gianni Samantha Goldrich Holger Gollan"
217 "Teresa Gomez-Diaz Laureano Gonzalez-Vega Stephen Gortler"
218 "Johannes Grabmeier Matt Grayson Klaus Ebbe Grue"
219 "James Griesmer Vladimir Grinberg Oswald Gschnitzer"
220 "Jocelyn Guidry"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
221 "Steve Hague Satoshi Hamaguchi Mike Hansen"
222 "Richard Harke Vilya Harvey Martin Hassner"
63e5f15 @invalid-email-address 20080529 tpd setq.lisp add Dan Hatton to credits
invalid-email-address authored
223 "Arthur S. Hathaway Dan Hatton Waldek Hebisch"
54db6b7 @daly 20081201 tpd src/axiom-website/patches.html 20081201.03.tpd.patch
authored
224 "Karl Hegbloom Ralf Hemmecke Henderson"
225 "Antoine Hersen Gernot Hueber"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
226 "Pietro Iglio"
f701f59 @daly 20081105 tpd src/input/Makefile reclos2.input added
authored
227 "Alejandro Jakubi Richard Jenks"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
228 "Kai Kaminski Grant Keady Tony Kennedy"
229 "Paul Kosinski Klaus Kusche Bernhard Kutzler"
ca3b36c @daly 20081205 tpd src/axiom-website/patches.html 20081205.02.tpd.patch
authored
230 "Tim Lahey Larry Lambe Franz Lehner"
231 "Frederic Lehobey Michel Levaud Howard Levy"
232 "Liu Xiaojun Rudiger Loos Michael Lucks"
233 "Richard Luczak"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
234 "Camm Maguire Francois Maltey Alasdair McAndrew"
235 "Bob McElrath Michael McGettrick Ian Meikle"
236 "David Mentre Victor S. Miller Gerard Milmeister"
237 "Mohammed Mobarak H. Michael Moeller Michael Monagan"
238 "Marc Moreno-Maza Scott Morrison Joel Moses"
239 "Mark Murray"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
240 "William Naylor C. Andrew Neff John Nelder"
241 "Godfrey Nolan Arthur Norman Jinzhong Niu"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
242 "Michael O'Connor Summat Oemrawsingh Kostas Oikonomou"
243 "Humberto Ortiz-Zuazaga"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
244 "Julian A. Padget Bill Page Susan Pelzel"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
245 "Michel Petitot Didier Pinchon Ayal Pinkus"
246 "Jose Alfredo Portes"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
247 "Claude Quitte"
d9cd78f @daly 20080619 tpd readme add Anatoly Raportirenko
authored
248 "Arthur C. Ralfs Norman Ramsey Anatoly Raportirenko"
249 "Michael Richardson Renaud Rioboo Jean Rivlin"
250 "Nicolas Robidoux Simon Robinson Raymond Rogers"
251 "Michael Rothstein Martin Rubey"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
252 "Philip Santas Alfred Scheerhorn William Schelter"
253 "Gerhard Schneider Martin Schoenert Marshall Schor"
254 "Frithjof Schulze Fritz Schwarz Nick Simicich"
255 "William Sit Elena Smirnova Jonathan Steinbach"
7ab20d7 @daly 20080818 tpd src/input/Makefile biquat.input added
authored
256 "Fabio Stumbo Christine Sundaresan Robert Sutor"
257 "Moss E. Sweedler Eugene Surowitz"
9edeec6 @invalid-email-address 20080409 tpd readme add Max Tegmark
invalid-email-address authored
258 "Max Tegmark James Thatcher Balbir Thomas"
259 "Mike Thomas Dylan Thurston Barry Trager"
260 "Themos T. Tsikas"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
261 "Gregory Vanuxem"
262 "Bernhard Wall Stephen Watt Jaap Weel"
263 "Juergen Weiss M. Weller Mark Wegman"
264 "James Wen Thorsten Werther Michael Wester"
265 "John M. Wiley Berhard Will Clifton J. Williamson"
266 "Stephen Wilson Shmuel Winograd Robert Wisbauer"
267 "Sandra Wityak Waldemar Wiwianka Knut Wolf"
268 "Clifford Yapp David Yun"
0f97824 @invalid-email-address 20070721 tpd src/interp/setq.lisp update contributor name list
invalid-email-address authored
269 "Vadim Zhytnikov Richard Zippel Evelyn Zoernack"
270 "Bruno Zuercher Dan Zwillinger"
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
271
272 Pervasive Literate Programming
273
274 I think David Diamond said it best (Datamation, June 1976, pg 134):
275
276 The fellow who designed it is working far away.
277 The spec's not been updated for many a livelong day.
278 The guy who implemented it is promoted up the line.
279 And some of the enhancements didn't match to the design.
280 They haven't kept the flowcharts, the manual's a mess.
281 And most of what you need to know, you'll simply have to guess.
282
283 and with respect to Axiom:
284
285 The research that it's based on is no longer to be had.
286 And the theory that it's based on has changed by just a tad.
287 If we keep it all together then at least there is a hope.
288 That the people who maintain it will have a chance to cope.
289
290 To quote Fred Brooks, "The Mythical Man-month"
291
292 "A basic principle of data processing teaches the folly of trying to
293 maintain independent files in synchronization... Yet our practice in
294 programming documentation violates our own teaching. We typically
295 attempt to maintain a machine-readable form of a program and an
296 independent set of human-readable documentation, consisting of prose
297 and flowcharts ... The solution, I think, is to merge the files, to
298 incorporate the documentation in the source program."
299
300 As you can already see from this document the whole of the Axiom
301 effort is structured around literate programs. Every directory has a
302 Makefile.pamphlet file which explains details of that directory. The
303 whole source tree hangs from the Makefile tree. (Some of the
304 Makefile.pamphlet files contain only text if executable code is not
305 needed). Every source file is embedded in a pamphlet file.
306
307 Which begs the question: ``What is a pamphlet file?''. Basically it
308 is a tex document with some additional markup tags that surround
309 source code. Pamphlet files are intended to document one particular
310 subject. Pamphlet files can be later combined into ``booklet'' files
311 as one would embed chapters into books.
312
313 Which begs the question: ``Why bother with pamphlet files?''. Clearly
314 you didn't read the philosophy rant above. In more detail there have
315 been two traditional methods of documenting source code. The first is
316 to sprinkle random comments into the code. This suffers from the
317 problem that the comments assume you already understand the purpose of
318 the code and why an enlightened comment like ``This oughta work'' is
319 perfectly clear and compelling. The second method is to write a
320 document as a separate file. They get written half-heartedly because
321 the lack of source code allows you to skip over explaining ugly
322 implementation details (where all of the real confusion lies). This
323 form of documentation never gets updated and gradually becomes
324 uninteresting history.
325
326 Pamphlet files overcome neither of these limitations if you don't make
327 the effort to do it right. Ask yourself the question ``What would
328 Knuth do?'' or ``Will this be clear 30 years from now?''.
329
330 Which begs the question: ``Why go to all this trouble?''. Because
331 you're having a conversation with people who are far removed from you
332 in time, space, and understanding. Because someone else will have to
333 maintain your code. Because you are part of a community of
334 mathematicians who hold you to high standards. Because if you can't
335 explain it clearly maybe YOU don't understand it or it isn't as clear
336 as you think it is.
337
338 Tools, tools, tools
339
340 noweb, The Literate Programming Tool
341
342 Literate programs are a combination of documentation and source code
343 kept in a pamphlet file. There have to be tools to deconstruct the
344 pamphlet into useable components. At the current time we are using a
345 system called noweb that was developed by Norman Ramsey. The source
346 code for noweb is in the zips directory. You can uncompress it,
347 compile it, and install it into the Axiom executable directory by
348 typing:
349
350 make noweb
351
352 By default, if the noweb directory does not exist it will
353 be built as needed simply typing:
354
355 make
356
357 Every directory contains a Makefile.pamphlet and typing:
358
359 document Makefile
360
361 will expand into the Makefile for that directory (note that we skip
362 the ``.pamphlet'' suffix). Thus you should never modify the Makefile
363 directly (nor any source file) as the document command will overwrite
364 the sources. The Makefile has four primary responsibilities. It needs
365 to explain everything about this directory and the files under its
366 control. It needs to set up target directories so the Makefiles in
367 the subdirectories can expect them. It needs to build all of the files
368 in the current directory into their target directories. It needs to
369 set up the environment and walk the subtree of directories beneath it
370 so they can do their job.
371
372 The document command
373
374 The document has the syntax:
375
376 document [ -o redirect ] pamphlet
377
378 where the redirect file can be any name where the output can go. The
379 pamphlet file is the name of the file without the .pamphlet
380 suffix. The document command supplies this. Thus to document
381 Makefile.pamphlet type:
382
383 document Makefile
384
385 ADVI, The DVI viewer
386
387 The advi software is the result of the Active-DVI project. It
388 is intended to expand the abilities found in DVI files. It has
389 been adopted as the standard Axiom DVI viewer.
390
391 The source code is in the zips directory.
392
393 Future Tool Directions
394
395 Lets imagine that we'd like to receive a pamphlet file from a
396 colleague. It contains a new theory and spiffy new algorithm. We'd
397 like to be able to put the pamphlet file into the system and have
398 everything magically happen to integrate the new pamphlet into the
399 system. What would that imply? Well, lets assume that the pamphlet
400 file has certain required sections. We'd like to get more than the
401 technical paper and the code. We'd also like to see the help
402 information, test cases, example code, cross-references to other
403 pamphlets that would get automatically included, have the proof
404 available and automatically checkable, etc. In the best of all
405 possible worlds we have a front-end system that knows nothing except
406 how to deconstruct and integrate properly formed pamphlet files. If
407 this were true we could be sure that all of the mathematics is
408 documented and external to the system. There are no ``rabbits'' (as
409 Dijkstra called surprises or special knowledge) that we pull out of
410 our hat. Conceptually, given an underlying Lisp system, it is clear we
411 can built such a system.
412
413 The General Directory Structure
414
415 The Top Level directory structure contains 7 directories which are
416 explained in detail below. Three of the directories (license, zips,
417 and lsp) are not part of the essential core of Axiom.
418
419 The other four directories (src, int, obj, and mnt) comprise the
420 system build environment. Each directory has a specific purpose. Lets
421 look at the essential directories first.
422
423 $AXIOM
424 license
425 lsp
426 CCL
427 GCL
428 CMUCL
429 src
430 include
431 lib
432 scripts
433 int
434 doc
435 obj
436 tmp
437 noweb
438 SYS=(linux,...)
439 mnt
440 SYS=(linux,...)
441 zips
442
443 The src directory consists of human-written, system-independent
444 code. You can copy this directory (and the top-level makefiles) and
445 have a complete build system. Nothing in this directory is ever
446 changed by the Makefiles and it can be mounted in a read-only fashion
447 during the build process. An example file would be the lisp source
448 files.
449
450 The int directory consists of machine-generated, system-independent
451 code. Consider this directory as a cache. Nothing in this directory is
452 necessary for a clean system build but once the build completes the
453 information in this directory can significantly shorten rebuilds.
454 Since this information is system-independent we can use the cache no
455 matter what architecture we target. An example file would be the dvi
456 files generated from the tex sources.
457
458 The obj directory consists of machine-generated, system-dependent
459 code. This directory is "scratch" space for the compiler and other
460 tools. Nothing in this directory is useful once the system is
461 built. An example file would be the .o files from the C compiler.
462
463 The mnt directory consists of machine-generated, system-dependent code
464 that will comprise the "shipped system". You can copy this directory
465 and have a complete, running Axiom system. If the end user will see it
466 or need it in any way it belongs here. Executables are generally built
467 in obj and moved here. Example files would be the final executable
468 images, the input files, etc.
469
470 The four directories above make it possible to do a system build for
471 one system (say, a linux system) which will fill in the int
472 subdirectory. Then you can NFS mount the src and int directories
473 read-only on a Solaris machine and do a solaris system build. The
474 original Axiom could build across many different architectures,
475 compilers, and operating systems.
476
477 The license directory
478
479 The license directory collects all of the licenses for material that
480 is included in this distribution. Source files contain a line that
481 refers to one of these license files. Some people are of the belief
482 that including the full license text in every source file magically
483 strengthens the license but this is not so. Imagine including the
484 full text of the copyright at the beginning of every section of a book.
485
486 The LICENSE.AXIOM file is a Modified BSD-style license that covers all
487 of the files released as part of this distribution except as noted in
488 particular files. Copyright information that might have shown up in
489 source files that were released from NAG are also collected here and
490 noted at the top of the files they cover.
491
492 The zips directory
493
494 The zips directory contains particular distributions of
495 network-available software that is known to work with this release of
496 Axiom. Newer versions may work and, if so, should be added to this
497 directory. The makefiles that handle these files will unpack them into
498 the correct locations in the src directory tree. These files exist to
499 increase the stability of the distribution so we can guarantee that
500 the code works. We encourage testing the latest distributions so that
501 we can remain with the leading edge and give feedback to the
502 individual package developers if problems arise.
503
504 The lsp directory
505
506 Axiom lives on top of Common Lisp. There are 3 distributions of Common
507 Lisp that have had Axiom builds in the past. Axiom was initially built
508 on the CMUCL (Carnegie Mellon University Common Lisp) distribution but
509 was quickly moved to AKCL (Austin Kyoto Common Lisp), now GCL (GNU
510 Common Lisp). When Axiom became a commercial product it was
511 distributed on CCL (Codemist Common Lisp). We plan to build on each
512 of these three distributions for several reasons. First, it gives us
513 cleaner, more vanilla code as we get feedback from each
514 implementation. Second, it gives us better facilities on different
515 platforms. GCL, for example, has an MPI (Message Passing Interface)
516 extension for parallel processing. Third, it gives us portability (CCL
517 is byte-coded and runs everywhere). Fourth, it gives us performance
518 (CMUCL is known for its optimizations, GCL compiles to optimized C and
519 has special declarations).
520
521 The lsp directory splits into 3 subdirectories, the CCL, GCL and CMUCL
522 directories. Each of these builds an executable into the final shipped
523 image (depending on which lisp is chosen at build time).
524
525 Steps to build Axiom
526
527 The Initial Distribution files
528
529 The initial distribution contains several top level files. These are:
530
531 1) Makefile.pamphlet
532 This is the noweb source for the Makefile file. All changes to
533 the Makefile should occur here and the
534
535 document Makefile
536
537 command should be rerun to recreate the Makefile. This also
538 contains the detailed explanation of the files and directories as well as
539 some initial comments on how to put the system together.
540
541 2) Makefile.dvi
542 This is the detailed explanation of the Makefile file. It will be
543 generated from the Makefile.pamphlet file when the build starts.
544
545 3) Makefile This is the actual Makefile that will create Axiom.
546
547 In general the distribution will contain the pamphlet files for each
548 source file and the source file itself. Modifications should be made
549 and explained in the pamphlet files. The document command should be
550 run to rebuild the source file and the dvi file.
551
552 Steps in the build process
553
554 The sequence of steps necessary to build a clean Axiom is simply:
555
b901c69 @invalid-email-address 20080528 tpd configure rewrite
invalid-email-address authored
556 export AXIOM=(path-including-this-directory)/mnt/SYSNAME
9d9f0f4 @invalid-email-address merge CHANGELOG and changelog-downcase, fix readme
invalid-email-address authored
557 make
558
559 If this fails check the FAQ for possible problems and their fixes.
560
Something went wrong with that request. Please try again.