Compiling the Source Code

Portability

Theoretically the code should compile on any platform, on any compiler, and give the same results. In fact, it is very difficult to write truly portable code that does mathematical computation: different compilers often seem to have different versions of the fp.h and math.h headers, and in particular it is difficult to guarantee that two different compilers will treat NaNs and Infs in the same (IEEE standard) manner at runtime: on this and on many other annoyingly delicate points, the functionality of the psignifit engine relies.

In order to find out whether the build has been successful, run with self-test by typing psignifit -t at the shell or Matlab command-line. This does two things: tests the IEEE-compatibility of your binary's floating-point behaviour, and fits a function to an example data set in order to uncover any bugs that might be making the source code non-portable to your platform. If the output does not end with the word *** success! ***, read it through carefully to see what is wrong.

As of version 2.5.6, the code compiles and runs correctly on the following platforms (although the engine has only been extensively tested under MacOS Classic):

MacOS Classic (versions 7.x -> 9.x) on PowerPCs

Standalone console applications and mex-files can be built using Metrowerks CodeWarrior (I have tried most releases from the old version 10 through to Pro 5, the only difficulty being the bugged MSL C library released in the old version 11). The binary runs correctly on the PowerPC architecture (including G3 and G4 machines) but not on old 680x0 machines (not that anyone should really be attempting to do computationally-intensive simulations on a 68k Mac these days).

MacOS X (Darwin command-line) on G3 and G4
FreeBSD on Intel

I have produced working command-line executables using the Gnu compiler (on OS X, this comes as part of the Developer Tools installation, but is given the name cc instead of gcc). The -lm switch is required. At the time of writing, mex-files are not an issue, as TheMathWorks have yet to release Matlab for OS X. Under FreeBSD, gcc version 2.95.3 seems to do the trick.

Digital Unix on the DEC Alpha

The cc compiler (version 5.6-079) under Digital UNIX will produce a command-line executable. The -ieee and -lm switches are required. Sadly I can't seem to make our Digital build of gcc (version 2.7.2.2) behave in the IEEE standard manner, so I have failed to compile a working version with the Gnu compiler.

Linux on Intel

The Gnu compiler (version 2.95.4) does the job of creating both command-line executables and mex-files. For the former, the -lm switch is required.

Windows

Flushed with success and the ease of porting from MacOS (where psignifit started life) to the UNIX world, I tackled the Wintel platform only to find, surprise surprise, that nothing worked. Various versions of the Borland, Microsoft and Lcc compilers either had incompatible definitions in fp.h and/or math.h, omitted unistd.h, or failed to treat Infs and NaNs sensibly at runtime.

Therefore, the only compiler I intend to support under Windows is gcc - not least because it is available for free. It can be obtained as part of the POSIX emulator package Cygwin, or as a set of DOS commands in either MinGW or DJGPP. Any of these can be used to create command-line executables (with DJGPP I have even managed a successful build on the old 16-bit DOS). Cygwin has the advantage of making the command-line executable easier to use, because it actually provides a proper command line, in the form of bash or tcsh. Mex-files can also be made relatively easily with Cygwin, using the gnumex package. (Cygwin gcc version: 2.95.3-5)

Making a standalone executable

Compiling the standalone executable is straightforward: simply compile and link together all the .c files in the distribution. For example, the following suffices under Cygwin:

Other platforms may require additional switches, as mentioned above. The primitive Makefile supplied in the source distribution currently works with Cygwin's version of Gnu make. Other platforms may have varying degrees of success with it, and may need to change the CC, CCFLAGS and LDFLAGS variables (it doesn't seem worthwhile writing a configure script for such a simple build).

Making a Matlab mex-file

The simplest way to make mex-files, if not necessarily the most efficient way, is to use the mex function from the Matlab command prompt. The function makepsig.m in the psignifit toolbox is a wrapper that calls mex in order to make the psignifit engine automatically. It assumes that the source directory is to be found inside the toolbox directory, so if this is not already the case, you need to download the source distribution and expand the psig-src directory inside the psignifit directory before calling makepsig. You can pass additional mex switches such as -g or -v into makepsig, the -V4 switch (or -V5, under Matlab R13 and later) being assumed already.

Under Linux, Matlab should be set up to use gcc for making mex files, and there should be no problem. Under Windows or MacOS, a mexopts.bat file appropriate for your compiler needs to be set up before you can use mex or makepsig. On the Mac, this can be done by typing mex -setup. This seems to work fine with the old CodeWarrior version 10, except that instruction scheduling (in the "PPC processor" project setting panel) is set for 601 processors for some reason, which might slow things down slightly. With CodeWarrior Pro, Matlab 5.x seems to miss out a certain amount of necessary housekeeping - you might want to keep the automatically generated CodeWarrior project file, make the following changes, and then make the mex-file directly from that:

• correct the instruction scheduling setting, as above;
• check "map newlines to CR" in "C/C++ Language" project settings panel, otherwise any text output from the mex file will look very strange;
• remove the dummy file <replace me.c> if it hasn't been removed automatically;
• remove cpp init file from project segment "MATLAB";
• remove cpp entry point from "Initialization" in the "PPC Linker" project settings panel.
  

On Windows, mex -setup might work in future, but at the time of writing, Matlab (release 12.1) does not offer settings for Cygwin or MinGW. For this, the easiest thing to do is to download Matthew Brett's tool gnumex. Unpack the gnumex archive and add the resulting directory to your path using pathtool. Then call gnumex and specify options:

• "Cygwin-mingw linking" if using Cygwin, "Mingw linking" if using MinGW
• "Mex dll"
• "C / C++"
• "Safe" or "Quick" according to your preference
• Opts bat file to create: save mexopts.bat in your preferences directory. The preferences directory can be ascertained by typing prefdir at the Matlab prompt, and it might be something like:
  C:\Documents and Settings\xyz\Application Data\MathWorks\MATLAB\R12\
  where xyz is your username.
  

Then click "Make Opts". Note also that, if you are going to use C++ in conjunction with the Cygwin-mingw linking method (which corresponds to the -mno-cygwin switch to gcc) there are certain headers and libraries that need to be added to the Cygwin setup: see Nicolay Giraldo's page. For the psignifit engine, this is not an issue unless you want to extend it using your own C++ code, because the 2.5.6 source distribution uses only C.

Please mail me at this address if you have any further tips on building mex-files on the various platforms. In particular, I would be very interested to hear if anyone has successfully got the Cygwin version of gdb to work with mex-files.