This document describes how to use the Standard ML bindings
for Sam Lantiga's SDL library. SDL stands
for Simple DirectMedia Layer and it is a library for
creating sound, fast graphics, getting mouse and keyboard
input etc. 'Stanard ML' is a typesafe higher order functional
programming language - i.e. very different from (and usually
much better than :) imperative object oriented languages,
such as 'C', 'C++', 'Java', 'Pascal' etc.
Compilers and operating systems
SDL runs on lots of operating systems. The SDL::ML
bindings are implemented for the compilers MLKit and
'MLTon'.
'MLTon' officially supports Linux, but
will possibly work with other Unices too.
I have succeeded (with help from Stephen T. Weeks)
in making it crosscompile SDL applications
from Linux to Windows, which is described in
Making MLTon crosscompile applications from Linux to Windows.
MLKit supports at least Linux and HPUX, but should also
work on other Unices. I have also succeeded in
Making MLKit crosscompile applications from Linux to Windows.
In my experience, MLKit will give memory leaks when writing applications like games, which typically have an eventloop with lots of long lived state information. 'MLTon' seems more suitable for this. However 'MLTon' cannot verify that your ML programs are correct, so you will problably need MLKit for this :)
For compiling MLKit you will need SML/NJ version 110.0.3 or SML/NJ version 110.0.6, and I recommend the last one. However it seems that you will need working version 110.9.1 of the SML/NJ compiler (or later) to compile a utility called cmcat for 'MLTon', unless you change a little in the sourcecode for cmcat so that it will compile with SML/NJ version 110.0.6. SML/NJ working version 110.9.1 cannot compile MLKit though.
Since both MLKit and 'MLTon' are generating C-code (at least for Linux and Windows) you need the gcc compiler too, both in a native and a crosscompiler version if you're crosscompiling for Windows.
This all amounts to at least 7 compilers! However you problably don't need a crosscompiling MLKit if you're writing games. All I'm saying is that, writing games with SDL in ML is only recommended if you have good patience and preferably experience with both SDL, 'C', ML, games programming and functional programming in general. On the other hand, it's very interesting, different and cool to write games in ML :)
Lastly, none of the Windows ports, nor the SDL bindings,
are complete and I will not be held responsible for any
problems it may cause you. It's just complete enough that I have been
able to write a commercial game with it. Hopefully I will
be allowed to store a version of it on this homepage later.
Downloading
When you've got the compilers that you think you'll need in place :)
you are ready to download SDL::ML and unpack it with the command
'tar -xvf SDLML_19991115.tar'.
Using SDL::ML with MLTon
First you must compile the .o file with the C-functions made ready to be called from 'MLTon', so go to 'srcC/MLTon/SDLFuncs/'. If you want to use SDL and 'MLTon' natively, you just type 'make'. If you're crosscompiling from Linux to Windows you should first activate your gcc crosscompiler by setting the appropriate paths. Then type 'make target=win32'. There will be warnings when the file 'SDLDummy' is linked, but you don't need 'SDLDummy' for anything - it is only a quick hack to force the makefile to compile the 'SDLFuncs.o' file.
Now go to 'srcSML/MLTon/SDLFuncs/'. Copy either 'Makefile_Win32' or 'Makefile_Linux' to Makefile, according to which version you need. An example 'Source.sml' file has been prepared and you should be able to compile it by typing 'make'. The makefile links with the necessary libraries for the platform. 'SDLFuncs.sml' is the ML API with the SDL bindings. The example is the file 'TestSDLFuncs.sml'. These 2 files where just put together to form 'Source.sml' for this example.
In general you will problably want to use MLTon's utility called cmcat to concatenate an SML/NJ CM project into one file (see the note in Making MLTon crosscompile applications from Linux to Windows). You won't be able to add SDLFuncs.sml to the project though, since cmcat does not like the function name '_prim', which is used in 'SDLFuncs.sml'. So paste in 'SDLFuncs.sml' manually at the top of your assembled source file.
In 'srcC/MLTon/Misc/' you will find the Windows crosscompilation
Makefile I'm using to compile my own project with. It might be useful.
Using SDL::ML with MLKit
First you must compile the .o file with the C-functions made ready to be called from MLKit, so go to 'srcC/MLKit/SDLFuncs/'. If you want to use SDL and MLKit natively, you just type 'make'. If you're crosscompiling from Linux to Windows you should first activate your gcc crosscompiler by setting the appropriate paths. Then type 'make target=win32'. There will be warnings when the file 'SDLDummy' is linked, but you don't need 'SDLDummy' for anything - it is only a quick hack to force the makefile to compile the 'SDLFuncs.o' file.
Now go to 'srcSML/MLTon/SDLFuncs/'. An example 'TestSDLFuncs.sml' file has been prepared and you should be able to compile it. Whenever compiling anything, you will have to start MLKit and have the file 'SDLFuncs.o' in the same directory where you start MLKit from. 'SDLFuncs.sml' is the ML API with the SDL bindings. To compile an SDL application you need to make the MLKit link with the appropriate libraries. In the MLKit menu you just go to Control and choose: link with library. If you're crosscompiling SDL applications you should type "-lmingw32 -mwindows -L/usr/local/lib -lSDL" and if you're compiling natively you should type "-lpthread -L/usr/local/lib -Wl,-rpath,/usr/local/lib -lSDL -ldl -lm". This assumes that you have SDL under '/usr/local/lib'.
In 'srcSML/MLKit/SDLFuncs/' you will also find the
projectfile 'sdlapi.pm' that I'm using to compile my own project with.
It might be useful.