*****************************************************
    * THE MAGMA DISTRIBUTION: INSTALLATION INSTRUCTIONS *
    *****************************************************


If you have downloaded the shared_complete.tar.gz file and executable(s),
then the distribution will consist of:

    shared_complete.tar.gz		All other files needed for Magma.

    magma.exe.gz			Standard executable
    magma.exe.*.gz			Other executables (optional)

and after shared_complete.tar.gz is untarred, you will at least have:

    INSTALL.txt				This file
    README.txt				Documentation information for users

If you have downloaded the separate shared files and executable(s),
you should have:

    INSTALL.txt				This file
    README.txt				Documentation information for users

    magma.exe.gz			Standard executable
    magma.exe.*.gz			Other executables (optional)
    package.tar.gz                      Magma standard packages

    extern.tar.gz                       External shared libraries for executable

    magma				Magma driving script

    libs.tar.gz                         Magma databases and libraries (default)

    doc.tar.gz				Documentation
    ThirdParty.tar.gz			Information and licenses for third
    					party libraries used by Magma

Simply follow the installation procedure below to install Magma.


			    ***************
			    * PATCH NOTES *
			    ***************

Please see the latest patch notes at:

    https://docs.magma-maths.org/patchnotes/


			**************************
			* INSTALLATION PROCEDURE *
			**************************


Here we give the Magma installation procedure which assumes the files
are in the gzip-compressed format.  The utility 'gunzip' should be in
your path (usually it is in /usr/local/bin).  We suppose that all the
Magma files are to be installed in the directory /usr/local/magma and
that the Magma driving script "magma" is to be installed as
/usr/local/bin/magma; change these to whatever is appropriate in the
following.

(0)	Make sure you have received a password file 'magmapassfile' from
	us (mail us at magma@maths.usyd.edu.au if you have not yet).

	Make sure that the file is readable by all by typing the command:

		chmod a+r magmapassfile

	Place the file in the directory in which you have downloaded
	the other Magma files.  This is all that needs be done for this
	file: the 'magma' script mentioned below should point to it at
	the end of the installation.

(1)	Make the directory /usr/local/magma, move all the Magma files into
	/usr/local/magma, and then change directory there by typing:

		cd /usr/local/magma

(2)	Unpack the executable and fix its permissions by one of the following:

	(a) First type:

		gunzip magma.exe
		chmod 755 magma.exe

	    If you have downloaded another executable such as
	    magma.avx2.exe.gz then rename it first, as follows:

		gunzip magma.avx2.exe
		mv magma.avx2.exe magma.exe
		chmod 755 magma.exe

(3)	If you downloaded the shared_complete.tar.gz file, unpack it by:

		gunzip < shared_complete.tar.gz | tar xopf -

	(The 'o' flag to tar ensures that the files will be unpacked with
	root ownership if you are running as root.  If your machine does
	not allow the 'o' flag, just omit it, or choose something else
	appropriate.  The 'p' flag ensures that the correct permissions
	are extracted from these files.)

(4)	Otherwise, you will need to unpack the individual .tar.gz files
	mentioned above:

		gunzip < extern.tar.gz | tar xopf -
		gunzip < ThirdParty.tar.gz | tar xopf -
		gunzip < doc.tar.gz | tar xopf -
		gunzip < libs.tar.gz | tar xopf -
		gunzip < package.tar.gz | tar xopf -

	(The 'o' flag to tar ensures that the files will be unpacked with
	root ownership if you are running as root.  If your machine does
	not allow the 'o' flag, just omit it, or choose something else
	appropriate.  The 'p' flag ensures that the correct permissions
	are extracted from these files.)

(5)	Edit the magma script and change the ..... to /usr/local/magma
	(or wherever you are installing Magma) so that all files and
	directories in the script are referred to correctly.

	Ensure that it is executable:

	    chmod 755 magma

	IMPORTANT: The various extracted files should have the correct
	permissions, but sometimes these can be lost.  All the files
	need to be readable by everyone who will be using Magma.  One
	way to ensure this is to run the following two commands in the
	Magma installation directory:

	    find . -type d -exec chmod go+rx '{}' ';'
	    find . -type f -exec chmod go+r '{}' ';'

(6)	Put a link from /usr/local/bin/magma to /usr/local/magma/magma by:

		ln -s /usr/local/magma/magma /usr/local/bin/magma

(7)	Try running magma by:

		magma

	(perhaps type "rehash" first if you use csh).  You can test the
	Help system by typing ? at the Magma prompt.  The Magma system
	packages should be automatically loaded also (you will not
	see any complaint if this is so).  If you get some error
	messages to do with packages, check that package.tar.gz was
	unpacked correctly and that the environment variable
	MAGMA_SYSTEM_SPEC is set correctly to the file "spec" in the
	root of the package directory.





			*********************
			* FILES DESCRIPTION *
			*********************


A short description of each of the (uncompressed) files follows.


INSTALL.txt
-----------

This file.


README.txt
----------

A file similar to this one describing the files but intended for the
users, not the system manager.


ThirdParty.tar
--------------

Information about and licenses for the third party libraries used by
Magma.


extern.tar
----------

A tar file which consists of a collection of shared libraries which must
be present for the executable to run.  Make it is in the same directory
as where the executable is.


doc.tar
-------

A tar file which contains the directory "doc" which contains the Magma
documentation.


magmapassfile
-------------

The password file which tells Magma what are the valid hosts on which
Magma can be run for your licence.  If you wish to add more hosts
within your licence, or change the hosts on which you wish to run
Magma, all you need do is contact us with the list of hostids for the
appropriate machines.  We can then create a new password file for the
new list and send it to you -- nothing else in the distribution need be
changed.


magma, magma.exe
----------------

Magma consists of the binary executable "magma.exe" and a driving shell
script "magma" which sets some environment variables first so the
executable "magma.exe" can find the password file "magmapassfile",
etc.

The shell script "magma" simply sets the environment variable
MAGMAPASSFILE so that the executable "magma.exe" can find the password
file.  Other environment variables are also set.  The first line of the
script runs:

	ROOT=.....

To install the Magma executable, change the ..... to the root directory
in which the executable magma.exe is installed.

Make sure the executable file magma.exe is publically executable by all
users of Magma.


package.tar
-----------

A tar file which contains the directory "package" which has the Magma
system packages used by Magma internally.  It should be installed in a
publically-readable place and the environment variable
MAGMA_SYSTEM_SPEC should be set to the file "spec" in its root.


libs.tar
--------

libs.tar is a tar file which consists of a collection of libraries
for use with Magma.  When un-tarred, there is a directory 'libs' which
contains each library in a subdirectory and two shell scripts PATH.sh
and PATH.csh to set the environment variables MAGMA_LIBRARY_ROOT and
MAGMA_LIBRARIES to access the libraries.

There are other databases not included in the libs tar by default;
these may be downloaded from the 'Optional Databases' section of the
Downloads area of the Magma website.


Problems
========

For all enquiries and problems please mail us at:

        magma@maths.usyd.edu.au