[Axiom-developer] Speed of compilation

[u1204]

Курочкин Геннадий,

Axiom does take a while to build. Let me explain why.

In general, Axiom is concentrating on Literate Programming.  The goal is
to keep Axiom alive by writing down all of the information necessary to
use, maintain, and modify it.

I was a member of the original development team at IBM. We normally
developed code, even algebra code, without any documentation and without
a test suite. As a result, when I got my own code back years later I did
not understand WHY I wrote the code. I understood WHAT it did and I knew
it was necessary because removing it broke the system.  I needed all of
my original background knowledge and experience to build Axiom as open
source.

That raised the question "How can I make Axiom live beyond the
current developers?" I believe the answer is Literate Programming.

I have the "Hawaii" test for a Literate Program.  You should be able to
give a developer a paper copy of your program, send them to Hawaii for a
2 week, all expense paid vacation, and when they return they should be
able to maintain and modify the program as well as the current
developers. To do that you need to write down WHY something exists as
well as how it works, how to use it, and how to test it. This is
especially important for the algebra since very few people are domain
experts.

To see where we'd like to be look at the book "Lisp in Small Pieces".
Christian has set the gold standard for Axiom documentation.

Axiom is now structured as a 20 volume book set.  The goal is to have
the full Axiom system source code completely embedded in the books. 
Every time the system is modified and rebuilt, all of the books
are also rebuilt. Eventually it will be normal to require updating the
human-readable text along with every code change, just as you would with
any textbook. New algebra will require some background theory as well as
explanations for code, help text, and a test suite.

Axiom is well on the way to being fully literate. It will take many
years before anyone gets a Hawaii vacation, of course, but that is the
goal. 

Building the documentation and running the test suites every time a
change is made means that compilation takes longer.  It currently takes
about 1 hour to build the system without tests and 2.5 hours with full
testing. Full system builds are done at every commit.

Build times only affect developers, not users. Axiom is focusing on
making it easier for end users. The )help command has many new pages.
The test suite has more documented examples. Many of the functions shown
by the )display operations command have examples of use shown in the
output. Individual domain test suites and help pages are embedded with
the source code of the domain so they are part of the documentation a
user sees in the books. A standard browser based front-end is partially
built. It will function as a web front and replace both HyperDoc and
Graphics with standard HTML5.

Writing naked code was acceptable in 1975. Machines were slow. Axiom
took about 3 weeks for a full build. Build time mattered a lot.
That is no longer true. Now Human understanding is much more important.

It is now time to raise the standards. We need to expect quality code
that is well documented (including some theory), easy to modify and
maintain, with a comprehensive test suite. Human-to-Human communication
is more important than Human-to-Machine (code).

Tim Daly