Windows Installer

This article is about how to make the Windows installer; if you'd like just to use the installer, see Octave for Microsoft Windows.

GNU Octave is primarily developed on GNU/Linux and other POSIX compliant systems. There have been many efforts in the past to build ports of GNU Octave for Microsoft Windows. This page contains instructions about creating a Windows installer using mxe-octave (a fork of MXE). This means, the Microsoft Windows installer is cross-compiled using a GNU/Linux system.

Steps to create Windows Installer

General steps

1. Install all requirements of MXE Octave.
2. hg clone https://hg.octave.org/mxe-octave
3. cd mxe-octave
4. ./bootstrap
5. ./configure
6. make all nsis-installer

Step details

./configure

The current Windows installers are build in three "flavors": for common 64- and 32-bit systems ("w64" and "w32") and for 64-bit systems exceeding 32 GB of main memory to store large data structures ("w64-64").

"w64" (recommended)	"w64-64"	"w32"
./configure \ --enable-devel-tools \ --enable-binary-packages \ --with-ccache \ --enable-octave=<octave version> \ --enable-windows-64 \ --enable-64	./configure \ --enable-devel-tools \ --enable-binary-packages \ --with-ccache \ --enable-octave=<octave version> \ --enable-windows-64 \ --enable-64 \ --enable-fortran-int64	./configure \ --enable-devel-tools \ --enable-binary-packages \ --with-ccache \ --enable-octave=<octave version> \ --disable-windows-64

The individual options have the following meaning (see also ./configure --help):

• --enable-devel-tools: Include gdb and an MSYS shell in the binary.
  • If you seriously want to work with gdb, you need --disable-strip-dist-files as configure option to keep debug symbols in the installed binaries for debugging on Windows. Beware as the total Octave distribution will be > 2 GB, the max. size for an NSIS installer. Your only options are to make 7z-dist, zip-dist or tar-dist installers.
• --enable-binary-packages: Cross-compile binary modules in Octave Forge packages. This saves time when installing them once the installation runs on Microsoft Windows.
• --with-ccache: The usage of ccache may speed up repetitive compilation drastically.
• --enable-octave=<octave version>: Build a specific version of GNU Octave, which can be one of:
  • release use src/release-octave.mk, download and build the latest GNU Octave release.
  • stable or default uses src/stable-octave.mk or src/default-octave.mk, respectively. This builds a self-created distribution tarball from the "stable" or "default" development branch of GNU Octave. See below for details.
• --enable-windows-64: Build for 64-bit MS Windows.
• --enable-64: Let Octave use 64-bit integers for indexing.
• --enable-fortran-int64: Use 64-bit integers in Fortran code and especially in numerical library code.

make

• Use make all 7z-dist, make all tar-dist or make all zip-dist instead of make all nsis-installer if you want to build just an archive of the files to install on Windows instead of an installer wizard.
• By default, packages will be built one at a time, but you may use make JOBS=4 (choose a number other than 4 that is appropriate for your system) to build each package in parallel. You may also combine this with the -j option for Make to build more than one package at a time, but be careful as using make -j4 JOBS=4 can result in as many as 16 jobs running at once.
• Include gdb in the installer by running make gdb before making the nsis-installer target.

Build installers for Octave development versions

1. Build the "stable" or "default" Octave development branch on Linux (in separate source and build trees) including your favorite modifications and patches. Octave must be configured with Java support. How to do this depends on your Linux distribution, see Octave for GNU/Linux.
2. Verify that Octave runs fine in Linux (for example using make check and by trying to run your build ./run-octave --gui).
3. Create a distribution archive called "octave-<version>.tar.lz" in the top build directory with

make dist-lzip DIST_IGNORE_HG_STATE=1

1. Move or copy "octave-<version>.tar.lz" to the <mxe-octave build>/pkg folder (or create a symbolic link to it).
2. Follow the general steps and ensure the configuration with either of --enable-octave=stable or --enable-octave=default.
3. Move the final installer in <mxe-octave build>/dist/ to some Microsoft Windows machine (USB thumb drive, LAN copy, whatever) and install it "as usual". If you created an archive, using make all 7z-dist for example, you'll have to manually create the desktop and start menu shortcuts (for GNU Octave and the MSYS-shell).

For next builds, mxe-octave is already configured and all dependencies have been built so the only thing to do is having a new Octave version + installer built:

• move/copy the dist archive from step 2 into mxe-octave's pkg subdir
• in <mxe-octave build> root dir do:

touch src/default-octave.mk

(to be sure mxe-octave picks up the new Octave archive). If you've renamed the dist archive, be sure it matches with the package name in src/default-octave.mk.

Remarks

• If you have several mxe-octave build dirs (for e.g., stable and several development versions) it is handy to have a separate pkg subdir symlinked to from all mxe-octave build dirs. That will save a lot of downloading bandwidth.
• As of late Dec 2015, mxe-octave allows out-of-tree builds, which makes it a lot easier to build separate Octave versions with the same mxe-octave tree. (See http://hg.octave.org/mxe-octave/rev/0962acdde3be)
• To keep mxe-octave up-to-date, from time to time do:

hg -v pull
hg -v update

• However, do not keep mxe-octave build dirs for too long. I'd suggest to wipe a build dir after at most two or three months and start over with a fresh clone a la Step 1.
• In the mean time, regularly clean up <mxe-octave build>/log to save disk space. After a first successful build there's no more use for the log subdirs for each package, so you can wipe them all.

It can happen that you meet problems with Java. To build Octave with Java support built-in, mxe-octave needs:

• A Java JDK (Java Development Kit) on the host system. IOW, the javac (Java compiler) and jar (Java archiver) executables should be in the PATH.
• Java include files for windows (win32, even for w64 builds). They should reside in "<mxe-octave build dir>/usr/x86_64-w64-mingw32/include/java/win32". If not present, mxe-octave downloads them but this can occasionally go wrong. On a multi-boot system a solution (note: dirty hack warning!) is symlinking to the Windows include files on the Windows partition from the mxe-octave location.

Troubleshooting

• The error message displayed by make is simply the last 10 lines of the log file. This may truncate the actual error message.
• Sometimes running "make" a second time without changing anything will fix the problem. In particular, autotools rebuilds some files in the first make which may cause the second make to succeed.
• If it is building Octave that failed, the source will be left in <mxe-octave build>/tmp-default-octave and it is possible to run "configure && make" in that directory.
• The configuration will be for the target system, not your own. In particular, if you have not installed all of the packages that MXE-octave installs, then your configuration will be different. However, some configuration variables will differ even if you have the same packages, and some compiler features may be available on the host system that are not available in cross-compile mode.
• A possible causes for build failure is having files in your local source or build directory that are not listed in the module.mk files; these are not copied into the dist archive.
• (philip, confirmed by oheim) On my core i5 desktop system with a fast SSD, mxe-octave builds usually fails at libmng, suspectedly because of a race condition related to disk I/O. A way to get past this is by specifying "make nsis-installer JOBS=1", if required repeatedly (sometimes 5 or 6 times), interrupting the build in the next step/dependency once libmng has been built fine, and restarting with "make nsis-installer JOBS=<higher number>". As of Dec. 2015 it is only libmng that has this issue.

Trying out cross-built Octave on Linux through VirtualBox

Micosoft makes pre-built Windows 10 virtual disk images available for testing. While primarily meant for testing the MS-Edge browser, the license for these images does not limit the use of these images to just MS-Edge. So it is perfectly possible to also test Octave. There are several advantages:

• Rebooting from Linux to Windows isn't needed;
• The latest Windows 10 version is always available;
• Building the installer or zip/7z/<whatever> archives itself isn't needed. One can interrupt the build process after the entire installation of Octave has been made in the dist/octave subdirectory of mxe-octave, i.e., when the message "generating installer" (or "zip...") is shown, saving ~10-15 minutes.

Of course one an also install (or unpack) octave into the virtualized Windows 10.

Steps:

• Install Virtualbox
• Grab a copy of the Windows 10 image here: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
• Unpack and import the disk image into VirtualBox.
• In VirtualBox, select Settings | Shared folders and setup access from Windows 10 to the Linux subdir where you but mxe-octave. It is advised to make it read-only.

Then:

• Either install (or unpack) Octave into Windows 10, or
• Create a shortcut to octave.vbs in the dist/octave subdir on Linux.

Hints:

• I adapted mxe-octave/binary-dist-rules.mk to have a consistent name for the dist/octave subdir (i.e., without time/date/bitwidth suffixes) so that in Windows the shortcut doesn't need adaptation after each cross-build action. Maybe it is better if binary-dist-rules.mk has a rule to create a symlink "dist/octave/" pointing to the latest cross-build.
• The image expires after 90 days. But if you make a VirtualBox snapshot it will last longer, and you don't need to uninstall Octave each time before installing a new build.