Document the issue reported as https://sourceforge.net/p/maxima/bugs/4086/

[maxima/cygwin.git] / INSTALL.win32

Executive Summary
=================

Maxima can now be built under Windows without recourse to any
Unix-like utilities. To do so, follow the purely lisp-based build
procedure in INSTALL.lisp.

Maxima can be simply compiled and installed under MSYS or Cygwin by
following the GNU Autotools instructions in INSTALL. With a few more
steps, Maxima will create a windows installer executable.  The
instructions for doing so are contained in this file. Note, however,
that this process is not as polished as the Unix-like install process.

In order to create the Maxima Windows installer from the maxima tarball 
distribution, I do the following in a MSYS window:
----------------------------------------------------
./configure --prefix=c:/maxima \
    --enable-chm \
    --enable-xmaxima-exe \
    --with-hhc=<path-to-hhc> \
    --enable-lang-es --enable-lang-pt --enable-lang-pt_BR
make
make install
make iss
----------------------------------------------------
Then run Inno Setup on the generated maxima.iss file. That is all it
takes.


External Requirements
=====================

1) MSYS+MinGW, including mktemp
2) msysDTK
3) GCL
4) Tcl/Tk (8.5 or later recommended)
5) Starkit, TclKit and img.kit
6) Vtk
7) InnoSetup
8) gnuplot
9) wxMaxima
10) Microsoft HTML Help Workshop
11) Perl 5.8 (ActivePerl)
12) Python 

Detailed Instructions
=====================

The instructions below apply to the maxima release tarball. In order
to build from the git repository, git, autoconf and automake are also
required. Follow the directions in INSTALL.git before proceeding.

1) Get a working msys+mingw installation from www.mingw.org. 

Option A - gcc-3.3.1 based system

From 2006 until 2012, it was essential to install the versions of gcc and
binutils listed here to obtain a working gcl.  The files are available
from <https://sourceforge.net/projects/mingw/files/>:
   a) Get and install MinGW-3.1.0-1.exe
   b) Install MSYS-1.0.10.exe 
      The installer should magically find your mingw installation
      and add it to your path.
   c) Install tcltk-8.4.1-1.exe
      Install it into directory where MSYS/MinGW can find it,
      for example mingw/bin directory.
   d) Install gcc-3.3.1
   e) Install binutils-2.14.90 from 
      ftp://ftp.sf.net/m/mi/mingw/binutils-2.14.90-20030807-1.tar.gz
   f) Install msysDTK-1.0.1.exe
      It provides Perl and autotools (autoconf/automake).
      msysDTK-1.0.1 comes with Perl version 5.6.  This is now too old.
      Since Maxima 5.11 we require version 5.8. 

      or install

      - automake msys-autoconf-2.59.tar.bz2
      - autoconf msys-automake-1.8.2.tar.bz2
      - libtool msys-libtool-1.5.tar.bz2
   g) Download the MinGW implementation of mktemp from: 
      http://downloads.sourceforge.net/mingw/mktemp-1.5-MSYS.tar.bz2 (4 Kb)
      Install by (cd /; tar xjf /path/to/mktemp-1.5-MSYS.tar.bz2)

NOTE: gcc 3.3.3 and gcc 3.4.0 do NOT work; likewise binutils 2.13.90
and 2.15.90, but 2.17.50-20060824 is OK.

This is output of msysinfo command for MSYS system with
all required components:
-----------------------------------------------------------------
MSYS 1.0.10(0.46/3/2) 2004-03-15 07:17 i686 unknown; targ=MINGW32
GNU bash, version 2.04.0(1)-release (i686-pc-msys); ENV=.profile
GNU Make version 3.79.1,Built for i686-pc-msys; MAKE_MODE=unix
gcc.exe (GCC) 3.3.1 (mingw special 20030804-1); targ=MINGW32
GNU ld version 2.14.90 20040120
   789320 Tue Mar 16 10:32:49 2004 /bin/msys-1.0.dll
    52064 Thu Jan 02 05:05:27 2003 /bin/msysltdl-3.dll
   135680 Tue Mar 16 10:32:48 2004 /bin/make.exe
    84992 Thu Aug 07 23:29:00 2003 /mingw/bin/gcc.exe
   617472 Tue Jan 20 21:57:52 2004 /mingw/bin/ld.exe
-----------------------------------------------------------------

Option B - gcc-4.6.2 based system

From early 2012 it has been possible to build maxima using current 
msys, mingw and gcc-4.6.

a) Download mingw installer mingw-get-inst from http://www.mingw.org/
b) Run the installer to install mingw and msys
c) Use the installed mingw-get to add the build dependencies, including
   - mingw-gcc
   - mingw-binutils
   - mingw-make
   - mingw32-autotools

maxima-5.27.0 was successfully built using
  MSYS 1.0.17(0.48/3/2) 
  GNU bash, version 3.1.17
  GNU Make 3.81
  gcc.exe (GCC) 4.6.2
  GNU ld (GNU Binutils) 2.22

2) Get a working GCL 

Get the GCL 2.6.8pre from CVS.  
See  <http://savannah.gnu.org/projects/gcl/>. 

Then compile and install under mingw/msys with

./configure --enable-ansi
make
make install

Check that gcl works by typing gcl at MSYS command line
-----------------------------------------------------------------------
$ gcl
GCL (GNU Common Lisp)  2.6.8 ANSI    Nov 11 2006 23:08:49
Source License: LGPL(gcl,gmp), GPL(unexec,bfd,xgcl)
Binary License:  GPL due to GPL'ed components: (UNEXEC)
Modifications of this banner must retain notice of a compatible license
Dedicated to the memory of W. Schelter

Use (help) to get some basic information on how to use GCL.
Temporary directory for compiler files set to C:/DOCUME~1/user/LOCALS~1/Temp/

>(quit)
-----------------------------------------------------------------------

3) Download tclkitsh-8.6.3-win32-ix86.exe and
tclkit-8.6.3-win32-ix86.exe from
<http://tclkits.rkeene.org/fossil/wiki?name=Downloads> and put them in
c:/programs/star.


4) Get and install Inno Setup from
<http://www.jrsoftware.org/isinfo.php>. 

5) Download the gnuplot windows binary from <http://gnuplot.sourceforge.net>.
It is recommended to use version 4.6 patchlevel 3 or more recent (If you
do have to use an older version, read the Maxima documentation for variable
gnuplot_view_args).  
Install gnuplot in your MSYS user home directory in ~/programs/gnuplot 

6) Compile wxMaxima for windows from <https://wxmaxima-developers.github.io/wxmaxima/>.
Use wxMaxima 0.6.5 with Maxima 5.9.3 or earlier, 
wxMaxima 0.7.0 with Maxima 5.10.0,
and wxMaxima 0.7.1 with Maxima 5.11.0.

Install it to default location, say C:\Program Files\wxMaxima. 
Then copy contents of wxMaxima directory excluding \uninst subdirectory
to your MSYS user home directory ~/programs/wxMaxima

NOTE: Location of Starkit/TclKit, gnuplot and wxMaxima is controlled
by the override-able variables and their defaults are:
 
TCLKITSH = tclkitsh.exe
TCLKITDIR = ../../../../programs/star
SDXDIR = $(TCLKITDIR)
GCCPREFIX=/mingw
GNUPLOTDIR = ../../../../programs/gnuplot
WXMAXIMADIR = ../../../../programs/wxMaxima

To see how they are used, look in interfaces/xmaxima/win32/Makefile.in
and Makefile.am in the top level maxima directory.  You may change
their values according to your preferences.

7) Install Microsoft HTML Help Workshop from
<http://www.microsoft.com/en-us/download/details.aspx?id=21138>.

Make sure that HHW directory is within PATH (edit PATH environment
variable with either Windows or MSYS approach), so the HTML Help Workshop
compiler command "hhc.exe" is available at the MSYS command prompt.

For reference, to change PATH within MSYS only, edit the file
c:\msys\1.0\etc\profile and add the following line after the initial
setting of PATH:
    export PATH="/c/gcl/bin:$PATH"

8) Install Perl 5.8.  ActivePerl binaries provided by
    http://www.activestate.com work.  Again add the perl bin
    directory to PATH.  Alternatively use a wrapper script like

    $ cat /usr/local/bin/perl
    #!/bin/sh
    exec /c/perl/bin/perl $@

9) Install Python 2.6. ActivePython binaries provided by
    http://www.activestate.com work.

10) Following components
    a) tcltk (e.g. wish84 command), 
    b) gcl (gcl command),
    c) HTML Help Workshop compiler (hhc command)
    d) perl
    e) python
should also be available at the MSYS command prompt.

If this is not the case, edit your PATH variable or add wrapper scripts.

11) You should now be ready to compile and install maxima. 
Configure maxima so that it will install in some sort of temporary
directory. The directory does not need to exist ahead of time.

./configure --prefix="c:/maxima" \
  --enable-lang-es --enable-lang-pt --enable-lang-pt_BR
make
make check
make install
make iss

The "check" should pass all tests except those listed as known
failures.

11) Once "make iss" is complete, run Inno Setup on the maxima.iss
file. It is recommended to remove the temporary maxima install
directory (c:/maxima above) before testing the installation.

12) Test the installed package (see the following part:)



Testing the installation package:
=================================

After building it, you can (and should) test the new Maxima installation package.
Install it on Windows and check that the installation (and later the deinstallation)
works properly. To test Maxima, try the following:

 o Run the maxima testsuite: run_testsuite();
 o Try compiling a function.  This has been a problem in the past
    f(x):=x+2;
    compile(f);
    f(2);
 o Test the graphics systems in both xmaxima and wxmaxima
    plot2d(sin(x),[x,0,10]);
    plot2d(sin(x),[x,0,10],[plot_format,xmaxima]);
    plot3d(x*y,[x,-1,1],[y,-1,1]);
    plotdf([-y,x],[trajectory_at,5,0]);
    load(draw)$
    draw3d(xu_grid = 30, yv_grid = 60, surface_hide = true,
          parametric_surface(cos(phi) * sin(theta),
                       sin(phi) * sin(theta),
                       cos(theta),
                       theta, 0, %pi, phi, 0, 2 * %pi))$
 o Check that plotting to Postscript works
    plot2d(sin(x),[x,0,10],[ps_file,"ps_test.ps"]);
 o Try out the on-line help: describe(sin);
 o Try out, if external packages (e.g. lapack) work:
   load(lapack);
   fpprintprec : 6;
   M : matrix ([9.5, 1.75], [3.25, 10.45]);
   dgeev (M);

   should return the eigenvalues of M (and false, false since we did
   not compute eigenvectors: [[7.54331, 12.4067], false, false]

 o Check that the windows help files work from the Start menu 
   and from within xmaxima and wxmaxima
 o Try if double-clicking on a .wxmx file opens it
 o The wxMaxima source comes with a file (test/testbench_simple.wxmx)
   that tries to trigger everything that has gone wrong in previous
   wxMaxima builds.  They include the commands that will test the
   graphics system in the next step.
   Open that file and then select "Cells/Evaluate all cells" in this
   file and check if the file is processed correctly.



Troubleshooting
===============


If compilation fails
--------------------

The Windows installer for gcl-based maxima requires gcc and as.  The gcc 
files required depend on the version of gcc used. If compilation fails
then some troubleshooting is required.

One way to do this is to save the .c file generated by gcl:
  f(x):=x+2$
  :lisp (setq compiler::*keep-gaz* t)
  compile(f);
then open a cmd window and run gcc from the command line. 


If plotting fails
-----------------

If plotting fails on a new platform (win64, arm or similar) it might
be that some of the tests for the operating system (
        (and sbcl win32)
or
        (string= *autoconf-windows* "true")
) might not detect the current flavour of the OS.