Developer Guide for the OSDL 0.5 version

Overview

The intended public for this document is OSDL developers, i.e. working on the library itself: OSDL users ought to refer to the OSDL User Guide.

This developer's guide is still to be written, however here are a few hints about OSDL's inner working.

See also: Ceylan developer's guide for common informations.

Note: this documentation is quite deprecated, it would need some serious update and rewriting.

Conventions

Overall conventions

For some transverse subjects, such as the anti-aliasing mode (wanted or not), at least two ways of managing these informations were possible, having them static or not:

The first solution was preferred, since the 'singleton to many instances' transition could be performed with a state machine indeed, but the call to static methods could handle that internally without needing to perform tremendous changes in the code that uses these features: that change could be transparent for user code.

Endianness (byte order)

The endianness of the system is detected at compile-time (#if SDL_BYTEORDER == SDL_BIG_ENDIAN...#else ... #endif), not at "run-time" ( if (SDL_BYTEORDER == SDL_BIG_ENDIAN) {... } else { ... }). This does not change much, since even the second form, which should evaluate to a comparison between constants, should be translated by the compiler similarly to the first one.



[Back to table of contents]



OSDL release management

Releasing a new OSDL version

First of all, the Ceylan release guide should be applied in the OSDL context as well. Additional actions are:

As for SVN, it leads to a tag command like:

svn copy https://osdl.svn.sourceforge.net/svnroot/osdl/OSDL/trunk https://osdl.svn.sourceforge.net/svnroot/osdl/OSDL/tags/release-0.5.0 -m "First release of the 0.5 series, with SVN support, autotools-based build system, integration to the Ceylan 0.6 version, improved OSDL scheduler."

Here is an example template for the osdl-announces@lists.sourceforge.net list:

Subject:
OSDL 0.5 released!

Body:

Hi,

we are proud to announce the 0.5.0 version of the OSDL library.

OSDL 0.5 is for the moment GNU/Linux only, and offers about the same features as the 0.4 version, but its build system has been completely revamped.

OSDL 0.5 is somewhat an intermediary version, between the 0.4 which was truely ancient (dated back to 2005 Q3), and the upcoming OSDL versions, that should add the Windows XP support and the XML management with OpenGL of tilesets for animated sprites.


Main OSDL 0.5 changes are:

	* SVN used instead of CVS

	* the Autotools are used, instead of custom-made GNUMakefiles

	* integration to the Ceylan 0.6 version

	* OSDL scheduler robustified and enhanced a lot

	* numerous tests improved (full test suite added), and many bugs fixed

Feel free to download latest LOANI archive (ex:
http://downloads.sourceforge.net/osdl/LOANI-0.5.tar.bz2) to test OSDL 0.5.

Support available through the osdl-support@lists.sourceforge.net mailing list.

Report OSDL bugs to the osdl-bugs@lists.sourceforge.net mailing list.

Homepage at http://osdl.sourceforge.net

Enjoy!

Wondersye, on Friday, March 30, 2007.

The corresponding news item could be:

Summary:
OSDL 0.5 released!

Body:
we are proud to announce the 0.5.0 version of the OSDL library.

OSDL 0.5 is for the moment GNU/Linux only, and offers about the same features as the 0.4 version, but its build system has been completely revamped.

OSDL 0.5 is somewhat an intermediary version, between the 0.4 which was truely ancient (dated back to 2005 Q3), and the upcoming OSDL versions, that should add the Windows XP support and the XML management with OpenGL of tilesets for animated sprites.

Main OSDL 0.5 changes are:

	* SVN used instead of CVS

	* the Autotools are used, instead of custom-made GNUMakefiles

	* integration to the Ceylan 0.6 version

	* OSDL scheduler robustified and enhanced a lot

	* numerous tests improved (full test suite added), and many bugs fixed

Feel free to download latest LOANI archive (ex:
http://downloads.sourceforge.net/osdl/LOANI-0.5.tar.bz2) to test OSDL 0.5.

Support available through the osdl-support@lists.sourceforge.net mailing list.

Report OSDL bugs to the osdl-bugs@lists.sourceforge.net mailing list.

Homepage at http://osdl.sourceforge.net

Enjoy!

Wondersye, on Friday, March 30, 2007.

Then update both LOANI archives in Sourceforge file release system.

Prepare for the next version

Follow again the Ceylan release guide.

Customization

To use another version of gcc than the one OSDL selected (use make checktools to check which would be used by default), redefine GCC_ROOT make variable so that it points to the compiler you want to use. Ex: if one wants to use the gcc compiler installed under /usr/local (i.e. /usr/local/bin for gcc executables and /usr/local/lib for its libraries), one would use: make all GCC_ROOT=/usr/local. If GCC_ROOT is not redefined, and if with its default value (GCC_ROOT being the directory where OSDL and Ceylan were extracted, i.e. GCC_ROOT = OSDL/OSDL-x.y/src/../../..) no compiler can be found, then it will be searched through the PATH. If gcc is to be found in the PATH, its corresponding libraries are supposed to be found in the LD_LIBRARY_PATH environment variable.



[Back to table of contents]



Random hints

Retrieving cutting-edge OSDL code

One should get latest OSDL sources from SVN:

svn [--username YourSFUserName] co https://osdl.svn.sourceforge.net/svnroot/osdl osdl

Compilation flags

Meaning

Main make variables that can be used to customize build
Make variable Meaning Used in build phase
INC include flags compilation
DFLAGS debug flags compilation and link
CFLAGS compile flags compilation
LDFLAGS link flags link
OPT option flags compilation and link

Use

Overall architecture of the Ceylan-OSDL pair

Image

With many projects, fine tuning of installation settings is difficult since usual make variables, such as INC or LDFLAGS, are set and used directly by the project.

For example, often the configure step determines which series of library names and locations should be used. Too often, there is no way for the user to define his settings and to add directly what lacks.

For example, users need to be able to add to LDFLAGS the following: -L<a path> -l<a library>. Unfortunately, they cannot use make LDFLAGS="-L<a path> -l<a library>" since LDFLAGS is used by most project, and it would erase any previous information hardcoded in LDFLAGS.

An unsatisfying solution would be to take LDFLAGS's hardcoded value, to add the settings the user wants to add, and to define a full new LDFLAGS value, which would contain both informations, from the command line. This solution is a bad idea, since the hardcoded value, often set by the configure step, depends on the platform, therefore the user fix would break portability.

To overcome this issue, we chose deliberatly not to use in OSDL internals the following variables:

but to leave them blank (ex: LDFLAGS=) and to make us of variables with the same names, but suffixed with _PRIV, which stands for "private to the project" (ex: LDFLAGS_PRIV).

That way, everywhere where library informations were needed, we used $(LDFLAGS) $(LD_FLAGS_PRIV), in that order, letting the possibility to customize the build thanks to a LD_FLAGS which would not interfere with our LD_FLAGS_PRIV. So the user just has to specify make LDFLAGS="-L<a path> -l<a library>" to add, not replace library informations and such.

Of course, if ever one wanted actually to replace these values, he just would have to specify make LDFLAGS_PRIV="-L<a path> -l<a library>".

This procedure applies for the Ceylan library as well.

Build messages

One should not be afraid of those libtool warnings for various libraries:

libtool: link: warning: library `<your path>/LOANI-installations/SDL_image-1.2.3/lib/libSDL_image.la' was moved.

For the moment, we did not manage to get rid of these messages, but they do not really matter since they do not denote any real problem.

Filenames

The library itself, whether downloaded as binary or rebuilt from sources, is named:



Please keep in mind that OSDL is a multimedia-oriented library built on top of prerequisites, so you should install them priorly to have OSDL-0.5 working.


Setting up one's environment by script

One interesting file to source is OSDL-environment.sh, which is to be found under the prefix used by LOANI, LOANI-installations by default.

By sourcing this script, you set your shell environment so that all LOANI installed tools are selected, thanks to the PATH and LD_LIBRARY_PATH environment variable.

Debugging rendering code

When developing code that performs rendering, it is often difficult to know what is exactly drawn in each step, or what might be the culprit of an unintended behaviour: the graphic system (OSDL) or the user program performing the actual rendering? One very easy way to tell it is to use the screenshot generating capabilities of the Surface class. For example, using Surface::savePNG allows to freeze graphics being generated at runtime, in order to understand what happens actually.

Tests

The build of tests is split from library's build, since we designed these tests to behave exactly as any other user application which would make use of Ceylan or OSDL.

Please react!

If you have informations more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!




[Top]

Last update: Monday, January 3, 2011