In FriCAS adding a new constructor (category, domain or package) is easy, just add it and update algebra Makefile.in as indicated in note at top of Makefile.in

Adding new algebra in Axiom and OpenAxiom

This is a complex process by its very nature. Developers and Maintainers who undertake the process need to understand quite a lot of detail. The ultimate steps to add algebra are tedious but simple. Note that only algebra code that gets shipped with the system needs to undergo this process. User code can be compiled once the distributed algebra exists and does not need either this Makefile or this installation process.

Since understanding is the key to making correct changes to this file I'll work on explaining the details of why things need to exist.

The first idea that you need to understand is the overall process of adding algebra code. Lets assume that you have a brand new spad file, called foo.spad containing a simple domain BAR. The steps in the process of adding this file are:

1. Find out where the algebra code lives in the lattice.

   You do this by

2. starting a new interpsys session
3. collecting all the names of the algebra files BAR requires
4. determining which layer each of the required files resides
5. determine the highest layer (e.g. 14) that contains the required files
6. insert the documentation into the next layer (e.g. 15)
7. insert the BAR file into the layer's file list
8. create a new subsection for the foo.spad file
9. add a stanza to extract foo.spad from foo
10. add a stanza to extract foo.dvi from foo
11. add a stanza to compile foo.spad to get BAR.lsp
12. add a stanza to compile BAR.lsp to get BAR
13. add a stanza to copy BAR to the final algebra directory
14. add the 5 chunk names into the default Makefile section

Rebuilding the algebra from scratch

Compile order is important. Here we try to define the ordered lattice of spad file dependencies. However this is, in reality, a graph rather than a lattice. In order to break cycles in this graph we explicitly cache a few of the intermediate generated lisp code for certain files. These are marked throughout (both here and in the various pamphlet files) with the word BOOTSTRAP.

If we take a cycle such as RING we discover that in order to compile the spad code we must load the compiled definition of {bf RING}. In this case we must compile the cached lisp code before we try to compile the spad file.

The cycle for SETCAT is longer consisting of: SETCAT needs SINT needs UFD needs GCDDOM needs COMRING needs RING needs RNG needs ABELGRP needs CABMON needs ABELMON needs ABELSG needs SETCAT.

It is highly recommended that you try to become a developer of Axiom and read the archived mailing lists before you decide to change a cached file. In the fullness of time we will rewrite the whole algebra structure into a proper lattice if possible. Alternatively we'll reimplement the compiler to handle graphs. Or deeply adopt the extensible domains. Whatever we do will be much discussed (and cause much disgust) around the campfire. If you come up with a brilliant plan that gets adopted we'll even inscribe your name on a log and add it to the fire.

In the code that follows we find the categories, packages and domains that compile with no dependencies and call this set ``layer 0''. Next we find the categories, packages and domains that will compile using only ``layer 0'' code and call this ``layer 1''. We walk up the lattice in this fashion adding layers. Note that at layer 3 this process runs into cycles and we create the ``layer 3 bootstrap'' stanzas before continuing upward.

I used to have code that would automatically generate this lattice but it got lost in the move from IBM to NAG. The current information was hand generated during the coding of this Makefile. Except for the bootstrap files most of the stanzas have the dependency graph encoded in the precondition lists for each makefile stanza. Thus we can see that building the package ANY1 requires the category TYPE:

  ANY1.NRLIB: TYPE ANY1.spad

This information also exists in the comments before each layer. Ordinary users of Axiom won't need to know this. However developers of the standard system should strive to keep this information up to date and correct. The spad compiler will tell you this information as part of the compile.

Once we reach the point in the lattice where all of the individual categories, domains and packages in each spad file have been compiled we can start building the system directly from the whole spad code files rather than the individual domains.