1. Intro

1.1 What and Why?

The System Optimisation Library is designed to make it easier to write code for cross platform use, without having to explicitly take into account every platform that you, or the users of your software/libraries, might be compiling your code on. And, even in the case that you do know this beforehand, you can still save yourself the time and effort of writing the code yourself.

I personally, find Operating System A and Operating System B (not named so as not to offend users) on the Hardware X platform sufficient and delightful for everything I want to do, except for cross platform development, since I can't easily test other platforms on them. However I know other's have their own preferences, and I personally do not believe in locking a user into my one particular platform, simply because I like the platform and I don't want to bother spending time/money developing for other platforms. I think that, since many tasks can be done cross platform, with only minor extensions, libraries to help out with this should be created, so rather than testing and developming on all the platforms, I can test and develop on one or two, and allow others to use my applications on other platforms with a minimal amount of fuss and hassle. As a software developer, I do not feel I have the right to bend the user to my platform of choice, and in fact, I have at least moderate obligation to bend my own work to be helpful to the user.

The main main features of this library are: Endian information; there is one predefined macro which will tell you the system's endian. Predefined macros for variable sizes; for the basic integer, and floating point types, there will be a macro to designate the size, in bytes, of each. This can improve performance over sizeof, which may require runtime instead of preprocessor-time calculations for your code. Explicitly sized integer variables; using the SDL naming convention, with a bit of expansions, there are macros to expand to every integer variable size from 8 bit to 64 bit, provided they exist on a platform. Ultra long integers; many compilers have an integer that is guranteed to be as large or larger than a long, such integers are macro'ed here to have one common name. General Optimization; some compilers have optimisation (or library export) commands that can be given, but they are by no means ubiquitous: This library will define macros for several of these so that they can be used (or at least left blank on systems where they cant) with the same keywords.

Everything in this library is done precompiler time, and therefore, it should not hinder or slow down program execution, and properly used, can provide significant execution gains.

Lastly, PLEASE HELP. I don't have a lot of money to get a lot of equipment. Currently I'm planning on gritting my teeth and getting a mac-mini to add one more platform (I'd much rather go for a G5 tower if I'm going to get a Mac, but I need to get one before I've no choice but to use a little endian Core processor, and the endian is the other big reason I want a mac). So, if you have a platform that is not yet supported, it should only take you a few minutes to set up the library for your platform, and contribute it to the site, and I, as well as the cross platform developing community, would be quite grateful.

1.3 Conventions

The main conventions to this library are specified in the documentation. Basically, every macro needs to be defined for every compiler/OS where it is applicable, and defined in such a manner that it will either (A) have the desired effect on the compiler/OS, or (B) do nothing and allow the compiler to compile without errors (normally this is simply an empty define). If at all possible, implementing method (A) in a compiler/OS setup is intended.

The only other conventions for this library are for file structure. In the base source directory, only system_opt.h should be present. This file should link to the appropriate compiler file, based on the compiler that has been determined to be compiling the program. The compiler header files should be in a directory named either for the name of the compiler, or more likely, it's abbreviation ("gcc" for GNU Compiler Collection, "msvcpp" for Microsoft Visual C++, etc.). The actual compiler header should have the same name as the directory, with a ".h" appended. Lastly, for each architecture the compiler can compile for, there should be a compiler/arch file in the same directory as the compiler file. The compiler/arch file is given the directory name, appended by and underscore and the arch name/abbreviation, with a ".h" tacked on to the end.

Contributors: Please update the changelog of this documentation in the CVS when you make changes!! Additionally, if you would like to add any more features, please tell me.

1.3 Licencing

This software is created and distributed under the BSD software Licence:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.