# daly/axiom

Axiom is a free, open source computer algebra system
PostScript HTML Tcl TeX Common Lisp JavaScript
Latest commit b7fe892 Feb 21, 2017 books/bookvolbib add additional references
Goal: Proving Axiom Correct

\index{Dybjer, Peter}
\begin{chunk}{axiom.bib}
@inproceedings{Dybj90,
author = "Dybjer, Peter",
title = {Inductive Sets and Families in Marin-L\"of's Type Theory and
Their Set-Theoretic Semantics},
booktitle = "Proc. First Workshop on Logical Frameworks",
year = "1990",
"\url{http://www.cse.chalmers.se/~peterd/papers/Setsem\_Inductive.pdf}",
abstract =
"{Martin-L\"of}'s type theory is presented in several steps. The kernel
is a dependently typed $\lambda$-calculs. Then there are schemata for
inductive sets and families of sets and for primitive recursive functions
and families of functions. Finally, there are set formers (generic
polymorphism) and universes. At each step syntax, inference rules, and
set-theoretic sematics are given",
paper = "Dybj90.pdf"
}

\end{chunk}

\index{Goguen, Healfdene}
\index{McBride, Conor}
\index{McKinna, James}
\begin{chunk}{axiom.bib}
@article{Gogu06,
author = "Goguen, Healfdene and McBride, Conor and McKinna, James",
title = "Eliminating Dependent Pattern Matching",
year = "2006",
journal = "Lecture Notes in Computer Science",
volume = "4060",
pages = "521-540",
abstract =
"This paper gives a reduction-preserving translation from Coquand's
{\sl dependent pattern matching} into a traditional type theory
with universes, inductive types and relations and the axiom K. This
translation serves as a proof of termination for structurally
recursive pattern matching programs, provides an implementable
compilation technique in the style of functional programming languages,
and demonstrates the equivelence with a more easily understood type
theory.",
paper = "Gogu06.pdf"
}

\end{chunk}

\index{McBride, Conor}
\index{Goguen, Healfdene}
\index{McKinna, James}
\begin{chunk}{axiom.bib}
@article{Mcbr06,
author = "McBride, Conor and Goguen, Healfdene and McKinna, James",
title = "A Few Constructions on Constructors",
journal = "Lecture Notes in Computer Science",
volume = "3839",
pages = "186-200",
year = "2006",
abstract =
"We present four constructions for standard equipment which can be
generated for every inductive datatype: case analysis, structural
recursion, no confusion, acyclicity. Our constructions follow a
two-level approach -- they require less work than the standard
techniques which inspired them. Moreover, given a suitably
heterogeneous notion of equality, they extend without difficulty to
inductive families of datatypes. These constructions are vital
components of the translation from dependently typed programs in
pattern matching style to the equivalent programs expressed in terms
of induction principles and as such play a crucial behind-the-scenes
role in Epigram.",
paper = "Mcbr06.pdf"
}

\end{chunk}

\index{Bove, Ana}
\index{Dybjer, Peter}
\begin{chunk}{axiom.bib}
@misc{Bove08,
author = "Bove, Ana and Dybjer, Peter",
title = "Dependent Types at Work",
year = "2008",
comment = "Lecture notes from LerNET Summer School, Piriapolis",
"\url{http://www.cse.chalmers.se/~peterd/papers/DependentTypesAtWork.pdf}",
abstract =
"In these lecture notes we give an introduction to functional
programming with dependent types. We use the dependently typed
programming language Agda which is an extension of {Martin-L\"of} type
theory. First we show how to do simply typed functional programming in
the style of Haskell and ML. Some differences between Agda's type
system and the Hindley-Milner type system of Haskell and ML are also
discussed. Then we show how to use dependent types for programming and
we explain the basic ideas behind type-checking dependent types. We go
on to explain the Curry-Howard identification of propositions and
types. This is what makes Agda a programming logic and not only a
programming language. According to Curry-Howard, we identify programs
and proofs, something which is possible only by requiring that all
programs terminate. However, at the end of these notes we present a
method for encoding partial and general recursive functions as total
functions using dependent types.",
paper = "Bove08.pdf"
}

\end{chunk}

\index{Benke, Marcin}
\index{Dybjer, Peter}
\index{Jansson, Patrik}
\begin{chunk}{axiom.bib}
@article{Benk03,
author = "Benke, Marcin and Dybjer, Peter and Jansson, Patrik",
title = "Universes for generic programs and proofs in dependent type
theory",
journal = "Nordic Journal of Computing",
volume = "10",
year = "2003",
pages = "265-269",
abstract =
"We show how to write generic programs and proofs in {Martin L\"of}
type theory. To this end we considier several extensions of
{Martin-L\"of}'s logical framework for dependent types. Each extension
has a universe of codes (signatures) for inductively defined sets with
generic formation, introduction, elimination, and equality
rules. These extensions are modeled on Dybjer and Setzer's finitely
axiomatized theories of inductive-recursive definitions, which also
have universese of codes for sets, and generic formation,
introduction, elimination, and equality rules. Here we consider
several smaller universes of interest for generic programming and
universal algebra. We formalize one-sorted and many-sorted term
algebras, as well as iterated, generalized, parameterized, and indexed
inductive definitions. We also show how to extend the techniques of
generic programming to these universes. Furthermore, we give generic
proofs of reflexivity and substitutivity of a generic equality
test. Most of the definitions in the paper have been implemented using
the proof assistant Alfa for dependent type theory.",
paper = "Benk03.pdf"
}

\end{chunk}

\index{Martin-L\"of, Per}
\begin{chunk}{axiom.bib}
@misc{Mart80,
author = {Martin-L\"of, Per},
title = "Intuitionistic Type Theory",
year = "1980",
paper = "Mart80.pdf"
}

\end{chunk}

\index{Martin-L\"of, Per}
\begin{chunk}{axiom.bib}
@inproceedings{Mart85,
author = {Martin-L\"of, Per},
title = "Costructive Mathematics and Computer Programming",
booktitle = "Proc Royal Soc. of London on Math. Logic and Programming Lang.",
year = "1985",
isbn = "0-13-561465-1",
pages = "168-184",
publisher = "Prentice-Hall",
paper = "Mart85.pdf"
}

\end{chunk}

\index{Dybjer, Peter}
\index{Setzer, Anton}
\begin{chunk}{axiom.bib}
@article{Dybj03,
author = "Dybjer, Peter and Setzer, Anton",
title = "Induction-recursion and initial algebras",
journal = "Annals of Pure and Applied Logic",
volume = "124",
year = "2003",
pages = "1-47",
abstract =
"Induction-recursion is a powerful definition method in intuitionistic
type theory. It extends (generalized) inductive definitions and allows us
to define all standard sets of Martin-{L\"of} type theory as well as a
large collection of commonly occuring inductive data structures. It also
includes a variety of universes which are constructive analogues of
inaccessibles and other large cardinals below the first Mahlo cardinal.
In this article we give a new compact formalization of inductive-recursive
definnitions by modeling them as initial algebras in slice categories. We
give generic formation, introduction, elimination, and equality rules
generalizing the usual rules of type theory. Moreover, we prove that the
elimination and equality rules are equivalent to the principle of the
existence of initial algebras for certain endofunctors. We also show the
equivalence of the current formulation with the formulation of
induction-recursion as a reflection principle given in Dybjer and
Setzer (Lecture Notes in Comput. Sci. 2183 (2001) 93). Finally we discuss
two type-theoretic analogues of Mahlo cardinals in set theory: an external
Mahlo universe which is defined by induction-recursion and captured by our
formalization, and an internal Mahlo universe, which goes beyond induction-
recursion. We show that the external Mahlo universe, and therefore also
the theory of inductive-recursive definitions, have proof-theoretical
strength of at least Rathjen's theory KPM.",
paper = "Dybj03.pdf"
}

\end{chunk}
 Failed to load latest commit information. book Jan 4, 2015 books Feb 20, 2017 license Mar 25, 2016 lsp May 19, 2016 src Feb 20, 2017 zips May 19, 2016 Dockerfile Feb 14, 2015 Dockerfile.howto Feb 14, 2015 Makefile Jul 23, 2016 Makefile.pamphlet Jul 22, 2016 Xresource.txt Jul 27, 2016 axiom30yr.jpg May 19, 2007 axiomicon.png Jun 1, 2007 axiomlogo.jpg Jun 1, 2007 axiomsml.png Jun 1, 2007 changelog Feb 20, 2017 configure Jun 24, 2008 faq Nov 14, 2016 patch Feb 20, 2017 projects Jan 8, 2015 readme Feb 16, 2017

"What matters the most is what you do for free" -- John Gorka

"...even more important, for the progress of mathematics in the computer
age, is the beaver, who will build the needed infrastructure of computer
mathematics, that would eventually enable us to solve many outstanding
open problems, and many new ones. Consequently, the developers of computer
algebra systems, and creators of algorithms, are even more important than
both birds and frogs." --Doron Zeilberger
(http://www.math.rutgers.edu/~zeilberg/Opinion95.html)

Listening to computer scientists argue, it seems that the standards of
proof is I've had two beers and there is this anecdote about a tribe
in New Guinea from one of Scott Birkins books that seems to be applicable.

The debate is hindered by low standards of proof.

-- Greg Wilson "What We Actually Know About Software Development"
https://vimeo.com/9270320

You've unpacked the Axiom source code to some directory. In this
document we'll call that directory /home/me/axiom. Note that the path
cannot contain spaces.

=======================================================================
================= MAKING AXIOM ========================================
=======================================================================

Axiom builds a system-specific version based on a string we'll call
the SYSNAME. Currently recognized SYSNAME strings can be found on the
Axiom website at:

Replace SYSNAME below with the likely name of your system.

We also assume that you downloaded AXIOM to someplace. Suppose
that place is /home/me/axiom, then:

cd /home/me/axiom                         << where you unpacked the sources
export AXIOM=/home/me/axiom/mnt/SYSNAME   << which axiom to build
export PATH=$AXIOM/bin:$PATH
make                                      << build the system

A recent cause of likely build failures is SELinux.
See the faq file for possible solutions.

When the make completes you'll have an executable called $AXIOM/bin/axiom ======================================================================= ================= INSTALLING AXIOM ==================================== ======================================================================= You can install Axiom on your system by typing (as root): make install This will put Axiom into /usr/local/axiom and the axiom command in /usr/local/bin/axiom You can change these defaults to anything thus: make INSTALL=/home/me/myaxiom COMMAND=/home/me/bin/myaxiom install ===================================================================== Documentation can be found at various places in the system or on the Axiom website: <http://axiom.axiom-developer.org> There is a book (available on Amazon.com): Jenks, Richard D. and Sutor, Robert S. "Axiom, The Scientific Computation System" Springer-Verlag, NY, 1992, ISBN 0-387-97855-0 The book is automatically built as part of the make and lives in: (yourpath)/axiom/mnt/(sysname)/doc/bookvol0.pdf In general every directory will contain a Makefile.dvi file. These files document facts about how Axiom is built. The directory mnt/linux/doc will contain .dvi files as they are written. Axiom is free and open source software. It is copyrighted code that is released under the Modified BSD license. Much debate about this topic has already been archived on the axiom-legal and axiom-developer mailing lists. The mail archives are available at the Axiom website: http://savannah.gnu.org/projects/axiom For the purposes of copyright, Axiom is to be considered "Joint Work". Specifically: "A joint work is a work prepared by two or more individuals, with the intention that their separate contributions be merged into a single work. A joint author can also be an organization or a corporation under the definition of "work for hire." A person who has merely contributed ideas without actually documenting those ideas generally cannot be considered an author. Authors own the work jointly and equally, unless the authors make an agreement otherwise. Each joint author has the right to exercise any or all of the exclusive rights inherent in the joint work. Each author may: * Grant thirds parties permission to use the work on a nonexclusive basis without the consent of the other joint authors * Transfer his or her entire ownership interest to another person without the other joint author's consent * Update the work for his or her own purpose Additionally, each joint author must account to the other joint authors for any profits received from licensing their joint work." (http://copyright.universityofcalifornia.edu/ownership/joint-works.html) Questions and comments should be sent to: axiom-developer@nongnu.org Tim Daly daly@axiom-developer.org ===================================================================== Philosophy Scratchpad was a large, general purpose computer algebra system that was originally developed by IBM under the direction of Richard Jenks. The project started in 1971 and evolved slowly. Barry Trager was key to the technical direction of the project. Scratchpad developed over a 20 year stretch and was basically considered as a research platform for developing new ideas in computational mathematics. In the 1990s, as IBM's fortunes slid, the Scratchpad project was renamed to Axiom, sold to the Numerical Algorithms Group (NAG) in England and became a commercial system. As part of the Scratchpad project at IBM in Yorktown I worked on all aspects of the system and eventually helped transfer the product to NAG. For a variety of reasons it never became a financial success and NAG withdrew it from the market in October, 2001. NAG agreed to release Axiom as free software. The basic motivation was that Axiom represents something different from other programs in a lot of ways. Primarily because of its foundation in mathematics the Axiom system will potentially be useful 30 years from now. In its current state it represents about 30 years and 300 man-years of research work. To strive to keep such a large collection of knowledge alive seems a worthwhile goal. However, keeping Axiom alive means more than just taking the source code and dumping it onto a public server. There are a lot of things about the system that need to change if it is going to survive and thrive for the next 30 years. The system is complex and difficult to build. There are few people who know how it is structured and why it is structured that way. Somehow it needs to be documented deeply so others can contribute. The mathematics is difficult. Unlike other free software you can't just reach for the old saying read the source code''. The source code is plain, clear and about as close to the mathematical theory as is practical. Unfortunately the mathematical theory is enshrined in some research library where few people will have access. Somehow this must change. The research work, the mathematics, the published papers, and the source code have all got to be kept together for the next generation to read, understand and modify. The mathematics is narrow and very focused. This was due to the fact that, while Axiom is a great research platform, we only had a limited number of visitors at IBM Research. So there is very little in the way of, say, infinite group theory in Axiom. We can add it. Doing so will show up shortcomings in the system. For example, how do you represent an infinite object? There are many possible representations and they depend on your goals. The system will have to change, expand, and, hopefully, become cleaner as more thought is applied. Scratchpad changed continuously while it was being used for research and we expect Axiom to do the same. The language (spad) is designed to let you write algorithms that are very close to the mathematics. However, the algorithms as presented in the current system have never been shown or proven (an important distinction) to be correct. It is vital that we undertake the huge effort of verifying and validating the code. How else can we trust the results and of what use is a system this complex without trust? Somehow we have to extend the system to integrate program proof techniques. That is, we have to make computational mathematics hold to the same standard as the rest of mathematics. All of which seems to integrate into a requirement for better documentation. The key change which developers of Axiom will find with this version is that the documentation is primary and the code is secondary. Taking direction from Knuth and Dijkstra the system is now in a literate programming style. The hope is that the next generation of developers and users will be able to understand, maintain and extend the system gracefully. And that eventually papers submitted to journals (an Axiom Journal?) will be easily imported into the system with their running code made available automatically. There is no guarantee that this attempt to change the culture of computational mathematicians is going to succeed. But it is our firm belief that current systems have reached a complexity plateau and we need to find new techniques to push the envelope. In general, we need to consider changes to the system with a 30 year horizon rather than the current write-ship-debug mentality of software development. This is, after all, mathematics, the queen of the sciences. It deserves all of the time, talent and attention we can bring to bear on the subject. Tim Daly -- September 3, 2002 Contributions All of these people have, in some way or other, been associated with Scratchpad and Axiom. If you contribute, add your name. The names are in alphabetical order as we make no attempt to quantify the relative merit of the contributions. In books/bookvol5.pamphlet is a variable called credits which contains this list. Typing )credits at the axiom command prompt will prettyprint the list. "An alphabetical listing of contributors to AXIOM:" "Michael Albaugh Cyril Alberga Roy Adler" "Christian Aistleitner Richard Anderson George Andrews" "S.J. Atkins Jeremy Avigad Henry Baker" "Martin Baker Stephen Balzac Yurij Baransky" "David R. Barton Thomas Baruchel Gerald Baumgartner" "Gilbert Baumslag Michael Becker Nelson H. F. Beebe" "Jay Belanger David Bindel Fred Blair" "Vladimir Bondarenko Mark Botch Raoul Bourquin" "Alexandre Bouyer Karen Braman Wolfgang Brehm" "Peter A. Broadbery Martin Brock Manuel Bronstein" "Stephen Buchwald Florian Bundschuh Luanne Burns" "William Burge Ralph Byers Quentin Carpent" "Pierre Casteran Robert Cavines Bruce Char" "Ondrej Certik Tzu-Yi Chen Bobby Cheng" "Cheekai Chin David V. Chudnovsky Gregory V. Chudnovsky" "Mark Clements James Cloos Jia Zhao Cong" "Josh Cohen Christophe Conil Don Coppersmith" "George Corliss Robert Corless Gary Cornell" "Meino Cramer Jeremy Du Croz David Cyganski" "Nathaniel Daly Timothy Daly Sr. Timothy Daly Jr." "James H. Davenport David Day James Demmel" "Didier Deshommes Michael Dewar Inderjit Dhillon" "Jack Dongarra Jean Della Dora Gabriel Dos Reis" "Claire DiCrescendo Sam Dooley Zlatko Drmac" "Lionel Ducos Iain Duff Lee Duhem" "Martin Dunstan Brian Dupee Dominique Duval" "Robert Edwards Heow Eide-Goodman Lars Erickson" "Mark Fahey Richard Fateman Bertfried Fauser" "Stuart Feldman John Fletcher Brian Ford" "Albrecht Fortenbacher George Frances Constantine Frangos" "Timothy Freeman Korrinn Fu Marc Gaetano" "Rudiger Gebauer Van de Geijn Kathy Gerber" "Patricia Gianni Gustavo Goertkin Samantha Goldrich" "Holger Gollan Teresa Gomez-Diaz Laureano Gonzalez-Vega" "Stephen Gortler Johannes Grabmeier Matt Grayson" "Klaus Ebbe Grue James Griesmer Vladimir Grinberg" "Oswald Gschnitzer Ming Gu Jocelyn Guidry" "Gaetan Hache Steve Hague Satoshi Hamaguchi" "Sven Hammarling Mike Hansen Richard Hanson" "Richard Harke Bill Hart Vilya Harvey" "Martin Hassner Arthur S. Hathaway Dan Hatton" "Waldek Hebisch Karl Hegbloom Ralf Hemmecke" "Henderson Antoine Hersen Nicholas J. Higham" "Roger House Gernot Hueber Pietro Iglio" "Alejandro Jakubi Richard Jenks Bo Kagstrom" "William Kahan Kyriakos Kalorkoti Kai Kaminski" "Grant Keady Wilfrid Kendall Tony Kennedy" "David Kincaid Ted Kosan Paul Kosinski" "Igor Kozachenko Fred Krogh Klaus Kusche" "Bernhard Kutzler Tim Lahey Larry Lambe" "Kaj Laurson Charles Lawson George L. Legendre" "Franz Lehner Frederic Lehobey Michel Levaud" "Howard Levy J. Lewis Ren-Cang Li" "Rudiger Loos Craig Lucas Michael Lucks" "Richard Luczak Camm Maguire Francois Maltey" "Osni Marques Alasdair McAndrew Bob McElrath" "Michael McGettrick Edi Meier Ian Meikle" "David Mentre Victor S. Miller Gerard Milmeister" "Mohammed Mobarak H. Michael Moeller Michael Monagan" "Marc Moreno-Maza Scott Morrison Joel Moses" "Mark Murray William Naylor Patrice Naudin" "C. Andrew Neff John Nelder Godfrey Nolan" "Arthur Norman Jinzhong Niu Michael O'Connor" "Summat Oemrawsingh Kostas Oikonomou Humberto Ortiz-Zuazaga" "Julian A. Padget Bill Page David Parnas" "Susan Pelzel Michel Petitot Didier Pinchon" "Ayal Pinkus Frederick H. Pitts Jose Alfredo Portes" "E. Quintana-Orti Gregorio Quintana-Orti Beresford Parlett" "A. Petitet Peter Poromaa Claude Quitte" "Arthur C. Ralfs Norman Ramsey Anatoly Raportirenko" "Guilherme Reis Huan Ren Albert D. Rich" "Michael Richardson Jason Riedy Renaud Rioboo" "Jean Rivlin Nicolas Robidoux Simon Robinson" "Raymond Rogers Michael Rothstein Martin Rubey" "Jeff Rutter Philip Santas Alfred Scheerhorn" "William Schelter Gerhard Schneider Martin Schoenert" "Marshall Schor Frithjof Schulze Fritz Schwarz" "Steven Segletes V. Sima Nick Simicich" "William Sit Elena Smirnova Jacob Nyffeler Smith" "Matthieu Sozeau Ken Stanley Jonathan Steinbach" "Fabio Stumbo Christine Sundaresan Robert Sutor" "Moss E. Sweedler Eugene Surowitz Max Tegmark" "T. Doug Telford James Thatcher Laurent Thery" "Balbir Thomas Mike Thomas Dylan Thurston" "Francoise Tisseur Steve Toleque Raymond Toy" "Barry Trager Themos T. Tsikas Gregory Vanuxem" "Kresimir Veselic Christof Voemel Bernhard Wall" "Stephen Watt Jaap Weel Juergen Weiss" "M. Weller Mark Wegman James Wen" "Thorsten Werther Michael Wester R. Clint Whaley" "James T. Wheeler John M. Wiley Berhard Will" "Clifton J. Williamson Stephen Wilson Shmuel Winograd" "Robert Wisbauer Sandra Wityak Waldemar Wiwianka" "Knut Wolf Yanyang Xiao Liu Xiaojun" "Clifford Yapp David Yun Qian Yun" "Vadim Zhytnikov Richard Zippel Evelyn Zoernack" "Bruno Zuercher Dan Zwillinger" Pervasive Literate Programming I think David Diamond said it best (Datamation, June 1976, pg 134): The fellow who designed it is working far away. The spec's not been updated for many a livelong day. The guy who implemented it is promoted up the line. And some of the enhancements didn't match to the design. They haven't kept the flowcharts, the manual's a mess. And most of what you need to know, you'll simply have to guess. and with respect to Axiom: The research that it's based on is no longer to be had. And the theory that it's based on has changed by just a tad. If we keep it all together then at least there is a hope. That the people who maintain it will have a chance to cope. To quote Fred Brooks, "The Mythical Man-month" "A basic principle of data processing teaches the folly of trying to maintain independent files in synchronization... Yet our practice in programming documentation violates our own teaching. We typically attempt to maintain a machine-readable form of a program and an independent set of human-readable documentation, consisting of prose and flowcharts ... The solution, I think, is to merge the files, to incorporate the documentation in the source program." "A common fallacy is to assume authors of incomprehensilbe code will somehow be able to express themselves lucidly and clearly in comments." -- Kevlin Henney "A programmer who cannot explain their ideas clearly in natural language is incapable of writing readable code." -- Tim Daly As you can already see from this document the whole of the Axiom effort is structured around literate programs. Every directory has a Makefile.pamphlet file which explains details of that directory. The whole source tree hangs from the Makefile tree. (Some of the Makefile.pamphlet files contain only text if executable code is not needed). Every source file is embedded in a pamphlet file. Which begs the question: What is a pamphlet file?''. Basically it is a tex document with some additional markup tags that surround source code. Pamphlet files are intended to document one particular subject. Pamphlet files can be later combined into booklet'' files as one would embed chapters into books. Which begs the question: Why bother with pamphlet files?''. Clearly you didn't read the philosophy rant above. In more detail there have been two traditional methods of documenting source code. The first is to sprinkle random comments into the code. This suffers from the problem that the comments assume you already understand the purpose of the code and why an enlightened comment like This oughta work'' is perfectly clear and compelling. The second method is to write a document as a separate file. They get written half-heartedly because the lack of source code allows you to skip over explaining ugly implementation details (where all of the real confusion lies). This form of documentation never gets updated and gradually becomes uninteresting history. Pamphlet files overcome neither of these limitations if you don't make the effort to do it right. Ask yourself the question What would Knuth do?'' or Will this be clear 30 years from now?''. Which begs the question: Why go to all this trouble?''. Because you're having a conversation with people who are far removed from you in time, space, and understanding. Because someone else will have to maintain your code. Because you are part of a community of mathematicians who hold you to high standards. Because if you can't explain it clearly maybe YOU don't understand it or it isn't as clear as you think it is. Lets imagine that we'd like to receive a pamphlet file from a colleague. It contains a new theory and spiffy new algorithm. We'd like to be able to put the pamphlet file into the system and have everything magically happen to integrate the new pamphlet into the system. What would that imply? Well, lets assume that the pamphlet file has certain required sections. We'd like to get more than the technical paper and the code. We'd also like to see the help information, test cases, example code, cross-references to other pamphlets that would get automatically included, have the proof available and automatically checkable, etc. In the best of all possible worlds we have a front-end system that knows nothing except how to deconstruct and integrate properly formed pamphlet files. If this were true we could be sure that all of the mathematics is documented and external to the system. There are no rabbits'' (as Dijkstra called surprises or special knowledge) that we pull out of our hat. Conceptually, given an underlying Lisp system, it is clear we can built such a system. The General Directory Structure The Top Level directory structure contains 7 directories which are explained in detail below. Three of the directories (license, zips, and lsp) are not part of the essential core of Axiom. The other four directories (src, int, obj, and mnt) comprise the system build environment. Each directory has a specific purpose. Lets look at the essential directories first.$AXIOM
lsp
GCL
src
include
lib
scripts
int
doc
obj
tmp
noweb
SYS=(linux,...)
mnt
SYS=(linux,...)
zips

The src directory consists of human-written, system-independent
code. You can copy this directory (and the top-level makefiles) and
have a complete build system. Nothing in this directory is ever
changed by the Makefiles and it can be mounted in a read-only fashion
during the build process. An example file would be the lisp source
files.

The int directory consists of machine-generated, system-independent
code. Consider this directory as a cache. Nothing in this directory is
necessary for a clean system build but once the build completes the
information in this directory can significantly shorten rebuilds.
Since this information is system-independent we can use the cache no
matter what architecture we target. An example file would be the dvi
files generated from the tex sources.

The obj directory consists of machine-generated, system-dependent
code. This directory is "scratch" space for the compiler and other
tools. Nothing in this directory is useful once the system is
built. An example file would be the .o files from the C compiler.

The mnt directory consists of machine-generated, system-dependent code
that will comprise the "shipped system". You can copy this directory
and have a complete, running Axiom system. If the end user will see it
or need it in any way it belongs here. Executables are generally built
in obj and moved here. Example files would be the final executable
images, the input files, etc.

The four directories above make it possible to do a system build for
one system (say, a linux system) which will fill in the int
subdirectory. Then you can NFS mount the src and int directories
read-only on a Solaris machine and do a solaris system build.  The
original Axiom could build across many different architectures,
compilers, and operating systems.

The license directory collects all of the licenses for material that
is included in this distribution. Source files contain a line that
refers to one of these license files. Some people are of the belief
that including the full license text in every source file magically
strengthens the license but this is not so.  Imagine including the
full text of the copyright at the beginning of every section of a book.

The LICENSE.AXIOM file is a Modified BSD-style license that covers all
of the files released as part of this distribution except as noted in
particular files. Copyright information that might have shown up in
source files that were released from NAG are also collected here and
noted at the top of the files they cover.

The zips directory

The zips directory contains particular distributions of
network-available software that is known to work with this release of
Axiom. Newer versions may work and, if so, should be added to this
directory. The makefiles that handle these files will unpack them into
the correct locations in the src directory tree. These files exist to
increase the stability of the distribution so we can guarantee that
the code works. We encourage testing the latest distributions so that
we can remain with the leading edge and give feedback to the
individual package developers if problems arise.

The lsp directory

Axiom lives on top of Common Lisp, specifically Gnu Common Lisp (GCL)

Steps to build Axiom

The Initial Distribution files

The initial distribution contains several top level files. These are:

1) Makefile.pamphlet
This is the noweb source for the Makefile file. All changes to
the Makefile should occur here and the

3) Makefile This is the actual Makefile that will create Axiom.

In general the distribution will contain the pamphlet files for each
source file and the source file itself. Modifications should be made
and explained in the pamphlet files. The document command should be
run to rebuild the source file and the dvi file.

Steps in the build process

The sequence of steps necessary to build a clean Axiom is simply:

export AXIOM=(path-including-this-directory)/mnt/SYSNAME
export PATH=$AXIOM/bin:$PATH
make

If this fails check the FAQ for possible problems and their fixes.