Compiling Octave with MSVC

Starting with Octave 2.9.9, Octave source tree contains support for
MSVC (Microsoft C/C++ compiler).  This file explains how to
successfully compile Octave under such a system.


1. Requirements
===============

Depending whether you are compiling Octave from a release package or
from CVS source tree, various additional tools are required.

1.1 Shell
---------

The compilation process requires a working UNIX-like shell under
Windows.  Such shell is provided either by Cygwin or MSYS (MinGW).
The choice of the actual shell will have an impact on the rest of the
procedure.  Altough both shell can be used, the procedure has been
mainly tested under the MSYS shell.

1.1.1 Cygwin shell

The use of the Cygwin shell has the advantage of installation
simplicity, as all required packages can be easily installed through
the setup program.  However it presents some annoying compile-time
problems.  The Cygwin shell can be installed via the setup program
http://www.cygwin.com/setup.exe.  You should at least select the
following packages

  bash  grep  sed  make

If you are building the CVS sources of Octave, you will also need

  gawk  bison  flex  autoconf  tetex  texinfo  ghostscript

When building from CVS, you need also gperf.  However, the version
available under Cygwin is too old, so you should grab a more recent
one.  You can either build gperf from the sources found at
ftp://ftp.gnu.org or use the package from the GunWin32 project
(http://gnuwin32.sourceforge.net).  Either way, get the gperf package,
install it and make sure the executable is in your PATH under the
Cygwin shell.

1.1.2 MSYS shell

The use of the MSYS shell requires more manual installation, but
currently results in fewer compile-time problem.  Download and install
the following packages from the MinGW download page
(http://www.mingw.org):

  MSYS-1.0.10.exe
  msysDTK-1.0.1.exe

If you are building the CVS sources of Octave, you will also need

  msys-autoconf-2.59.tar.bz2

from the MinGW site.

  NOTE: the autoconf version included in msysDTK is too old (2.56).
        Grab the newer one and simply uncompress it in the root
        directory of the MSYS installation directory.

If you are building from CVS, you will need the following
additional tools that are not part of the MSYS packages

  bison  flex  gperf

You can find these packages as part of the GnuWin32 project
(http://gnuwin32.sourceforge.net) or you can build them from sources
found at ftp://ftp.gnu.org.  Download and install these packages and
make sure the executables are in your PATH under the MSYS shell.

Building the documentation from CVS also requires additional tools,
mainly TeX, texinfo and ghostscript.  MiKTeX (http://www.miktex.org)
provides a user-friendly TeX implementation under Windows, with an
easy-to-use installer.  Download and install MiKTeX if you're building
from CVS, and make sure the executables (located in
<MiKTeX_install>\Main\miktex\bin) are in your PATH under the MSYS shell.

MiKTeX also provides texinfo.  However, the msysDTK package provides
an out-dated version that cannot be used to build Octave
documentation.  So you should make sure that you're using the MiKTeX
implementation, by either playing with your PATH variable or renaming
the makeinfo.exe, texi2dvi and texi2pdf files located in the directory
<MSYS_install>\bin.

Ghostscript is available from http://www.cs.wisc.edu/~ghost/.
Download and install the package gsxxxw32.exe, where xxx stands for
the actual release or ghostscript (as of writing this documentation,
version is 8.54; hence the package is named gs854w32.exe).  Again,
make sure the gswin32.exe executable is in your PATH under the MSYS
shell.

1.2 Gnuplot
-----------

Octave relies on gnuplot for plotting.  It is not necessary to install
gnuplot just to build the Octave executable, but it is needed to
create some figures for the documentation if you are building the CVS
sources of Octave.

A Windows version of Gnuplot can be found at http://www.gnuplot.info.
Download and install it, and make sure the pgnuplot.exe executable is
in your PATH under the shell.

1.3 MSVC compiler
-----------------

You'll need a recent MSVC compiler.  This compiler is available for
free (as in beer) from Microsoft MSDN web site.  Octave has been
successfully compiled using version 8 of the compiler (AKA Visual
Studio 2005).  To start a command prompt with the correct compilation
environment, use the corresponding menu entry in your start menu.

If you're using the free version of Visual Studio (Express edition),
you'll need to install the Platform SDK package, also available from
MSDN.  In that case, you'll also need to run the "SetEnv.cmd" script
found in the SDK installation directory for the required additional
setup.

1.4 Unix-to-MSVC compilation scripts
------------------------------------

These scripts provide a UNIX-like compilation interface, based on the
Microsoft compilation tools.  The package is available from the Octave
web site.  Download and install the package, and make sure the scripts
are in your PATH under the shell.

As those scripts calls the Microsoft compilation tools, those tools
should also be in your PATH.  I've found that the easiest way to get a
correct environment is to start the shell from the command prompt that
is already configured for MSVC.

Hence the following steps:

  * start command prompt from Visual Studio menu entry

  * run "SetEnv.cmd" if required

  * additional setup (like adding Gnuplot, GnuWin32 bin
    directory... to the PATH)

  * start the shell:

    - MSYS:    start <MSYS_install>\bin\rxvt.exe -e /bin/sh --login -i
    - Cygwin:  start <Cygwin_install>\cygwin.bat

1.5 Glob library
----------------

Octave also requires a filename globbing library.  This library is
typically part of the C library on UNIX systems, but is not part of
the Windows or MSVC run-time libraries.  You can find a glob package
on the Octave website.  This package provides the missing features and
is intended to be compiled in a fully setup shell with the
Unix-to-MSVC compilation scripts:

  * download and decompress the sources
  * run "./configure.vc" (you can edit it to change the installation dir)
  * run "make"
  * run "make install"

Then you'll have to tell MSVC where to find the headers and library
files by adjusting the INCLUDE and LIB environment variables.  This
can be done before starting the shell, in the "additional setup" step
(see above).

1.6 Readline library
--------------------

While not mandatory to compile Octave, the readline library is very
useful to make Octave really usable.  A patched version of the
readline library can be found in the Octave website.  This patched
version is intended to be compiled from the shell using the
Unix-to-MSVC compilation scripts:

 * download and decompress the sources (and apply the patch, if required)
 * follow the instructions in the file README.msvc

As for the glob library, adapt the INCLUDE and LIB environment
variables.  Note that as Octave will be linked to the readline DLL,
you should also add the path of readline.dll to your PATH variable.

1.7 F2C
-------

As there exist no free MSVC-like fortran compiler, the compilation
process makes use of the f2c utility and the libf2c library.  Those
components can be downloaded from http://www.netlib.org/f2c/msdos/ and
http://www.netlib.org/f2c/libf2c.zip.

To compile libf2c, use makefile.vc and NMAKE.EXE.  To be usable within
Octave, the following modifications needs to be done:
  1) edit makefile.vc and add "-MD" as compilation flag (to
     the CFLAGS variable).
  2) edit fio.h and comment the declaration of isatty (around line 112).
     This means replacing the line:

		extern int isatty(int);

     with

		/* extern int isatty(int); */

After compilation, install f2c.h and vcf2c.lib at locations where they
can be found by the MSVC tools (adjust the INCLUDE and LIB variables).
Note that you must rename vcf2c.lib into f2c.lib so that Octave's
configure script will find it.


2. Compilation
==============

Copy the following lines into a shell script and execute it (note that
you can use whatever you want as installation directory):

--- BEGIN (cut me)
#!/bin/sh
if ! grep "__declspec(noreturn dllimport)" configure 2>&1 > /dev/null; then
  echo "Pre-processing configure script..."
  sed -e "s/'extern \"C\" void exit (int);'/'extern \"C\" __declspec(noreturn dllimport) void exit (int);' 'extern \"C\" void exit (int);'/g" configure \
    > configure.tmp
  mv configure.tmp configure
fi

CC=cc-msvc CXX=cc-msvc NM="dumpbin -symbols" AR=ar-msvc RANLIB=ranlib-msvc \
  ./configure --build=i686-pc-msdosmsvc --prefix=/usr/local/octave-vc8-debug --with-f2c
--- END (cut me)

Then run the usual:

  make
  make install

2.1 MSYS
--------

When building from the MSYS shell and CVS, everything should run fine
until building the doc.  At some point, TeX might ask you for the
location of the file conf.texi.  If this happens, simply type
"../conf.texi" and the process should continue.

2.2 Cygwin
----------

Building from the Cygwin shell and CVS produces more compile-time
errors when generating the documentation.  Here are some fixes that
should work around most problems:

  * edit "run-octave" and add the 2 lines right after the definition of
    LOADPATH and IMAGEPATH:

      LOADPATH=`cygpath -d -p $LOADPATH`
      IMAGEPATH=`cygpath -d $IMAGEPATH`

  * if texi2dvi fails with the error "Fatal error: I'm stymied", defines TEX
    variable to "tex" as in: "TEX=tex make"

  * if pdftex fails in doc/refcard with the same error as above, edit
  the Makefile and replace "pdftex" calls with "pdfetex"


3. Installation
===============

The compiled Octave is relocatable.   This means that whetever
installation dir you chose at configure time, you can move the whole
installation directory to another location without any problem.   Octave
should still run OK.


4. Notes
========

This procedure has been successfully tested under Windows XP with
Visual Studio 2005 Express edition, Platform SDK for Windows Server
2003 R2, patched readline version 5.2, APFL ghostscript 8.54, Gnuplot
4.0, MSYS-1.0.10, msysDTK-1.0.1, MiKTeX-2.4.  Depending on your
configuration, it may or may not work for you.


Please send questions, comments or suggestions to

Michael Goffioul
michael dot goffioul at swing dot be

Thu Nov  2 11:30:50 2006