Maxima is a symbolic computation program.  It is full featured,
doing symbolic manipulation of polynomials, matrices, rational
functions, integration, Todd-coxeter, graphing, bigfloats.  It has a
symbolic debugger source level debugger for maxima code.  Maxima is
based on the original Macsyma developed at MIT in the 1970's.
It comes with extensive self tests.

Maxima is distributed under the GNU General Public License, with some
export restrictions from the U.S. Department of Energy. See the file
COPYING.

Installation information is available in the file INSTALL. Summary
information about this release can be found in the file NEWS. Detailed
change information is available in the ChangeLog.

A simple usage example:

(%i1)	pyth:a^2+b^2=c^2;
(%o1)	b^2+a^2=c^2

(%i2)	solve(pyth,a);
(%o2)	[a=-sqrt(c^2-b^2),a=sqrt(c^2-b^2)]

(%i3)	integrate(x*sin(a*x),x);
(%o3)	(sin(a*x)-a*x*cos(a*x))/a^2

For more information on Maxima, see the Maxima web site,
<http://maxima.sourceforge.net>.

  Maxima project Git / build system HOWTO


  1  General

      Makefile.am is the file to modify, NOT Makefile
      (Makefile is generated automatically from Makefile.am)

      "make install" catches Makefile problems
      that are not detected by "make" alone

      Adding / removing files often leads to Makefile problems

      To update your repository, execute
      git pull  # assuming origin/master points to the SF Maxima repo

      Workflow with Git:
      git pull                      # update your repo
      git checkout master           # work off master
      git checkout -b scratch-pad   # create a working branch
      <do development, tests, commits, then, once satisfied...>
      git checkout master           # put yourself on master branch
      git pull                      # update your repo, again
      git merge scratch-pad         # merge development work into master
      git push origin master        # push to SF Maxima repo

      BE SURE NOT TO PUSH YOUR SCRATCH-PAD!

  2  Renaming something in Git

      --  Create a scratch/development branch as in 1.

      --  git mv X Y
          This moves X to Y and preserves the history.
	  Like any other change, this needs to be committed
	  as a separate step.

  3  Adding / removing a file in maxima/src

      --  Create a scratch/development branch as in 1.

      --  Add new file X, then execute
          git add X; git commit -m 'Message' -- X

      --  Remove old file X
          git rm X
          Then execute "git commit" as above

      --  Add / remove file name from maxima/src/Makefile.am

      --  Add / remove file name from maxima/src/*-depends.mk

          NOTE: There are several *-depends.mk files. These are
          theoretically updated automatically but to the best
          of my knowledge it is necessary to fix them by hand.

      --  Add / remove file name in maxima/src/maxima.system

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  If the change affects the plotting routines: Verify that
          tests/testbench_draw_manual.wxm still holds the right
	  results.

      --  If the change affects drawdf() or plotdf(): Verify that
          tests/testbench_drawdf_manual.wxm still holds the right
	  results.

      --  Merge your work onto master and push the changes as in 1.


  4  Adding / removing a file in maxima/share

      --  Copy new file / remove old file
          as you did in 3.

      --  Add / remove file name in maxima/share/Makefile.am

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  If the change affects the plotting routines: Verify that
          tests/testbench_draw_manual.wxm still holds the right
	  results.

      --  Merge your work onto master and push the changes as in 1.


  5.1  Creating a new share package

       E.g., new package name = my_package

      -- Naming conventions:

         write_long_names_like_this, andNotLikeThisPlease,
         norlikethiseitherthanks

         spell_out_names, dnt_try_sv_typng_w_abbrvs_tnx

      -- Create a new directory my_package

      -- Put Lisp and/or Maxima files in the directory

         At least one file must be named my_package.lisp or my_package.mac
         Otherwise load(my_package) fails

      -- Create texinfo documentation file my_package.texi
         (PLEASE CREATE DOCUMENTATION, THANK YOU)

         my_package.texi goes in maxima/doc/info
         (same as other texinfo files)

         Use maxima/share/template.texi as a template for my_package.texi

      -- Create test file rtest_my_package.mac
         (PLEASE CREATE A TEST FILE, THANK YOU)

         Test file contains pairs of expressions:
         input expression, then expected result

         batch("my_package/rtest_my_package.mac", test);
         executes the test


  5.2  Adding a directory in maxima/share

      --  Create a scratch/development branch as in 1.

      --  Make the new directory and put the new files in it

      --  Add the all the files in your new directory and commit this change:
          git add .
	  git commit -m 'Message' -a

      --  Put the my_package files on the file list of maxima/share/Makefile.am

      --  Add my_package to SHARE-SUBDIRS-LIST in maxima/src/init-cl.lisp

      --  Move my_package.texi to maxima/doc/info

          Put my_package.texi on the list of files in
          maxima/doc/info/Makefile.am

          Put my_package on the list of topics in maxima/doc/info/maxima.texi
          See instructions in comments at top of maxima/share/template.texi

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  6  Adding / removing a file in maxima/tests

      --  Create a scratch/development branch as in 1.

      --  Copy new file / remove old file
          and execute "git add" / "git rm"

      --  Add / remove file name in maxima/tests/Makefile.am

      --  Add / remove file name in maxima/tests/testsuite.lisp

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  7  Updating the website

    See the Git repository "website", particularly "README.md" there.


  8.1  Backups of Git

    All you need is the rsync tool and some disk space.

    Issue the following command:

    rsync -av 'rsync://maxima.git.sourceforge.net/gitroot/maxima/*' .


  8.2  Backups of the ML subscribers list

    You need to be a list admin to do that. Other then that you only
    need a mail client to send mailman commands to
    maxima-request@math.utexas.edu

    The command to get the subscribers list is "who" followed by the
    list admin password. Sending an empty mail with "who XXX" in the
    subject line should be enough.

    I have the following cron.weekly script to do this automatically:

    | #! /bin/sh
    |
    | su myuser -c "echo end | mail -s \"who password\" maxima-request@math.utexas.edu"


  8.3  Other Backups

    Backups of the following stuff would be nice too:

    - wiki

    - bug database


  9  Releases

  9.1  Release policies

    Releases are prepared (nominally) three times a year, on April 1,
    August 1, and December 1. Releases simply package whatever seems
    stable at that time.

    It is the responsibility of developers (not the release
    administrator) to copy bug fixes from the release branch to master
    or vice versa (it doesn't matter whether bug fixes are introduced
    on one branch or the other).

    I don't recommend major changes on a release branch, but there is
    really nothing to stop it. As always I'll appeal to good judgement.

    If I've forgotten some step, please add it to this document.

  9.2  Release numbering

    The first release on the 5.mm release branch is 5.mm.0, the second
    is 5.mm.1, third 5.mm.2, etc. The highest number on the branch is
    the "best" or, at least, the most committed-to version. There is no
    release candidate numbering.

    The version major number has been 5 for many years. If you feel like
    changing it to, say, 6, well, there's nothing to stop you.

  9.3  Changelog

    The changelog for 5.mm is named ChangeLog-5.mm.md (the suffix .md
    indicating that it is in so-called "markdown" format). To obtain the
    raw material for the changelog:

    $ git log branch-5.${mm-1}-base..HEAD

    Use the git-log output as the basis for ChangeLog-5.mm.md. Use your
    best judgement as to what to include; the git-log output is
    typically much, much larger than the changelog. Look at previous
    changelogs to see the markdown format and organization.

    Commit ChangeLog-5.mm.md to master. Don't forget to add it to
    the top level "Makefile.am" so that it will be included in the
    release tarball.

  9.4  Verifying the functionality of the maxima tarball

    The autotools offer a few make targets that allow to verify the
    maxima release:

    $ make pdf
    isn't done automatically on "make all" so it is good to test if this
    make target works.

    $ make check
    runs the standard testsuite, the testsuite for the share packages
    and the tests for the ask_* functions for all lisps maxima is compiled
    with and returns an error if any test unexpectedly failed.

    $ make distcheck
    compiles maxima, builds a release tarball, extracts this tarball,
    compiles it and runs "make check" on it in order to find out if
    "make dist" has produced a working tarball no files are missing from.

    $ mkdir build
    $ ../configure
    $ make
    $ make distcleancheck
    tests if "make disclean" brings maxima back into the original state.
    this is very handy when building debian packages.

    make installcheck
    $ tests if "make install" results in a working maxima release.

    Note that with Ubuntu Cosmic/Disco in Jan 2019 still only the first
    two of these make targets run without errors.

  9.5  Git commands for releases

    Release versions live on a branch named branch-5_mm, and are tagged
    5.mm.0, 5.mm.1, 5.mm.2, etc. The Git tag must be the same as the
    version number declared to autoconf.

    $ git checkout master
    $ git tag -a branch-5_mm-base
    $ git push --tags origin master
    $ git checkout -b branch-5_mm
    $ <edit configure.ac to set version number to 5.mm.0>
    $ git add configure.ac && git commit
    $ git tag -a 5.mm.0

    <at this point, verify that you can build packages BEFORE you push>

    $ git push --tags origin branch-5_mm-base
    $ git checkout master
    $ <edit configure.ac to set version number to 5.${mm-1}post>
    $ git add configure.ac && git commit
    $ git push origin master

    Repeat 5.mm.0 stuff (edit configure.ac and tag) for 5.mm.1, 2, 3, ....

    To copy bug fixes from one branch to another:

    $ git cherry-pick -x <commit hash>

  9.6  Building a release

    $ git checkout branch-5_mm
    $ sh bootstrap
    $ ./configure
    $ make dist-gzip

    At this point you now have maxima-5.mm.nn.tar.gz.

    Binaries for Linux are traditionally created by RPM.

    I'll assume you know how to build stuff with RPM. Copy the tar.gz
    to <path to rpm build tree>/SOURCES/. Then:

    $ rpmbuild -ba maxima.spec

    Debian packages can be built the following way:

    - Install clisp, sbcl, gcl, ecl and debhelper.
    - checkout the branch DebianPackaging
    - Update the changelog contained in its debian directory: From there the
      e-mail address of the packager and the version number of the Debian
      package are taken. It also is important that gpg knows the private key
      for the e-mail address mentioned in the last ChangeLog entry.
    - copy the debian directory into the directory containing the contents of
      the release tarball.
    - cd into this directory and type:
      $ debuild
    - debuild will now complain that the source is missing and tell under which
      names it will accept the tarball. Rename the tarball to this name and start
      debuild again.
    - a few minutes later gpg will ask for the key's password in order to sign
      the newly built packages.

    Unfortunately just using the Debian package included in the autotools won't
    equip the Maxima package it generates with the metadata that allows to
    install the wxMaxima package shipped with Debian and Ubuntu.

  9.7  Uploading files

    $ sftp mysfusername,maxima@frs.sourceforge.net
    > cd /home/frs/project/m/ma/maxima
    > cd Maxima-Linux
    > mkdir 5.mm.nn-Linux
    > cd 5.mm.nn-Linux
    > lcd /path/to/rpms
    > put maxima-*5.mm.nn*.rpm
    > cd ..
    > mkdir 5.mm.nn-source
    > cd 5.mm.nn-source
    > lcd /path/to/tar.gz
    > put maxima-5.mm.nn.tar.gz
    > quit

  9.8  Announcements

    Post an announcement about every 5.mm.nn release to the Maxima
    mailing list. When it seems stable enough (i.e. no immediate plans
    to create another release) feel free to announce it in other forums,
    e.g. sage-devel.

    Since wxMaxima does do a simultaneous release with Maxima and
    windows installers containing wxMaxima and maxima are usually
    published within hours of the new Maxima release the wxMaxima
    developers beg to be informed in advance about the planned release
    date. Filing a ticket at http://wxmaxima-developers.github.com/wxmaxima/
    or sending the project maintainer an email should be sufficient
    for this task.

The following external tools are needed to build and/or use Maxima:

1) A supported Lisp implementation. See README.lisps.

2) To build Maxima in the standard manner, Bourne shell and make are
   required. See INSTALL.

3) Maxima can also be built using nothing except Lisp. See
   INSTALL.lisp.

4) Plotting uses gnuplot, <http://gnuplot.sourceforge.net>, by
   default. Plotting can also be done with Maxima's xmaxima
   application.

5) xmaxima requires Tcl/Tk, preferably version 8.5 or later.
   xmaxima is both one possible interface to  Maxima and a plotting
   program. As a graphical interface it is not required but as a
   plotting program it is required by some commands (plotdf, ploteq
   and scene).

6) drawdf requires Vtk and its bindings for Tcl/Tk.

7) The scene command requires python-vtk

8) Building Maxima from GIT additionally requires the GNU autotools.

Maxima 5.9.3 comes with documentation translated
into Portuguese and Spanish languages.

Configure options (see INSTALL for more details)

    --enable-lang-es
    --enable-lang-pt
    --enable-lang-es-utf8
    --enable-lang-pt-utf8

trigger building of corresponding language
pack.  Each language pack contains documentation
in info (for Maxima on-line help system) and
HTML formats.

First two configure options

    --enable-lang-es
    --enable-lang-pt

build language packs for locales in ISO-8859-1
(aka Latin1) encoding such as es_XX and pt_XX,
where XX is any valid country code.
This language packs work on all Lisp implementations.

Second pair of options

    --enable-lang-es-utf8
    --enable-lang-pt-utf8

build language pack for Unicode locales
(es_XX.UTF-8, pt_XX.UTF-8).
They are compatible only with Unicode-aware
Lisp implementations such as ccl, clisp, cmucl, ecl,
and sbcl.

Notes on Lisp implementations for Maxima:

Clisp, CMUCL, Scieneer Common Lisp (SCL), GCL (ANSI-enabled only),
ECL, ABCL and SBCL can compile and execute Maxima.
Allegro Common Lisp and OpenMCL might also work, but have not
been fully tested.

Ports to other ANSI Common Lisps should be straightforward
and are welcome; please post a message on the Maxima mailing list
if you are interested in working on a port.

When Maxima is recompiled, the Lisp implementation is selected by
an argument of the form `--enable-foolisp' for the configure script.
`./configure --help' shows a list of the Lisp types recognized by
configure (among other options). It is possible to specify several
Lisp type(s) you want maxima to be built with at the same time.
configure tries to autodetect the Lisp type if it is not specified,
but it has been reported that autodetection can fail.

--------------------------------------------------------------------
Comparison of execution times (in seconds) for the run_testsuite()
function for Maxima 5.36.0 as reported on the Maxima mailing list:

64 Bit (Gentoo Linux):

gcl-2.6.12    152
sbcl-1.2.10   155
ccl-1.10      313
ecl-15.3.7    559
clisp-2.49   1060

32 Bit (Gentoo Linux)
sbcl-1.2.10  170
gcl-2.6.12   177
cmucl-20e    253
ccl-1.10     293
ecl-15.3.7   556
clisp-2.49   844


--------------------------------------------------------------------
Clisp <http://clisp.org>

	Clisp can be built with readline support, so Maxima has
advanced command-line editing facilities when built with it.

Clisp is compiled to bytecodes, so Maxima running on Clisp is
substantially slower than on Lisps compiled to machine instructions.
On the other hand, Clisp contains code from CLN <http://www.ginac.de/CLN/>,
a library for efficient computations with all kinds of numbers in
arbitrary precision. Another advantage of clisp is that byte code
resulting in compiling a program on one computer might work on a
computer running a different Clisp version. Also Clisp uses an
extremely efficient memory handling which means it might not run
out of memory where ECL, SBCL and GCL do.

CLISP version 2.49 has a bug that causes it to output garbled data
if the front-end is fast enough to acknowledge a data packet while
the next data packet is still being prepared.

There are Clisp implementations for many platforms including
MS Windows and Unix-like systems.

Maxima compiled with a typical linux install of clisp 2.49.92
typically depends on the following libraries:

 * libc
 * libffcall
 * libreadline
 * libsigsegv
 * libtinfo
 * libunistring

--------------------------------------------------------------------
CMUCL <http://www.cons.org/cmucl/>

	CMUCL is a fast option for Maxima on platforms where it is
available. The rmaxima front-end provides advanced line-editing
facilities for Maxima when compiled with CMUCL. rlwrap is available
from <https://github.com/hanslub42/rlwrap> .

CMUCL versions: 18e and 19a and later are known to work.

There are CMUCL implementations only for Unix-like systems
(not MS Windows).

--------------------------------------------------------------------
Scieneer Common Lisp (SCL) <http://www.scieneer.com/scl/>

	Scieneer Common Lisp (SCL) is a fast option for Maxima for a
range of Linux and Unix platforms.  The SCL 1.2.8 release and later
are supported.  SCL offers a lower case, case sensitive, version which
avoids the Maxima case inversion issues with symbol names.  Tested
front end options are: maxima emacs mode available in the
interfaces/emacs/ directory, the emacs imaxima mode available from
https://sites.google.com/site/imaximaimath/, and TeXmacs available from
http://www.texmacs.org/

--------------------------------------------------------------------
GCL <http://savannah.gnu.org/projects/gcl/>

	GCL versions starting with 2.4.3 can be built with readline
support, so Maxima has advanced command-line editing facilities
when built with it. GCL produces a fast Maxima exectuable that
profit from GCL's fast bignum algorithms.

Only the ANSI-enabled version of GCL works with Maxima, i.e.,
when GCL is built, it must be configured with the --enable-ansi flag,
i.e., execute ``./configure --enable-ansi'' in the build directory
before executing make.

Whether GCL is ANSI-enabled or not can be determined by
inspecting the banner which is printed when GCL is executed;
if ANSI-enabled, the banner should say "ANSI".
Also, the special variable *FEATURES* should include the keyword :ANSI-CL.

There are GCL implementations for many platforms
including MS Windows and Unix-like systems.

Maxima compiled using a typical linux install using gcl 2.6.12
typically depends on:

 * libc
 * libgmp
 * libreadline
 * libx11
 * gcc

--------------------------------------------------------------------
SBCL <http://www.sbcl.org>

	SBCL is a fork of CMUCL which differs in some minor details,
but most notably, it is simpler to rebuild SBCL than CMUCL.
For many tasks a maxima compiled with SBCL is considerably faster than
GCL. For other tasks GCL is faster than SBCL.

As sbcl doesn't use readline it is recommended to use rmaxima for using
a command-line maxima with SBCL. For common details of SBCL and CMUCL
See CMUCL above.

Maxima compiled using a typical linux install using sbcl 1.4.10
typically depends on:

 * libc
 * zlib

--------------------------------------------------------------------
Allegro Common Lisp <http://franz.com/products/allegro-common-lisp/>

	Maxima should work with Allegro Common Lisp, but
only limited testing has been done with these Lisp
implementations. User feedback would be welcome.

--------------------------------------------------------------------
CCL <http://ccl.clozure.com/>

	CCL, formerly known as OpenMCL, is known to work with maxima on
all platforms where ccl runs including Linux, Mac OSX, and Windows.
There are appear to be some bugs in the 32-bit version of ccl,  but
the 64-bit version passes all tests.

--------------------------------------------------------------------
ECL <https://common-lisp.net/project/ecl/>

	ECL is known to work with maxima and passes the testsuite.  ECL
runs on many platforms and OSes and is the lisp compiler used for
maxima on android. It is faster than CLISP, but seems to tend more
towards fragmenting the available memory. ECL tends to be slower
than GCL or SBCL but faster than CLISP.

ECL must be configured to use the C compiler, building Maxima with the
ECL bytecode compiler is (currently) not possible.  So do *not* use the
option "--with-cmp=no" when building ECL.

Maxima compiled using a typical linux install using ecl 16.1.2
typically only depends on:

 * libc

--------------------------------------------------------------------
Armed Bear Common Lisp (ABCL) <https://common-lisp.net/project/armedbear/>

ABCL's main feature is that is tightly integrated into java.
That also means that it is an interpreter running in a virtual machine
which makes it even slower than clisp. Also java doesn't automatically
convert tail-recursive function calls to loops which means that in a
few functions might run out of stack space faster than other lisps.

Installing rpms
===============

There are three Maxima binary rpms:
maxima, maxima-exec-cmucl, and maxima-xmaxima.

The maxima and maxima-exec-cmucl rpms must be installed together.

maxima-exec rpms for other Lisp versions can also be installed,
although you'll probably have to build them yourself.

The maxima-xmaxima rpm is optional. Xmaxima is a Maxima GUI.


Building rpms
=============

You can build rpm files from an unpacked tarball or Git checkout.

(0) Go to the Maxima directory.

    $ cd sandbox/maxima  # or whatever is your top-level maxima directory

(1) Set the version number.

    Open ./configure.ac and change the AC_INIT line.
    (This is the only way I know to change the version number.)

    Optionally -- open ./maxima.spec.in and increment the `Release' number.
    (This number is appended to the version number.)

(2) Select Lisp version.

    Open ./maxima.spec.in.

    Change all `%define enable_<whatever>' to `0'
    except for the selected Lisp; make that `1'.

    Change all `%define <whatever>_flags' to `--disable-<whatever>'
    except for the selected Lisp; make that `--enable-<whatever>'.

(3) Build rpms.

    $ make rpm

    The maxima.spec file that is generated during this process builds
    four binary rpms:
    maxima, maxima-emacs, maxima-xmaxima, and maxima-exec-<whatever>.