Whenever I refer to directories, file names or commands issued on the
computer they will be written in
mono-space and verbatim.
Write software that automatically generates Common Lisp (CL) bindings for Ogre.
Ogre is a 3D graphics library written in C++. This means that we'll have to generate code for CFFI (my chosen FFI) in CL and we'll have to generate C wrapper code for Ogre's C++ classes and methods since talking directly to C++ is riddled with problems (which will not be further discussed in this document).
Both the generated C++ code as well as the CL code should be human readable and produce as little warnings as possible when compiling! (When having to choose between the generated code being readable and the code of the bindings generator being readable I have given the former priority. I'm not so sure whether it's a good choice but time will tell...)
The bindings should be a usable subset of Ogre's API, enough to create a game. Due to various reasons (time, man power, differences between C++ and CL) it is probably not possible to ever automatically generate complete bindings to the Ogre API.
At the time of this writing I am not anymore working exclusively on Okra. I do use Okra in my private projects and through that it will slowly grow.
What you need and should know to get the examples running.
The start-up scripts (the
*.bat files) expect to be run from
At the time of this writing (20091225) in the Debian testing
distribution there are Ogre packages. Don't forget to turn off
CMakeLists.txt if you won't be using it.
To use Ogre you'll need to install the following packages:
To use OIS you'll need these packages:
For MyGUI check out: http://mygui.info/ or http://ogre3d.org/addonforums/viewforum.php?f=17
Check Compiling libokra yourself to for the rest of the instructions.
All examples expect Ogre to be installed so download the source from: http://www.ogre3d.org/download/source (you'll need "OGRE 1.6.x Source for Linux / OSX").
Configure, compile and install in
/usr/local. Ogre has some
dependencies which need to be installed first. Also, see here for
more information on the whole process:
The Linux start-up scripts are written and tested using SBCL
(1.0.25.debian at the time of writing) and expect to find
sbcl in the
They expect to find the necessary Ogre libraries in
/usr/local/lib/OGRE and all others in the
lib directory of the Okra
All these options are set in the
*.sh files and can be changed there.
All examples depend on the Ogre SDK to be installed so download it from: http://www.ogre3d.org/download/sdk (you'll need "OGRE 1.6.x SDK for Code::Blocks + MinGW C++ Toolbox").
Copy the following libraries from
<ogre-sdk>/bin/Release to the Okra
The Windows start-up scripts are written and tested using Clozure CL
and expect to find
wx86cl in the path.
All libraries are expected to be found in the
lib directory of the
All these settings are in the
*.bat files and can be changed there.
If the libokra library that comes with the Okra distribution doesn't work you'll need to compile it yourself. You'll need CMake for that: http://www.cmake.org/cmake/resources/software.html
If you have installed CMake on Linux you should issue:
cmake -G "Unix
If you're on Windows you should read the Windows (MinGW) chapter.
Start with the simplest example first:
If that works try the
physics-and-input example. This example depends
on both Buclet and clois-lane which you can find at:
Make sure both are installed correctly and if you're on Windows copy
over the DLLs from both the Buclet and clois-lane
lib directories to
lib directory. If you're on Linux copy over the
libclois-lane.so file from the clois-lane
lib directory to Okra's
If you don't want to copy over library files for the above examples you'll need to make sure the OS can find them. (By adapting the example start-up scripts for example.)
CEGUI support has been deprecated in favour of MyGUI. The code has
been moved to the
1.6.x-cegui branch in Git.
MyGUI v3.0.0+ is supported. This should actually be move to its own project but it is in Okra for now.
There are a couple of things to keep in mind when generating an executable using Okra from your CL implementation.
On all the implementations I have tested the callbacks from C to CL
had to be reloaded. The (unexported)
take care of this.
For some CL implementations you need make sure the foreign libraries are reloaded. Of the implementations I have tested this needed to be done for CCL on Windows. This is done using an init script which is supplied when saving the image.
In the libraries (unexported)
load-foreign-libraries functions are
provided for this. (And also
load-libcegui in the
package, I have to clean that up.)
My modus operandi when working on the bindings generator is from
within Emacs. I start up Slime with
M-x slime and change the
current directory to that of the bindings generator with
Once I made some changes to the source I do a
:okra-bindings-generator) in Slime and place the files in the Okra
root directory with
bin/rsync-generated-bindings.sh (this is from
I use rsync because it will only replace the files that have been
changed so that
make and the CL implementation only have to recompile
those changed files which saves a lot of time. Sometimes this leads
to problems however and I do
replaces all the bindings files. (It also deletes the
which shouldn't be really necessary.)
Then I issue a
make from the Okra root directory to create the new C
wrapper libraries and after that I run one of the examples.
./physics-and-input.sh from the
examples directory at the time of
writing since I do not have regression tests yet.)
Everything ...Ptr should probably be handled like MeshPtr if they give problems.
Passing a vector (#(a b ...)) is much slower than passing the values as seperate arguments. (At least on SBCL 1.0.25.debian.)
SBCL is quite a bit faster than CCL for me on Windows. At the time of writing (2009-09-02) this was with SBCL 1.0.22 and a recent SVN checkout of CCL.
If your libs directory is empty you'll either to download them from the homepage or you can try to compile them yourself in which case you'll need to download and install MinGW, MSYS and CMake:
Install MinGW first and then MSYS. Use MSYS version 1.0.10. There's guides and information on http://www.mingw.org/ if needed. (http://www.mingw.org/wiki/HOWTO_Install_the_MinGW_GCC_Compiler_Suite)
I suggest first trying the libraries that come with Okra and only then the MinGW route unless you're familiar with the latter.
You will need the DLLs from the OgreSDK. You can download the SDK at:
You need the Code::Blocks + MinGW version (which is currently at version 1.6.1 but this doesn't matter). You will need at least the following DLLs (from
libclois-lane.dll if you want to run
the demo that depends on clois-lane). These last two you will need to
compile for yourself.
The CMake scripts do not find Ogre correctly on MinGW yet so you'll
have to check
CMakeLists.txt in the Okra directory and change it to
point to the correct locations (the two lines below "if (MINGW)").
If all of this is done you can issue:
cmake -G "MSYS Makefiles" (not
And if everything goes right (probably not) it should end up in the
Q. Why are both LOOP and ITER (package ITERATE) being used?
A. When I started programming Common Lisp I preferred ITER, but lately
I've come to appreciate LOOP, if only because it means less
dependencies when writing libraries for public consumption. Ofcourse,
this argument isn't of much use when using both in a library.