© Copyright 2006 The 'Verse Project. All rights reserved.
Hosted by:
This document attempts to ease the porting process. Or at least provide a loose checklist for porting. It would also be useful for a new developer for a platform that is already supported as it gives a glimpse of the inner workings of the project. Also, this document is primarily describing the porting of the main engine (the theVerse module in CVS). We are doing this as it is the most complicated of all the modules and if the porter ports that, the other modules will be simple in comparison.
Please note that we will be doing our best to keep this document up to date with the CVS not release.
Also note that since no-one has gone through porting these app's yet, we can't really give any hints or tips. But, as they come in, or we figure some out, they will be posted here. After all, we've already posted a couple things to keep an eye on.
Obviously, if you are considering porting this project to a new platform (or contribute to an existing one), subscribing to the relevant mailing list(s) is a must. A list of the available mailing lists is here. Subscripting can be done there as well.
Currently, there exists only one mailing list; the general developer mailing list. Once you've gone through the developer documentation, familiarized yourself with the code base, and have decided to contribute to the project, announce yourself there.
There are a couple reasons for this. First off, we like to know what people are working on as it may influence design/tech/etc decisions. Secondly, someone may have already started work on the port and coordinating is much better than duplicating. And lastly, reading the list for a while, will give an idea of the current development direction, who's doing what, etc.
First thing is to make sure that all the libs, etc listed here have an appropriate license on your platform. As in, licenses that allow us to retain our BSD license. If in doubt, ask.
From here on in, we'll assume here that you've already installed all the requirements, they're functioning properly and have appropriate licenses.
The first thing that must be done is finding out what os.platform says then add this to supported_platforms in SConstruct. Next is to go through SConstruct and make sure that all the libs are being included, etc. Everything is pretty well documented and sectioned. So, it shouldn't be difficult to figure out what's what. Also, note that any changes done may (will probably) require updating the SConstruct file.
Within each module there will be a docs directory. This will contain a design doc (if only a loose one) so that you have a better idea of how things work. It should be up to date, but if it isn't find out who's in charge of that module and ask. It's there job to make sure that it stays basically up to date. So, if they fail in this regard, it's there job to be that document.
This functionality is in loadlib.[c,h]. So, for those that have dlfcn.h on there system, including loadlib.h will just include dlfcn.h. That being said, the porter must look in loadlib.h as things have different names (yes, I know that this is somewhat "administration" of us to do, but there are reasons for it).
Because some systems are not going to have dlfcn.h (e.g. Windows), we will have to use there native dynamic loading API. So, things like mutex's will obviously have different names, types, etc.
We have "solved" this by using names defined by us and referring to that in the code. That way, no matter what system we are on, the proper type, etc will be used without the need to have #ifdef's all over the place.
So, when porting to a new system, if it is required to use that systems dynamic loading facilities, loadlib.[c,h] will have to be altered accordingly. This will limit this messiness to this one file. At least for this one issue...
Audio is optional and the lib to use is set at compile time. To disable audio, use the with_audio=none switch (type 'scons with_audio=none').
Once things are working with no audio, if OpenAL has be ported to your platform, try compiling with it. If OpenAL has not be ported to your platform, then there are three choices, 1) port it, 2) find another lib under an appropriate license, or 3) failure of (1) & (2) leaves, leave the audio disabled. In any case, the audio option should be set as the default in SConstruct.
pthreads is the current default library. Though threading has currently not been coded, there will be two interfaces to the pthreads library; one for static linking, the other for dynamic linking. The reason for this is that Windows pthreads implementation has been licensed under the LGPL requiring dynamic linking.
Thus, if your platform has a pthreads implementation, check the license to see how to link against it. If it does not have an appropriate license, then an alternate threading library must be found and used (assuming one exists).
Please keep in mind that threads.h serves as a guide as to what needs to be coded. It's modeled after the pthreads library so any other implementation needs to at least be able to mimic that functionality. See threads_pthread* for examples.