OSDL Porting Informations

Overview

OSDL and Ceylan, its helper library, are designed to be portable, and they aim to be supported by following platforms:

• Unix [more infos]
  • System III & V family
    • GNU/Linux [supported], for all kinds of distributions
    • Solaris [to-do], for all various Sun Solaris versions
    • AIX [to-do], for all various IBM AIX versions
  • BSD family
    • FreeBSD [ported a few versions ago, to be updated]
    • NetBSD [ported a few versions ago, to be updated]
    • OpenBSD [to-do]
    • Mac OS X [to-do], all versions, including Panther, Tiger and al
• Windows family
  • Windows 2000 [to-do]
  • Windows XP [supported]
  • Windows Vista [to-do]
  • MinGW [not needed since Visual Studio Express]
  • Cygwin [not targeted]
• Handheld family
  • Nintendo DS [supported (only a subset of the features available though)]

Note that an important effort with the autotools and Sourceforge compile farm has been performed, thus porting our libraries to new platforms is a quite easier challenge than before.

One of the main concerns raised by portability is to ensure the application can be built with as little changes of its source code as possible. This is the task of a relevant build system to hide the system specificities and to configure appropriatly the application. This topic is discussed in our build system section.

There is only one means of knowing whether a platform is supported: it is to actually take a source release of the developments and to try to build it from scratch. Therefore one should have access to every platform to support, which is detailed in our quality section, in the testing subsection.

Platform management

Platform detection

As, for each platform, the most convenient build system is chosen, it is the task of each build system to apply any platform-specific action.

On UNIX platforms and on cross-compilation-based ones (Nintendo DS), the autotools (autoconf, automake and al) and GNU make are used.

On other systems, a dedicated project file is given, which thus can have the platform type directly taken into account. This is the case notably for the Windows build, making use of the Visual C++ Express (free) editions.

Platform adaptation

Once the platform is known, adaptation has to be made. The customization is based onto compiler flags being set. Not only the very specific platform is described by an appropriate preprocessor symbol, but the successively more general families are taken care of, as well. For example, from the most specific to the least, one could have FreeBSD, BSD family, UNIX, POSIX.

We placed here the Ceylan platform-specific identifiers (ex: CEYLAN_ARCH_LINUX), OSDL counterparts can be easily deduced (ex: OSDL_ARCH_LINUX).

Following specific platform symbols are defined, in the same categorization order as for the supported platforms:

• UNIX: CEYLAN_ARCH_UNIX
  • System V: CEYLAN_ARCH_SYSTEM_V
    • Linux: CEYLAN_ARCH_LINUX
    • Sun Solaris: CEYLAN_ARCH_SOLARIS
    • IBM AIX: CEYLAN_ARCH_AIX
  • BSD: CEYLAN_ARCH_BSD
    • FreeBSD: CEYLAN_ARCH_FREEBSD
    • NetBSD: CEYLAN_ARCH_NETBSD
    • OpenBSD: CEYLAN_ARCH_OPENBSD
    • Mac OS X: CEYLAN_ARCH_MACOSX
• Windows: CEYLAN_ARCH_WINDOWS
  • Windows 2000: CEYLAN_ARCH_WIN2000
  • Windows XP: CEYLAN_ARCH_WINXP
  • Windows Vista: CEYLAN_ARCH_WINVISTA
  • Cygwin: CEYLAN_ARCH_CYGWIN
  • MinGW/MSYS: CEYLAN_ARCH_MINGW
• Handhelds:
  • Nintendo DS: CEYLAN_ARCH_NINTENDO_DS (generic flag)
    • DS ARM7: CEYLAN_RUNS_ON_ARM7
    • DS ARM9: CEYLAN_RUNS_ON_ARM9

Some more cross-genre symbols are defined:

• CEYLAN_ARCH_UNIX_ON_WINDOWS = CEYLAN_ARCH_CYGWIN and CEYLAN_ARCH_MINGW
• CEYLAN_ARCH_POSIX = CEYLAN_ARCH_UNIX and CEYLAN_ARCH_UNIX_ON_WINDOWS

When writing platform-dependent code, one has to use these preprocessor defines, such as #if CEYLAN_ARCH_LINUX...#else...#endif or #if ! CEYLAN_ARCH_MINGW...#endif. Preprocessor commands should not be indented: they should all begin at the first column, except for severely nested defines.

These preprocessor tests should apply to a specific platform symbol only if the same test cannot be expressed thanks to a feature symbol: prefer when possible CEYLAN_USES_FILE_DESCRIPTORS to CEYLAN_ARCH_UNIX, for example.

The order of the different code replacements is chosen so that the most common ones are the first listed in the file.

Each else or endif is followed by a comment reminding to which symbol test it is linked to.

Finally, platform-dependent code should look like:

#if CEYLAN_USES_FILE_DESCRIPTORS
...
#else // CEYLAN_USES_FILE_DESCRIPTORS
...
#endif // CEYLAN_USES_FILE_DESCRIPTORS

Per-platform discussion

GNU/Linux

This is the main developer platform for both Ceylan and OSDL. The build system uses common GNU tools: the dreadful autotools, the GNU compiler tool chain with gcc, the GNU make, etc. on the command line.

GNU/Linux is also the platform from which cross-compilation to the Nintendo DS is performed. It is based on GNU make and on the devkitARM toolchain and related (ex: libnds).

FreeBSD & NetBSD

They could be used as a developer platform as well (although we actually preferred to stick to Linux). This is the reason why LOANI was ported from bash to sh, and why some adaptations had to be made.

Windows

In general, the Cygwin runtime should not be used since it is GPL, whereas our developments are LGPL [more infos]. Note that one can purchase from Cygwin a commercial license of their product that removes the GPL constraints. Hence, in this very particular case, our developments can be set to use Cygwin libraries for that user, who cannot release them tough.

Despite the Cygwin runtime generally will not be used with Ceylan/OSDL (as explained above), Cygwin shell, tools and command-line environment can be used to help the build, as long as, at the end of the process, the result to be released does not depend anymore on Cygwin work, notably on Cygwin libraries.

MSYS can be used for that matter as well. It is more lightweight, more limited, but has no license concern regarding our LGPL use.

The initial Windows porting plan was to make use of MinGW with the Code::Blocks IDE [see MinGW Starter Guide].

Another solution could have been to cross-compile Ceylan and OSDL (for example from GNU/Linux) to Windows [see MinGW cross compilation guide].

We finally preferred to use the Visual C++ Express Edition, released freely by Microsoft. See our section dedicated to the development toolchain for Windows for more informations.

Not that for FAT file systems, creation and last access dates and times are not managed.

Common & optional features

Basically there are very common features that each and every platform provide, such as string manipulations or video display creation. OSDL provides them natively thanks to the few C++ language built-ins, and to portable back-ends, such as SDL for most platforms, or custom-made developments for others (the Nintendo DS).

There are also less frequently features that are not available on all platforms. One example is the regular expressions, often natively supported by the UNIX platforms only. From Ceylan/OSDL point of view, they are optional features that may or may not be available. The user can test whether they can be used thanks to the Ceylan::Features and OSDL::Features namespaces. An example would be: Ceylan::Features::checkForSupportedFeatures( RegularExpressions | Threads ).

These optional features are activated on a per platform basis. Here are the relationships between a platform type and the enabled features:

• regular expressions are available if and only if the CEYLAN_USES_REGEX symbol is set, which happens if and only if CEYLAN_ARCH_UNIX is defined
• multithread is available if and only if the CEYLAN_USES_MULTITHREAD symbol is set, which happens if and only if CEYLAN_ARCH_UNIX is defined (no Windows support for multithreading yet)
• process primitives are available if and only if the CEYLAN_USES_PROCESS_MANAGEMENT symbol is set, which happens if and only if CEYLAN_ARCH_UNIX is defined
• each advanced file primitive is available if and only if the corresponding symbol is defined:
  • CEYLAN_USES_FILE_LOCK: if read/write locks on files are available
  • CEYLAN_USES_SYMBOLIC_LINK: if symbolic links may be used on filesystems able to support them
  • CEYLAN_USES_FILE_DESCRIPTORS: if low-level file descriptors can be used with the underlying system
  which usually happens if and only if CEYLAN_ARCH_UNIX is defined

Please react !

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