18.9 : Using free functios with AXIOM
A free function is a function defined at the top level in an Aldor source file, in other words the function definition is not contained within any domain or category.
Before AXIOM Version 2.0, library functions had to come from
domains (or packages), but this is no longer the case.
Whenever you use )library directly or indirectly (for example,
by using )compile), the AXIOM databases are updated with
knowledge of all constructors and free functions.
After that, free functions participate fully in function selection
within the AXIOM intepreter, and
can also be passed to other functions, for example
AXIOMFunmap.
Note that they cannot be package-called since they do not come from a
domain.
You may need to more fully qualify the types of their arguments via
declarations or coercions to get the exact operation you intend.
18.10 : Efficiency
The Aldor compiler's runtime efficiency is, in part, due to the inlining of functions at the point of their call. In order to do this, it must be able to find suitable code in an object file. Unfortunately the old AXIOM compiler does not produce compatible files, so it is not possible to inline old compiler code.
This is particularly important for domains such as AXIOMTypeNonNegativeInteger, AXIOMTypeInteger, and AXIOMTypeList: typical code spends much of its time manipulating objects of these types. The Aldor runtime therefore extends certain important domains with operations which are identical in name and function to their AXIOM counterparts, but can be found by the Aldor compiler because they are redefined by Aldor source code.
The files that implement this extension process are axextend.as and axext_l.l which should be in the $ALDORROOT/samples/libax0 directory. The idea is that Aldor provides a mechanism for extending existing domains into objects which have more functionality -- we use this to change (in this case, make more efficient) the existing operations.
This is done for the low level datatypes, such as integers, floats and some aggregate types (currently AXIOMTypeList and AXIOMTypeVector). Algebraic datatypes such as polynomials and expressions have not been extended in this way.
A subset of the Integer extension is shown below:
extend
extend Integer: with {
+: (%, %) -> %;
=: (%, %) -> Boolean;
integer: Literal -> %;
}
== add {
import from Machine;
Rep ==> BInt;
import {
BIntPlus: (BInt, BInt) -> BInt;
BIntEQ: (BInt, BInt) -> Bool;
ArrToBInt: (Arr) -> BInt;
} from Builtin;
(a: %) + (b: %): % ==
per(BIntPlus(rep a, rep b));
(a: %) = (b: %): Boolean ==
BIntEQ(rep a, rep b) pretend Boolean;
integer(l: Literal): % ==
per ArrToBInt(l pretend Arr);
}
This will ensure that whenever the Aldor compiler finds a call to +, and it wishes to inline the call, a call to the FOAM builtin BIntPlus will be generated, rather than a much more expensive call to an AXIOM-defined function.
Similarly, it is possible to define extensions in terms of
functions (or macros) imported from Foreign(Lisp).
The Lisp function should be defined in an auxilliary lisp file,
which may be compiled and loaded into the AXIOM system.
This course of redefining AXIOM operations should be a last
resort used in order to gain efficiency, because any changes to
the representation of a domain must be reflected in both the
AXIOM library, and in the Aldor and Lisp code which defines
the extension.
18.11 : Details of system commands
In this section we describe in detail three AXIOM system commands that are useful when compiling Aldor files within AXIOM:
- )set axiomxl args
- )compile
- )library
The )compile system command acts as a front-end to both the Aldor compiler and the old AXIOM system compiler. In what follows we shall only describe the options as they pertain to Aldor; see the AXIOM system command documentation for additional information regarding the old system compiler.
The first thing )compile does is look for a source code filename among its arguments. Thus the following commands:
)compile mycode.as )compile /u/jones/apps/mycode.as )compile mycodeall invoke )compiler on the file /u/jones/apps/mycode.as if the current AXIOM working directory is /u/jones/apps. (Recall that you can set the working directory via the )cd command. If you don't set it explicitly, it is the directory from which you started AXIOM.)
This is frequently all you need to do to compile your file. This simple command:
- Invokes the Aldor compiler to produce Lisp output.
- Calls the Lisp compiler if the Aldor compilation was successful.
- Uses the )library command to tell AXIOM about the contents of your compiled file and arrange to have those contents loaded on demand.
Should you not want the )library command automatically invoked, call )compile with the )nolibrary option. For example,
)compile mycode.as )nolibrary
The general description of Aldor command line arguments is in chapter 27. The default options used by the )compile command can be viewed and set using the )set axiomxl args AXIOM system command. The current defaults are
-O -Fasy -Fao -Flsp -laxiom -Mno-ALDOR_W_WillObsolete -DAxiomThese options mean:
- -O: perform all optimizations,
- -Fasy: generate a .asy file,
- -Fao: generate a .ao file,
- -Flsp: generate a .lsp (Lisp) file,
- -laxiom: use the axiom library libaxiom.al,
- -Mno-ALDOR_W_WillObsolete: do not display messages about older generated files becoming obsolete, and
- -DAxiom: define the global assertion Axiom so that the Aldor libraries are not accidentally used with AXIOM.
To supplement these default arguments, use the )moreargs option on )compile. For example,
)compile mycode.as )moreargs "-v"uses the default arguments and appends the -v (verbose) argument flag. The additional argument specification must be enclosed in double quotes.
To completely replace these default arguments for a particular use of )compile, use the )onlyargs option. For example,
)compile mycode.as )onlyargs "-v -O"only uses the -v (verbose) and -O (optimize) arguments. The argument specification must be enclosed in double quotes. In this example, Lisp code is not produced and so the compilation output will not be available to AXIOM.
To completely replace the default arguments for all calls to )compile within your AXIOM session, use )set axiomxl args. For example, to use the above arguments for all compilations, issue
)set axiomxl args "-v -O"Make sure you include the necessary -l and -Y arguments along with those needed for Lisp file creation. As above, the argument specification must be enclosed in double quotes.
By default, the )library system command exposes all domains and categories it processes. This means that the AXIOM intepreter will consider those domains and categories when it is trying to resolve a reference to a function. Sometimes domains and categories should not be exposed. For example, a domain may just be used privately by another domain and may not be meant for top-level use. The )library command should still be used though, so that the code will be loaded on demand. In this case, you should use the )nolibrary option on )compile and the )noexpose option in the )library command. For example,
)compile mycode.as )nolibrary )library mycode )noexpose
Once you have established your own collection of compiled code, you may find it handy to use the )dir option on the )library command. This causes )library to process all compiled code in the specified directory. For example,
)library )dir /u/jones/apps/quantumYou must give an explicit directory after )dir, even if you want all compiled code in the current working directory processed, i.e.
)library )dir .
The )compile command works with several file extensions. We saw above what happens when it is invoked on a file with extension .as. A .ao file is a portable binary compiled version of a .as file, and )compile simply passes the .ao file on to Aldor. The generated Lisp file is compiled and )library is automatically called, just as if you had specified a .as file.
A .al file is an archive file containing .ao files. The archive is created (on Unix systems) with the ar program. When )compile is given a .al file, it creates a directory whose name is based on that of the archive. For example, if you issue
)compile mylib.althe directory mylib.axldir is created. All members of the archive are unarchived into the directory and )compile is called on each .ao file found. It is your responsibility to remove the directory and its contents, if you choose to do so.
A .lsp file is a Lisp source file, presumably, in our context, generated by Aldor when called with the -Flsp option. When )compile is used with a .lsp file, the Lisp file is compiled and )library is called. You must also have a .asy file present, generated from the same source file.
Finally, when called with a file having the extension .spad, the
)compile command invokes the old AXIOM system compiler.
18.12 : Using Aldor outside AXIOM for AXIOM
Section 18.11 discusses what really happens when you invoke the )compile system command from within AXIOM. If you invoke Aldor manually from the operating system prompt (or from a front-end windowed application), you must use the proper options so that all files needed by AXIOM are generated. You must include the options
Note that you cannot test the execution of your code except by starting AXIOM and then loading and executing the compiled version. There are several reasons why you might want to develop your code outside AXIOM:
- AXIOM may not be available on the machine on which you have Aldor installed.
- You do not want to incur the paging delays of having AXIOM loaded and then invoking Aldor.
Now we look at these options and discuss which ones you might want to leave out in the early stages of developing your code.
- -O
- This flag indicates that full optimization be performed on generated code. You need not use this in the early stages of development since you will not actually be executing your code. Optimization is also time consuming.
- -Fasy
- The presence of this flag causes a .asy file to be generated. This file contains symbolic information about your code that was gathered and generated during compilation. The file is needed by AXIOM and can be used by library browsers.
- -Fao
- Always include this flag. It causes Aldor to create a portable binary data .ao file from your file. This is needed by AXIOM and during the compilation of other files that depend on the contents of the current file.
- -Flsp
- A Lisp file is created when you specify this option. Omit it until you are ready to load your code into AXIOM.
- -laxiom
- This is required. It tells Aldor to look in the libaxiom.al library for data about AXIOM constructors.
- -DAxiom
- Not required, but useful. The Aldor libraries contain a terminating error condition that tests if the global assertion Axiom is true. This prevents you accidentally using the Aldor libraries when you intended to use the AXIOM libraries.
Since compilation of large files can take some time, you may decide to include more and more of the ``optional'' arguments as your work proceeds, just in case the next compile is that lucky one where everything works!
When you are ready to test and use your code within AXIOM, start
up AXIOM and then )cd to the directory containing your
compiled code. Invoke )compile on each .lsp file you wish
to use. The Lisp compiler will be invoked and the )library
command will be called automatically unless you specify
)nolibrary on )compile.
18.13 : Fine Print
At present, code from the AXIOM library will only run inside an AXIOM workspace. Consequentely Aldor programs extending the AXIOM library will only run inside AXIOM. For a later version, it is planned that the entire AXIOM library will be translated into Aldor, at which point it should be possible to call it from C, Fortran, or any other environment in which Aldor operates.
You must choose whether you wish to use the stand-alone Aldor library (aldor.as + libaldor) or whether you wish to use the AXIOM library (axiom.as + libaxiom). It is possible to use them both together, but some types exist in both libraries but have slightly different meanings, so using them together is quite tricky.
The AXIOM and Aldor libraries contain many constructors with the same names. Unfortunately, the like-named constructors often export different operations, complicating the translation of a program written for the Aldor library to one written for AXIOM. It is beyond the scope of this document to do a detailed comparison of the libraries.
We suggest you compare the exports of the constructors if you intend to start a project using the Aldor library and then shift to the AXIOM library, or vice versa. For example, look at AXIOMTypeComplex in the complex.as file in the Aldor library source directories and compare it to the definition in gaussian.spad in the AXIOM source ``algebra'' directory (this directory is probably $AXIOM/../../src/algebra on a Unix machine.)
When you compile a .as file within AXIOM, the -DAxiom global assertion is automatically added to the Aldor command line. The Aldor libraries will cause compilation to terminate when they are processed if this assertion is present. This gives you some measure of protection against trying to use Aldor libraries within AXIOM.
Previous
Home
Contents
Next