Cross_Platform_Guide

[Home] - also see: [Code_Style_Conventions] - hosted at openANTz.com

also see [Code_Style_Conventions]

---

Platforms:

MSW - XP, W2K3, Vista, W7 (32 & 64bit)
OSX - 10.5, 10.6 and 10.7
Linux - CentOS, Red Hat, Fedora, Ubuntu, SUSE, Debian

*BSD under consideration

ANTz is a cross-platform application written in C99 and can be wrapped in C++ or Cocoa (OSX).

This guide is intended to allow programmers to generate code on one platform that is easy to port to others. It is good to keep in mind that we plan to make ANTz into an API library that can be used by other apps.

ANTz Conventions:
- All platform specific code and libraries are isolated in the '\os\' folder. The files 'os/npos.h' and 'os/npos.c' serve as a re-direct for all OS specific methods. The actual OS specific code resides in a sub-folder for that OS, such as 'os/msw/npmsw.h' which is also where the actual OS specific libraries are included, for example 'windows.h'.


- Be aware that when adding any platform specific functionality it needs to be implemented across all platforms. So either write the other OS methods at the same time or get someone else to do it. Otherwise the code will not be included.


- Sometimes there is no cross-platform method possible for a desired functionality. In this case the additional functionality should likely be made into a plugin using a .DLL(MSW) or .RO (OSX and Linux). An exception is video codecs, on OSX we will likely use QuickTime, on MSW and Linux we plan to use VLC, (which does not work for OSX.) In some cases a special code branch is made, (different version of ANTz,) However there has to be a very good reason, such as support for the infinite z, (they intend to make their library cross-platform in the future.) Either way the IZ system will likely be made into a plugin at a future date.

Issues:

Line Endings - CRLF(MSW), CR(OSX), LF(Linux)
- CSV files need to be tolerant to all of the above.
- Code files (.c and .h etc...) need an extra blank line return at end of file.

File Path - '\'(MSW) vs '/'(OSX, Linux)
- file path routines need to be OS aware and use appropriate slashes.
- header include statements should always use a forward slash ("../io/npgl.h") as this works under all OS compilers (MSW, OSX, Linux.)

Visual Studio - is far too tolerant of bad code...
- watch out for 'warning' followed by 'assuming' resulting from missing function declarations usually a headers issue.

Xcode - also too tolerant of non-C code...
- allows C++ behavior in C files... avoid this.
- declare all variables at the top of the function before any logic statements.

BIG ENDIAN vs little endian
- watch out when doing any bitwise or bytewise operations.
- be-aware of byte orders in communicating with other machines.

Global Variables
- rather then use globals, it is preferred to store global-like variables in the main data structure, (data->...myVariable).
- however, temporary use of globals to aid short-term development is okay, just do not initialize them when declared, as this has caused problems. Instead use one of the startup Init...() functions to initialize global variables.