OKlibrary  0.2.1.6
Maxima.hpp File Reference

Central docus-file regarding Maxima/Lisp. More...

Go to the source code of this file.


Detailed Description

Central docus-file regarding Maxima/Lisp.

Maxima/Lisp in the OKlibrary

Calling the supported Maxima console

  • For questions related to building Maxima see Buildsystem/ExternalSources/SpecialBuilds/docus/Maxima.hpp.
  • Via oklib --maxima (see Buildsystem/MasterScript/docus/general.hpp for general information on the masterscript "oklib") a Maxima-console is opened, with support for loading Maxima-components from the OKlibrary:
    1. By oklib_load_all(); then all Maxima-functions in the OKlibrary are loaded.
    2. More general, via oklib_load(filename) a specific module is loaded:
      • "filename" here is, as with the C++ system, a relative path starting with "OKlib".
      • At each level files "include.mac" are provided to include whole (super-)modules.
      • So "oklib_load_all()" just is oklib_load("OKlib/ComputerAlgebra/include.mac").
      • But also specific Maxima-files can be loaded.
    Further parameter can be provided (they are passed on to Maxima), so for example by
    oklib --maxima --batch=FILE
        
    the file FILE is batch-processed by Maxima.
  • As can be seen from the make-output, "oklib --maxima" just calls the Maxima console provided with initial definitions.
    1. The template for these initial definitions is the file /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/MasterScript/SpecialProcessing/maxima-init.mac.
    2. As usual for such templates, configuration variables are accessed via "m4_SHELL(variable)".
  • The redefinition-warnings shown when starting Maxima in this way (and using CLisp instead of Ecl) are about a change in behaviour when parsing files. Likely this doesn't affect usage, but here are the details:
    1. By default, "oklib_load" and "oklib_include" (see below) do not provide debugging information for the parsed functions.
    2. This saves run-time and storage space.
    3. If the debugging information (filename and fileline of the creating function for list-values) is needed, then it can be activated by setting "oklib_load_annotation" to true.
    4. The standard functions (like "load") are not affected (they always provide annotations).
    5. See the discussion of "oklib_load_annotation" below for further information.
  • If you have in your home directory a directory ".maxima", containing a file "maxima-init.mac", then this file will be used instead of the OKlibrary initialisation file:
    1. So in order to work with the OKlibrary, normally you should not have a file "~/.maxima/maxima-init.mac".
    2. However, if you have special needs then using "~/.maxima/maxima-init.mac" might be what you want.

Preloaded functionality

  • For all the details, see the OKlib-Maxima initialisation file /home/csoliver/OKplatform/OKsystem/OKlib/Buildsystem/MasterScript/SpecialProcessing/maxima-init.mac.
  • Inclusion and loading of files:
    1. Inside a Maxima-file (in the context of the OKlibrary), inclusion of other Maxima-files happens via oklib_include(filename), where filename is the relative path starting with "OKlib".
    2. In this way multiple inclusions are avoided.
    3. To avoid multiple inclusions for Maxima modules, use oklib_plain_include(modulename) (which does not augment the filename).
    4. On the other hand, via oklib_load(filename) it is guaranteed that the specified file is re-loaded (while all other includes are again guarded against multiple inclusions).
    5. Loading a file in batch mode (re-loading it and showing the execution of every line) happens via oklib_batch(filename).
    6. Using oklib_batch is recommended for executing tests (that is, loading files from directories testobjects).
    7. And loading a demo (additionally to "batch" this allows for interaction) happens via oklib_demo(filename).
  • Access to configuration-variables:
    1. From a Maxima-session, via "system(string_with_shell_code)" one can perform system calls, however to obtain the value of a variable, one has to use 'system("echo ${Var}")' and copy the output from the screen.
    2. In this way all configuration-variables from the OKlibrary build system are available.
    3. For convenience OKplatform and OKsystem are directly defined as variables.
  • Storing results at given time intervals:
    1. The variable "oklib_session_name" contains the name used for storing results in a file via "oklib_save".
    2. Calling oklib_save(arguments) triggers the following actions:
      1. If "oklib_store" is false, then nothing happens.
      2. If not "oklib_storage_interval"-many run-time minutes have elapsed since the last file-storage (or since the start of the session). then nothing happens.
      3. Otherwise, if you used "oklib_save()" then all variables in the environment of this call will be saved to file, while if you used for example "oklib_save('a,'b)", then only the values of variables a and b will be saved.
    3. Via "load(filename)" these variable-values are made accessible in a Maxima-session.
  • Logging of Maxima-output:
    1. Calling oklib_log(string) starts logging into file "oklib_session_name_string" (name as above for saving results, plus underscore and additional specification via string; if this file already exists, then it is emptied).
    2. Computation of term t is then best done via display(t)$, so that also the input is shown.
    3. Closing the logging_process by oklib_log_close().
  • Variable oklib_test_level controls the test levels, similar to the C++ higher-order unit test system:
    1. oklib_test_level = 0 means the "basic" test level (for permanent testing).
    2. oklib_test_level = 1 means the "full" test level (to be used before submitting to the central repository).
    3. oklib_test_level = 2 means the "extensive" test level (to be used before a new release).
    4. oklib_test_level may have higher values.
    5. To run absolutely all tests, use oklib_test_level = inf.
  • The boolean variable oklib_load_annotation governs whether functions loaded by oklib_load and oklib_include annotate their results:
    1. By default, we turn off ("false") annotation.
    2. When running the tests, it should be turned on ("true"); this debugging information is the reason for the default annotation by (plain) Maxima.
    3. When annotation is turned on (the default for Maxima), then every list created by some function coming from a file is internally stored with an annotation including the complete path for the file and the related line-number.
    4. When saving results to a file, this can cause a huge increase in file size.
    5. This annotation is hard-coded into the functions when they are parsed.
    6. We redefine the relevant functions in ComputerAlgebra/MaximaInternals/optload.lisp.
    7. With new Maxima versions one needs to check whether the corresponding functions in nparse.lisp and mload.lisp have changed, and accordingly must update the redefining functions.

Documentation in general

Docus for specific modules

Building a new Maxima package

  1. Assume for example that the current version is 5.17.1, and that want to create an update (from CVS), which we name 5.17.1.1. (Further updates would be called 5.17.1.2 etc.)
  2. Now the creation of a package "maxima-5.17.1.1.tar.gz" happens as follows.
  3. Download the appropriate sources; the newest sources by
    > cvs -z3 -d:pserver:anonymous@maxima.cvs.sourceforge.net:/cvsroot/maxima co -P maxima
       
  4. Create an advance in the version number in the fourth digit, by changing the line with "AM_INIT_AUTOMAKE" in maxima/configure.in. In our example, where the current version is 5.17.1, the new entry is
    AM_INIT_AUTOMAKE(maxima,5.17.1.1)
       
  5. Update information, and create the package:
    cd maxima
    ./configure
    make dist
       
    The package then needs to moved to its proper place
  6. The program xgettext is needed for that.

Definition in file Maxima.hpp.