transl: do not assume a catch's mode based on the last body form
[maxima.git] / INSTALL.win32
blobca2a2c9e559ac53882a2e8782434e7a838343f66
1 Executive Summary
2 =================
4 Maxima can now be built under Windows without recourse to any
5 Unix-like utilities. To do so, follow the purely lisp-based build
6 procedure in INSTALL.lisp.
8 Maxima can be simply compiled and installed under MSYS or Cygwin by
9 following the GNU Autotools instructions in INSTALL. With a few more
10 steps, Maxima will create a windows installer executable.  The
11 instructions for doing so are contained in this file. Note, however,
12 that this process is not as polished as the Unix-like install process.
14 In order to create the Maxima Windows installer from the maxima tarball 
15 distribution, I do the following in a MSYS window:
16 ----------------------------------------------------
17 ./configure --prefix=c:/maxima \
18     --enable-chm \
19     --enable-xmaxima-exe \
20     --with-hhc=<path-to-hhc> \
21     --enable-lang-es --enable-lang-pt --enable-lang-pt_BR
22 make
23 make install
24 make iss
25 ----------------------------------------------------
26 Then run Inno Setup on the generated maxima.iss file. That is all it
27 takes.
30 External Requirements
31 =====================
33 1) MSYS+MinGW, including mktemp
34 2) msysDTK
35 3) GCL
36 4) Tcl/Tk (8.5 or later recommended)
37 5) Starkit, TclKit and img.kit
38 6) Vtk
39 7) InnoSetup
40 8) gnuplot
41 9) wxMaxima
42 10) Microsoft HTML Help Workshop
43 11) Perl 5.8 (ActivePerl)
44 12) Python 
46 Detailed Instructions
47 =====================
49 The instructions below apply to the maxima release tarball. In order
50 to build from the git repository, git, autoconf and automake are also
51 required. Follow the directions in INSTALL.git before proceeding.
53 1) Get a working msys+mingw installation from www.mingw.org. 
55 Option A - gcc-3.3.1 based system
57 From 2006 until 2012, it was essential to install the versions of gcc and
58 binutils listed here to obtain a working gcl.  The files are available
59 from <https://sourceforge.net/projects/mingw/files/>:
60    a) Get and install MinGW-3.1.0-1.exe
61    b) Install MSYS-1.0.10.exe 
62       The installer should magically find your mingw installation
63       and add it to your path.
64    c) Install tcltk-8.4.1-1.exe
65       Install it into directory where MSYS/MinGW can find it,
66       for example mingw/bin directory.
67    d) Install gcc-3.3.1
68    e) Install binutils-2.14.90 from 
69       ftp://ftp.sf.net/m/mi/mingw/binutils-2.14.90-20030807-1.tar.gz
70    f) Install msysDTK-1.0.1.exe
71       It provides Perl and autotools (autoconf/automake).
72       msysDTK-1.0.1 comes with Perl version 5.6.  This is now too old.
73       Since Maxima 5.11 we require version 5.8. 
75       or install
77       - automake msys-autoconf-2.59.tar.bz2
78       - autoconf msys-automake-1.8.2.tar.bz2
79       - libtool msys-libtool-1.5.tar.bz2
80    g) Download the MinGW implementation of mktemp from: 
81       http://downloads.sourceforge.net/mingw/mktemp-1.5-MSYS.tar.bz2 (4 Kb)
82       Install by (cd /; tar xjf /path/to/mktemp-1.5-MSYS.tar.bz2)
84 NOTE: gcc 3.3.3 and gcc 3.4.0 do NOT work; likewise binutils 2.13.90
85 and 2.15.90, but 2.17.50-20060824 is OK.
87 This is output of msysinfo command for MSYS system with
88 all required components:
89 -----------------------------------------------------------------
90 MSYS 1.0.10(0.46/3/2) 2004-03-15 07:17 i686 unknown; targ=MINGW32
91 GNU bash, version 2.04.0(1)-release (i686-pc-msys); ENV=.profile
92 GNU Make version 3.79.1,Built for i686-pc-msys; MAKE_MODE=unix
93 gcc.exe (GCC) 3.3.1 (mingw special 20030804-1); targ=MINGW32
94 GNU ld version 2.14.90 20040120
95    789320 Tue Mar 16 10:32:49 2004 /bin/msys-1.0.dll
96     52064 Thu Jan 02 05:05:27 2003 /bin/msysltdl-3.dll
97    135680 Tue Mar 16 10:32:48 2004 /bin/make.exe
98     84992 Thu Aug 07 23:29:00 2003 /mingw/bin/gcc.exe
99    617472 Tue Jan 20 21:57:52 2004 /mingw/bin/ld.exe
100 -----------------------------------------------------------------
102 Option B - gcc-4.6.2 based system
104 From early 2012 it has been possible to build maxima using current 
105 msys, mingw and gcc-4.6.
107 a) Download mingw installer mingw-get-inst from http://www.mingw.org/
108 b) Run the installer to install mingw and msys
109 c) Use the installed mingw-get to add the build dependencies, including
110    - mingw-gcc
111    - mingw-binutils
112    - mingw-make
113    - mingw32-autotools
115 maxima-5.27.0 was successfully built using
116   MSYS 1.0.17(0.48/3/2) 
117   GNU bash, version 3.1.17
118   GNU Make 3.81
119   gcc.exe (GCC) 4.6.2
120   GNU ld (GNU Binutils) 2.22
122 2) Get a working GCL 
124 Get the GCL 2.6.8pre from CVS.  
125 See  <http://savannah.gnu.org/projects/gcl/>. 
127 Then compile and install under mingw/msys with
129 ./configure --enable-ansi
130 make
131 make install
133 Check that gcl works by typing gcl at MSYS command line
134 -----------------------------------------------------------------------
135 $ gcl
136 GCL (GNU Common Lisp)  2.6.8 ANSI    Nov 11 2006 23:08:49
137 Source License: LGPL(gcl,gmp), GPL(unexec,bfd,xgcl)
138 Binary License:  GPL due to GPL'ed components: (UNEXEC)
139 Modifications of this banner must retain notice of a compatible license
140 Dedicated to the memory of W. Schelter
142 Use (help) to get some basic information on how to use GCL.
143 Temporary directory for compiler files set to C:/DOCUME~1/user/LOCALS~1/Temp/
145 >(quit)
146 -----------------------------------------------------------------------
148 3) Download tclkitsh-8.6.3-win32-ix86.exe and
149 tclkit-8.6.3-win32-ix86.exe from
150 <http://tclkits.rkeene.org/fossil/wiki?name=Downloads> and put them in
151 c:/programs/star.
154 4) Get and install Inno Setup from
155 <http://www.jrsoftware.org/isinfo.php>. 
157 5) Download the gnuplot windows binary from <http://gnuplot.sourceforge.net>.
158 It is recommended to use version 4.6 patchlevel 3 or more recent (If you
159 do have to use an older version, read the Maxima documentation for variable
160 gnuplot_view_args).  
161 Install gnuplot in your MSYS user home directory in ~/programs/gnuplot 
163 6) Compile wxMaxima for windows from <https://wxmaxima-developers.github.io/wxmaxima/>.
164 Use wxMaxima 0.6.5 with Maxima 5.9.3 or earlier, 
165 wxMaxima 0.7.0 with Maxima 5.10.0,
166 and wxMaxima 0.7.1 with Maxima 5.11.0.
168 Install it to default location, say C:\Program Files\wxMaxima. 
169 Then copy contents of wxMaxima directory excluding \uninst subdirectory
170 to your MSYS user home directory ~/programs/wxMaxima
172 NOTE: Location of Starkit/TclKit, gnuplot and wxMaxima is controlled
173 by the override-able variables and their defaults are:
175 TCLKITSH = tclkitsh.exe
176 TCLKITDIR = ../../../../programs/star
177 SDXDIR = $(TCLKITDIR)
178 GCCPREFIX=/mingw
179 GNUPLOTDIR = ../../../../programs/gnuplot
180 WXMAXIMADIR = ../../../../programs/wxMaxima
182 To see how they are used, look in interfaces/xmaxima/win32/Makefile.in
183 and Makefile.am in the top level maxima directory.  You may change
184 their values according to your preferences.
186 7) Install Microsoft HTML Help Workshop from
187 <http://www.microsoft.com/en-us/download/details.aspx?id=21138>.
189 Make sure that HHW directory is within PATH (edit PATH environment
190 variable with either Windows or MSYS approach), so the HTML Help Workshop
191 compiler command "hhc.exe" is available at the MSYS command prompt.
193 For reference, to change PATH within MSYS only, edit the file
194 c:\msys\1.0\etc\profile and add the following line after the initial
195 setting of PATH:
196     export PATH="/c/gcl/bin:$PATH"
198 8) Install Perl 5.8.  ActivePerl binaries provided by
199     http://www.activestate.com work.  Again add the perl bin
200     directory to PATH.  Alternatively use a wrapper script like
202     $ cat /usr/local/bin/perl
203     #!/bin/sh
204     exec /c/perl/bin/perl $@
206 9) Install Python 2.6. ActivePython binaries provided by
207     http://www.activestate.com work.
209 10) Following components
210     a) tcltk (e.g. wish84 command), 
211     b) gcl (gcl command),
212     c) HTML Help Workshop compiler (hhc command)
213     d) perl
214     e) python
215 should also be available at the MSYS command prompt.
217 If this is not the case, edit your PATH variable or add wrapper scripts.
219 11) You should now be ready to compile and install maxima. 
220 Configure maxima so that it will install in some sort of temporary
221 directory. The directory does not need to exist ahead of time.
223 ./configure --prefix="c:/maxima" \
224   --enable-lang-es --enable-lang-pt --enable-lang-pt_BR
225 make
226 make check
227 make install
228 make iss
230 The "check" should pass all tests except those listed as known
231 failures.
233 11) Once "make iss" is complete, run Inno Setup on the maxima.iss
234 file. It is recommended to remove the temporary maxima install
235 directory (c:/maxima above) before testing the installation.
237 12) Test the installed package (see the following part:)
241 Testing the installation package:
242 =================================
244 After building it, you can (and should) test the new Maxima installation package.
245 Install it on Windows and check that the installation (and later the deinstallation)
246 works properly. To test Maxima, try the following:
248  o Run the maxima testsuite: run_testsuite();
249  o Try compiling a function.  This has been a problem in the past
250     f(x):=x+2;
251     compile(f);
252     f(2);
253  o Test the graphics systems in both xmaxima and wxmaxima
254     plot2d(sin(x),[x,0,10]);
255     plot2d(sin(x),[x,0,10],[plot_format,xmaxima]);
256     plot3d(x*y,[x,-1,1],[y,-1,1]);
257     plotdf([-y,x],[trajectory_at,5,0]);
258     load(draw)$
259     draw3d(xu_grid = 30, yv_grid = 60, surface_hide = true,
260           parametric_surface(cos(phi) * sin(theta),
261                        sin(phi) * sin(theta),
262                        cos(theta),
263                        theta, 0, %pi, phi, 0, 2 * %pi))$
264  o Check that plotting to Postscript works
265     plot2d(sin(x),[x,0,10],[ps_file,"ps_test.ps"]);
266  o Try out the on-line help: describe(sin);
267  o Try out, if external packages (e.g. lapack) work:
268    load(lapack);
269    fpprintprec : 6;
270    M : matrix ([9.5, 1.75], [3.25, 10.45]);
271    dgeev (M);
273    should return the eigenvalues of M (and false, false since we did
274    not compute eigenvectors: [[7.54331, 12.4067], false, false]
276  o Check that the windows help files work from the Start menu 
277    and from within xmaxima and wxmaxima
278  o Try if double-clicking on a .wxmx file opens it
279  o The wxMaxima source comes with a file (test/testbench_simple.wxmx)
280    that tries to trigger everything that has gone wrong in previous
281    wxMaxima builds.  They include the commands that will test the
282    graphics system in the next step.
283    Open that file and then select "Cells/Evaluate all cells" in this
284    file and check if the file is processed correctly.
288 Troubleshooting
289 ===============
292 If compilation fails
293 --------------------
295 The Windows installer for gcl-based maxima requires gcc and as.  The gcc 
296 files required depend on the version of gcc used. If compilation fails
297 then some troubleshooting is required.
299 One way to do this is to save the .c file generated by gcl:
300   f(x):=x+2$
301   :lisp (setq compiler::*keep-gaz* t)
302   compile(f);
303 then open a cmd window and run gcc from the command line. 
306 If plotting fails
307 -----------------
309 If plotting fails on a new platform (win64, arm or similar) it might
310 be that some of the tests for the operating system (
311         (and sbcl win32)
313         (string= *autoconf-windows* "true")
314 ) might not detect the current flavour of the OS.