
                                   Macaulay2
                   by Daniel R. Grayson <dan@math.uiuc.edu>
                and Michael E. Stillman <mike@math.cornell.edu>

                     available from http://Macaulay2.com/

We thank the United States National Science Foundation for generous funding
to develop Macaulay2.

Macaulay2 is copyright 1993-2014 by Daniel R. Grayson and Michael E. Stillman.
We permit you to use the source code under the terms of the GNU General Public
License (GPL), version 2 or 3, as published by the Free Software Foundation;
see the files Macaulay2/COPYING-*.  The packages contributed by various
authors, located in the directory Macaulay2/packages/, come with separate
licenses.  The binary distributions of Macaulay2 are licensed under GPL 
version 3.

This is free software.  There is no warranty; not even for merchantability or
fitness for a particular purpose.

This file describes how to build the software from sources and is not included
in binary distributions.  Most users will prefer to download a binary
distribution.

----------------------
Getting the source code
----------------------

The current development version of the source code can be obtained with this
command, assuming you have installed "git" on your machine:

    git clone https://github.com/Macaulay2/M2

A directory called M2, which you can move or rename, will be created, and this
INSTALL file is in the subdirectory "M2" of it.  After cloning, you can switch
to the branch containing version 1.6 with the following command:

    git checkout release-1.6

The following command shows the list of release branches:

    git branch -a | grep origin/release

The following commands will download the latest changes to the source code:

    git pull
    git submodule update

---------
Programs
---------

Here are programs you may have to install on your system to build Macaulay2.

   program: fakeroot
    get at: http://ftp.debian.org/debian/pool/main/f/fakeroot
     notes: You need this only if you intend to make a debian distribution
            package for Macaulay2.

   program: rpmbuild
     notes: needed only if you want to make an rpm distribution file

---------
Libraries
---------

Here are some libraries you may have to install on your system to build
Macaulay2.  If your operating system distinguishes between development
versions and run-time versions of the libraries, you will need the development
version.

Here are commands that will get you a good development environment under
various modern operating systems:

  Debian:
    Install packages with:
      sudo apt-get install -y -q autoconf bison curl emacs flex g++ gcc gfortran libboost-dev libc6-dev libcdd-dev libgc-dev libgdbm-dev libglpk-dev libgmp3-dev liblapack-dev liblzma-dev libmpfr-dev libncurses5-dev libntl-dev libpari-dev libreadline-dev libtool libxml2-dev libz-dev make openssh-server pkg-config subversion xbase-clients unzip pinentry-curses
    On all systems, add
        --enable-build-libraries="ntl pari"
      to the "configure" command line below.
    On a 32-bit system, add
        --with-mpir-config-options="ABI=32 --build=i686-pc-linux-gnu"
      to the "configure" command line below.  (The --build option is necessary
      only to enable distribution of the resulting binaries to users of other
      hardware.) 

  Ubuntu:
    Install packages with:
      sudo apt-get install -y -q autoconf bison emacs flex g++ gcc gfortran libc6-dev libcdd-dev libgc-dev libgdbm-dev libglpk-dev liblapack-dev libmpfr-dev libncurses-dev libncurses5-dev libntl-dev libpari-dev libreadline-dev libxml2-dev liblzma-dev libz-dev make openssh-server patch subversion time unzip xbase-clients zlib1g-dev libtool pkg-config
        # note: libz-dev seems to have been replaced by zlib1g-dev
        # note: libncurses-dev seems to have been replaced by libncurses5-dev
        # note: libreadline-gplv2-dev is an older GPL v2 version of libreadline
    On all systems, add
        FC=gfortran
      to the environment or to the "configure" command line below.  (The
      program "make" has a default value of "f77" for "FC", the Fortran
      compiler, but "f77" isn't available.)
    On a 32-bit system, add
        --with-mpir-config-options="ABI=32 --build=i686-pc-linux-gnu"
      to the "configure" command line below.  (The --build option is necessary
      only to enable distribution of the resulting binaries to users of other
      hardware.) 
    On Ubuntu 14.10 and later, add
        --enable-build-libraries=pari
      to the "configure" command line below.  (The version of pari possibly installed there
      will crash when M2 exits.)
    (To upgrade to a new release of Ubuntu, run "update-manager" if you want a GUI, or run
    "do-release-upgrade" for a command line interface.)

  Raspbian:
    Install packages with:
      sudo apt-get install -y -q autoconf bison curl emacs flex g++ gcc gfortran libc6-dev libcdd-dev libgc-dev libgdbm-dev libglpk-dev libgmp3-dev liblapack-dev libmpfr-dev libncurses-dev libntl-dev libpari-dev libreadline-dev libxml2-dev libz-dev make openssh-server subversion xbase-clients time libtool
    On a 32-bit system, add
        --with-mpir-config-options="ABI=32 --build=i686-pc-linux-gnu"
      to the "configure" command line below.  (The --build option is necessary
      only to enable distribution of the resulting binaries to users of other
      hardware.) 
    The Raspberry Pi comes with 512MB of RAM and a swapfile /var/swap of size 100MB.  It's a good idea to
     increase the swap size to 1000MB by editing /etc/dphys-swapfile .

  Fedora:
    Install packages with:
      sudo yum -y install autoconf bison boost-devel cddlib-devel emacs factory-devel fakeroot flex gc-devel gcc-c++ gdbm-devel git glpk-devel gmp-devel kernel-devel lapack-devel libatomic_ops-devel libfac-devel libgfortran-static libtool libxml2-devel mpfr-devel mpir-devel ncurses-devel ntl-devel pari-devel patch readline-devel rpm-build rpm-sign rpmdevtools subversion
    Some debugging aids:
      sudo debuginfo-install strace

  Scientific linux:
    Install packages with:
      sudo yum install -y autoconf bison boost-devel emacs flex gc-devel gcc-c++ gcc-gfortran gdbm-devel glpk-devel gmp-devel lapack-devel libatomic_ops-devel  libtool libxml2-devel mpfr-devel ncurses-devel readline-devel rpm-build rpm-sign subversion zlib-devel xz-devel
    Some debugging aids:
      sudo yum install -y strace
    Note: Scientific Linux 7.1 has a modern version of gcc (version 4.8.3).  By contrast,
      Scientific Linux 6.5 has an old version (4.4.7) of gcc that may not work with a
      future version of Macaulay2.  However, one can install newer compilers
      (4.8.2) from the repository of the "Scientific Linux CERN 6" distribution,
      (see http://linux.web.cern.ch/linux/devtoolset/) using the following commands.
	  wget -O /etc/yum.repos.d/slc6-devtoolset.repo http://linuxsoft.cern.ch/cern/devtoolset/slc6-devtoolset.repo
	  yum install devtoolset-2-gcc devtoolset-2-gcc-g++ devtoolset-2-gcc-gfortran devtoolset-2-binutils
      Then use
	  . /opt/rh/devtoolset-2/enable
      to update the environment of your currently running shell.  The latter
      command will also work in your shell initialization file, ".profile".

  Suse64:
    sudo zypper install -y autoconf bison createrepo emacs flex gc-devel gcc gcc-c++ gcc-fortran gcc43 gcc43-c++ gcc43-fortran gdbm-devel gmp-devel lapack libgmp3 libxml2-devel make mpfr-devel ncurses-devel patch readline-devel subversion zlib-devel libtool

  Arch Linux:
      sudo pacman -S archlinux-keyring
      sudo pacman-key --populate archlinux
      sudo pacman -S make autoconf automake pkg-config gcc gcc-fortran mpfr ntl flint lapack glpk cddlib boost gtest gfan nauty bison unzip flex time
    If the package "pari" is also installed on your system, remember to add
    	--enable-build-libraries=pari
    to the "configure" command line below in the section on compiling Macaulay2, because the installed library seems to
    crash when the program terminates (when the exit handlers are executed, it dies in the function "closepari".)

  Mac OS X:
    Install the Xcode Command Line Tools, available from Apple.  After upgrading the OS,
      it will be necessary to reinstall it.  One may use the following command for installing it:
      	 xcode-select --install
    Optionally install a good version of emacs, such as the one available from 
      http://emacsformacosx.com/, which is a native Mac OS X port of emacs. To
      run it from the command line, create an executable shell script called 
      "emacs" with this line in it:
        exec /Applications/Emacs.app/Contents/MacOS/Emacs "$@"
    Install "homebrew", available from http://brew.sh/.  (Experts who want to install
      homebrew somewhere other than in /usr/local may prefer to point a browser
      at https://github.com/Homebrew/homebrew/tarball/master, which will download
      a tar file that can be untarred anywhere and renamed.)
    Install the programs and libraries needed for building:
	brew tap homebrew/versions
	brew tap homebrew/science
	brew tap homebrew/homebrew-x11
	brew install gcc49 pkg-config autoconf automake gnu-tar libtool boost
	brew install --build-from-source --cc=gcc-4.9 bdw-gc libatomic_ops gdbm gmp pari cddlib glpk flint
    Note: the reason we compile from source with gcc is that the precompiled
      packages that brew would otherwise download are compiled using "clang"
      and assume that the CPU supports advanced vector extensions, which not
      all of the machines of our users do.
    Now remember to add 
        --enable-build-libraries="pari flint readline" CC="gcc-4.9 -mtune=generic" CXX="g++-4.9 -mtune=generic"
      to the "configure" command line below in the section on compiling Macaulay2.
    Note: the compiler option "-mtune=generic" ensures that gcc generates code that
      will run on the most commonly available CPUs.  If you won't be distributing the
      code to others, it can be omitted.
    Note: including "readline" in the "--enable-build-libraries" option is
      necessary because it doesn't seem to be possible to recompile it from
      source; the binary distribution used by homebrew uses "clang", which will
      optimize the code in "gc" for your particular CPU.  If you won't be
      distributing the code to others, it can be omitted.
    Note: under Mac OS version 10.10 (Yosemite), the test for whether compiling with
      g++-4.9 and then linking with gcc-4.9 works may fail, in which case adding
        MACOSX_DEPLOYMENT_TARGET=10.9
      to the environment (e.g., with the "sh" command
        export MACOSX_DEPLOYMENT_TARGET=10.9
      ) may help.  Apparently the tools have trouble determining that 10.10 is a
      newer version number than 10.9.  Linking alternatively with libgcc_eh
      seems to break C++ exception handling.
    Note: homebrew uses /usr/bin/gcc to compile its libraries.  If compiling
      with clang instead of gcc, then run this first:
        brew install gmp mpfr
    Note: software installed by "fink", if not kept up to date, can interfere
      with the Macaulay2 build process.  To test, for example, whether the
      correct version of "automake" is available, run the shell command
        type automake
      and expect to see /usr/local/bin/automake, as opposed to
      /sw/bin/automake.  Since homebrew suffices for most purposes, it's
      probably best to just remove fink entirely, with the command
        sudo rm -rf /sw

  Cygwin 1.7 under Microsoft Windows:
    Use setup to install these packages:
	autoconf automake bison emacs-X11 file flex gcc-core gcc-fortran
	gcc-g++ git libatomic_ops-devel libboost-devel libgc-devel
	libgdbm-devel libglpk-devel liblapack-devel libmpfr-devel
	libncurses-devel libreadline-devel libstdc++6-devel libtool
	libxml2-devel make patchutils pkg-config time unzip wget
    You may also want these:
        ctags emacs-el gdb gvim libxml2-doc openssh psmisc vim xauth xconsole
        xinit xkill xterm
    After installing xinit, the program "startxwin" can be used to start X Windows.

----------------------
  Compiling the most recent GNU C compiler
----------------------

  It may happen that you need a modern version of the GNU C compiler, but you
  have no way to download a binary distribution of it, or you have no way to
  use "brew" or "fink" to download and compile it for you.  In that case, you
  may download, compile, and install the GNU C compiler (without necessariy
  having root access) as follows.  Change "$HOME/local" below to the path to
  the directory where you want to install the files; if it's a directory not
  owned by you, prefix the "make install" command below with "sudo".

       wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
       tar xjf gcc-4.8.2.tar.bz2
       cd gcc-4.8.2
       ./contrib/download_prerequisites
       cd ..
       mkdir gcc-4.8.2-build
       cd gcc-4.8.2-build
       ../gcc-4.8.2/configure --prefix=$HOME/local --program-suffix=-4.8.2 --enable-languages=c,c++,fortran --disable-multilib
       make
       make install

     Do not omit the language "fortran" from the list, even if the package
     "lapack-devel" is installed, as "gfortran" is consulted for the locations
     of its libraries, and it would be bad to have a mismatch.

     It might be possible to add --disable-libstdcxx to the "configure"
     command line above, allowing the resulting binaries to depend on the
     version of libstdc++ already installed on your system.

     The resulting compiler executables will be named gcc-4.8.2 and g++-4.8.2.
     Now put the following lines in your file $HOME/.profile :

        export PATH=$HOME/local/bin:$PATH
        export MANPATH=$HOME/local/share/man:$MANPATH
        export INFOPATH=$HOME/local/share/info:$INFOPATH
        export LD_LIBRARY_PATH=$HOME/local/lib:$HOME/local/lib64:$LD_LIBRARY_PATH
        export CC=gcc-4.8.2
        export CXX=g++-4.8.2
        export FC=gfortran-4.8.2

     and then log out and log in again (or source the file into your
     environment and continue in the same process or in daughter processes).

     Under Scientific Linux 6.4, if you run "sudo yum install -y glibc-devel.i686"
     first, then you can omit --disable-multilib above and get a 32 bit
     compiler, too.  To see quickly which glibc architectures are installed,
     run "ls /usr/include/gnu/stubs-*.h".  (Parenthetically, we observe that to
     make /usr/bin/gcc successfully compile 32 bit binaries, one should also
     run "yum install -y libgcc.i686".)

     Any other libraries you may want to use may also be installed with
     $HOME/local as the install prefix, as gcc-4.8.2 will automatically search
     in there for include files and libraries.

     Installing multiple software in the same directory, such as in $HOME/local
     (as described above), makes it hard to remove or upgrade packages.  To
     solve that problem, use the program "epkg", available from
     http://www.encap.org/epkg/.

----------------------
Choosing a place for the repository
----------------------

A typical Macaulay2 build directory can use up 1.5GB of disk space, and in an
institutional environment your home directory is probably backed up to tape.
(You may do something similar on your own computers.)  Thus you can avoid an
unnecessary burden on your system administrator if you put the repository (or
at least the build directories) on a locally mounted scratch drive, where the
files are not backed up.  For your changes to Macaulay2 source code, github.com
will serve as your backup.

-----------------------
Compiling Macaulay2
-----------------------

Now the directory to be in is the one containing this file in the source
distribution -- it is called "M2", and is a subdirectory of the top level
directory of the source tree.  If you are reading this file on the web, it may
be more convenient to switch now to reading it in its location in the source
tree.

Begin with this command:

        make

The "make" command above runs the commands "autoconf" and "autoheader", which
create the "configure" script and the "include/config.h.in" file, needed in the
next steps.  Once those files are created, it is not necessary to make them
again.  The "make" command on your system should be a recent version of GNU
make.

Now continue building the program this way:

        ./configure --enable-download
        make
        make check                      # optional
        make install

Remember to add any options specified above, in the section for your particular
operating system, to the "configure" command line.

To take advantage of parallelism when running "make", append an option of
the form "-jN" to the command line, where "N" is replaced by the number of
processors you wish to devote to the task.  (Our makefiles are just begining to
take advantage of this.)

To skip the running of the NTL "wizard", which conducts time consuming
experiments to optimize the speed of its code, before compiling it, add the
option --disable-ntl-wizard to the "configure" command line above.

By default, the files are installed in appropriate subdirectories of
/usr/local.  To specify a different location (prefix) you may use an option to
the configure script:

        ./configure --enable-download --prefix=/foo/bar

Files will then be installed in the following directories:

        /foo/bar/bin
        /foo/bar/share/Macaulay2
        /foo/bar/share/doc/Macaulay2
        /foo/bar/share/man/man1
        /foo/bar/share/emacs/site-lisp
        /foo/bar/lib/Macaulay2

instead of in

        /usr/local/bin
        /usr/local/share/Macaulay2
        /usr/local/share/doc/Macaulay2
        /usr/local/share/man/man1
        /usr/local/share/emacs/site-lisp
        /usr/local/lib/Macaulay2

To use a different prefix, say $HOME/local, for finding libraries and include
files installed in a nonstandard location, add the following options to the
"configure" command line:
        LDFLAGS=-L$HOME/local/lib CPPFLAGS=-I$HOME/local/include
That step is unnecessary if the compiler was compiled from sources and installed
with that prefix.

To use a different compiler suite, such as gcc version 4.8.2 as compiled above,
add something like the following to the "configure" command line:
        CC=gcc-4.8.2 CXX=g++-4.8.2 FC=gfortran-4.8.2
That step is unnecessary if the environment variables CC and CXX are set as
described above.

To specify libraries to link against during configuration, use the LIBS
environment variable, as described in documentation for autoconf.  For example,
to link with libfoo, add the following option to the "configure" command line:

        LIBS=-lfoo

To see descriptions of all the environment variables that influence
configuration, run this command and look at the section of the output
entitled "Some influential environment variables":

        ../../configure --help

The only one of these variables with a nonempty default value is
CFLAGS, and its default value is "-g -O2".  That will be supplanted if
you override it.

To specify a different installation location for the "make install" command you
may add an option to the "make install" line, as follows:

        make install prefix=/foo/bar

To make an encapsulated directory tree or distribution tarball suitable for use
with the program "epkg" (see http://www.encap.org/epkg/), add the option

        --enable-encap

to the "configure" command above.

The effect is to insert one more component into the path names used at
installation time, so that in response to 

        make prefix=/foo/bar install

files will be installed in the following directories:

        /foo/bar/Macaulay2-*/bin
        /foo/bar/Macaulay2-*/share/Macaulay2
        /foo/bar/Macaulay2-*/share/doc/Macaulay2
        /foo/bar/Macaulay2-*/share/man/man1
        /foo/bar/Macaulay2-*/share/emacs/site-lisp
        /foo/bar/Macaulay2-*/lib/Macaulay2

Each * above is replaced by the current version number.  There will
also be a few extra files placed in the directory /foo/bar/Macaulay2-*
which instruct epkg how to make appropriate symbolic links to install
our program, and how to initialize the dumped data file, if present:

        /foo/bar/Macaulay2-*/encapinfo
        /foo/bar/Macaulay2-*/postinstall
        /foo/bar/Macaulay2-*/preremove

-------------------------------------------
Compiling on multiple machine architectures
-------------------------------------------

If multiple machine architectures are supported by your hardware and operating
system, a good way to specify which one to use is to use the build option to
autoconf's configure script with an architecture in config.guess format, as
well as to specify names for the compilers that include the additional options
for the architecture to be used.  This will work with gmp, for example, as it
knows how to produce the additional options to the compilers:

   ../../configure --build=x86_64-apple-darwin CC="gcc -m64" CXX="g++ -m64"

Another way to do it is to add the architecture option to CFLAGS and to
CXXFLAGS.  The disadvantage of that approach is that the package might have its
own idea about what values to use for those options and ignore these settings:

   ../../configure CFLAGS="-O2 -m64" CXXFLAGS="-O2 -m64"

Sometimes a library will get confused by values for CC and CXX with spaces in
them, or will try to parse the options, and get confused by the "-m64" option.
In that case, the work-around is to create shell scripts on your path called
something like gcc-m64 and g++-m64 that can be used as the compilers, and to
use this instead.  In the shell script gcc-m64 put this single line:

     exec gcc -m64 "$@"

In the shell script g++-m64 put this single line:

     exec g++ -m64 "$@"

Mark both shell scripts executable.

----------------------
MacOS X notes
----------------------

    The standard gcc under Mac OS X is actually "clang", is based on LLVM, and
    has been buggy, so we compile the latest gcc or we use "brew" to install
    it, as described above.

    To build Macaulay, add the option

        --build=x86_64-apple-darwin

    to the appropriate "configure" command line above, for else it will try to
    build a 32 bit version of Macaulay2.

    Recall that if you are using version 4.8 of gcc, as installed by homebrew,
    you should add

        CC=gcc-4.8 CXX=g++-4.8

    to the "configure" command line (or, better, to your environment setting in
    your .profile).  To sum up, your command line, with all those options, will
    look something like this:

        ../../configure --enable-download --prefix=/foo/bar --build=x86_64-apple-darwin CC=gcc-4.8 CXX=g++-4.8

----------------------
Rerunning the package examples
----------------------

Some packages cache their example output in the source code tree, since they
depend on the presence of external programs not included with Macaulay2.  Here
we briefly summarize them and the software they depend on:

    gfanInterface StatePolytope need polymake, builds OK
	    http://polymake.org/lib/exe/fetch.php/download/polymake-2.13-1.tar.bz2
	    (Make 3.81 has a problem with their makefile, so use 4.0)

    Bertini needs bertini:
	    http://www.nd.edu/~sommese/bertini/BertiniSource_v1.4.tar.gz
	which needs gmp and mpfr:
	    https://gmplib.org/download/gmp/gmp-6.0.0a.tar.xz
	    http://www.mpfr.org/mpfr-3.1.2/mpfr-3.1.2.tar.xz

    PHCpack needs PHCpack, download the binary:
	    http://www.math.uic.edu/~jan/x86_64phcv23p.tar.gz

    AdjointIdeal ConvexInterface MapleInterface Parametrization need Maple.

    ConvexInterface also needs the maple package "convex" installed.  See the 
    package documentation for hints about installing it.
    	    http://www.math.uwo.ca/~mfranz/convex/files/current/convex.m

----------------------
Warning messages
----------------------

	-  warning: -jN forced in submake: disabling jobserver mode

	   This message can be ignored, if the previous recursive make command
	   had -j1 as an option, as -j1 implies the use of just one processor,
	   anyway.  (We use -j1 as an option when compiling third party libraries
	   whose makefiles are not known to support parallelism.)

----------------------
Autoconf, autoreconf, libtool, ...
----------------------

If you get any mysterious error messages involving autoconf, autoreconf,
libtool, etc., try running

	 make -f Makefile get-tools

in the top level.  This command will install versions of those tools known to
work with Macaulay2.

