[Axiom-developer] Bootstrap documentation.

[Waldek Hebisch]

I want to include some documentation of current algebra bootstrap
used in wh-sandbox.  Below is what I have now.  Any comment
(or things that need better explanation)?


\section{Bootstrap problem}

Current Axiom compiler compiles each constructor (category, domain
or package) separately.  In order to perform type check Axiom
needs type information from other constructors.  To collect
type information about constructor Axiom must compile it.
This creates bootstrap problem: in order to compile a constructor
one must first compile many other constructors.

In principle bootstrap problem could be avoided organizing algebra
into layers, so that layer $0$ is independent of other layers and
each higher layer depends only on lower layers.  However current
Axiom algebra contains a lot of cyclic dependencies: substantial
part of algebra depends on [[Integer]] and [[Integer]] has rich structure
and depends on many categories which in turn depend on Integer.

ATM this bootstrap problem has no proper resolution: Axiom
avoids it simply using type information collected in the past
and stored in databases ([[interp.daase]] and [[category.daase]]).
This solution means that attempt to change signature of any exported
operation is likely to cause build failure.

Using type information stored in databases solve only part of
bootstrap problem: internally Axiom types are represented by
executable code and sometimes Axiom needs to load actual compiled
code.  The exact rules telling when Axiom needs compiled code
and when it is enough to have info in databases are unknown.
Axiom needs to load categories given as argument to [[Join]]
(because [[Join]] is implemented as runtime operation).  It
seems that Axiom also needs to load a category given as argument
to contructors if this category itself has arguments.

During normal compilation Axiom tries to optimize (expand inline)
calls to operation from core domains (listed in
[$optimizableConstructorNames]] variable).  To do this Axiom
has to load those domains.  This optimization in the past required
keeping compiled Lisp corresponding to core domains (in fact, what
was stored was a cut breaking cycles involving core domains).
Currently Axiom has special flag [[$bootstrapDomains]] domains to
disables this optimization.

Even after using [[$bootstrapDomains]] flag there are still
cyclic load dependencies caused by constructor arguments, but
those problem are resolved using [[$bootStrapMode]] flag
which causes relaxed type checking and skips executable parts
of categories.

The final process looks as follows. First, categories are
topologicaly sorted with respect to [[Join]] (arguments to
[Join]] must be compiled before category using [[Join]]).
This order is slightly tweaked to avoid problems due to
constructor parameters.  In the first pass categories
are compiled using [[$bootStrapMode]] set to [[t]].  This
makes compiled code of categories available to second pass.
In the second pass categories and core domains are
compiled setting [[$bootstrapDomains]] to [[t]].  We have
to compile categories because categories may have associated
default domain which also may be loaded.  We also compile
few domains which we are needed for unknown reasons (if we
skip them the build will fail).  In the third pass we
compile categories and core domains in normal mode.
Finally, we compile the rest of algebra in alphabetical order
(in fact, we let make choose the order, but the list we give is
sorted alphabetically, and make processes it in order).

\section{Adding new constructor}

Adding a new constructor is different than the above process.  It is
easier because new constructor can freely use function provided
by standard algebra.  OTOH information about new constructors
is absent from Axiom databases, so cyclic dependencies between new
constructors have no easy solution.  However if one is adding
mutually dependent constructors without cyclic dependencies
the solution is easy: compile all dependent constructors in
a single Axiom image, using apropriate order.  The [[guess-pkg]]
target ilustrates this method.OA  
-- 
                              Waldek Hebisch
address@hidden