Porting_Guide

This document briefly describes how the X3P Library should be portable to other operating systems and computing platforms. Porting is necessary due to the lack of standardized I/O functions, e.g. opening/closing a file handle, and because of different hardware architectures, e.g. less/big-endianess of a specific processor type.

Overview

• The principal philosophy is to make every operating system or computing platform specific operation accessible via some suitable interface method that needs to be provided by the Environment interface class. This Environment interface is only to be used from within the X3P library itself and is not to be exposed to the public user of this library, i.e. the interface is not to be made available via the public include directory.
• Then for every supported platform the corresponding implementation of the Environment interface needs to be written, e.g. Win32Environment.
• Through the use of compile time macros, only the appropriate one of those Environment implementations is actually compiled.
• An instantiated object of the chosen implementation is accessible through a static method from anywhere within the library by using the Environment interface.

Details

This lists the necessary steps when adding support for a new operating system. The final goal is to come up with something analogous to the /trunk/src/ISO5436_2_XML/cxx/win32_environemt.{h,c}xx files that adapts to the operating system to be added.

• Create the new files /trunk/src/ISO5436_2_XML/cxx/newos_environemt.{h,c}xx and implement the Environment interface from /trunk/src/ISO5436_2_XML/cxx/environment.
• Do not forget to implement the Environment::GetInstance() method within the newly created files, which provides an instance of your new implementation.
• Surround the code within both files with an appropriate #ifdef macro, so that the compiler only recognizes the new code when it is compiled for exactly that platform.
• Using the same compile time macro as above, ensure that all the other /trunk/src/ISO5436_2_XML/cxx/*_environemt.{h,c}xx implementations files skip code generation.

Hopefully this is everything you need to do, but possibly you will encounter problems:

• Although the existing C/C++ has been written to be standard compilant, there might of course be issues.
• Probably the use of the <tchar.h> include may cause minor problems, specifically the use of the _T("...") macro within the code, but the macro can easily be duplicated and copied into our own files.
• Unicode strings when streamed to std::cout may cause problems. Especially the Info class (there may be other locations) streams string data directly to std::cout. On Microsoft Windows std:cout is always treated as an ANSI stream even if the compiler has the UNICODE macro set. Therefore all string data is converted using String::ToChar method before it is streamed. Other operating systems may provide a unicode std::cout.
• The xsd tool from CodeSynthesis used for generating the XML serialization class may produce slightly different code on the new platform.

Build system

The current build system is solely based on a Microsoft Visual Studio solution file. To support other operating systems than Microsoft Windows this has to be ported to cmake before the library itself can be ported.