Embedthis GoAhead 3.3.1
Home >Source Code > Porting GoAhead

# Quick Nav

- Porting to a new O/S
- Working with the Team

# See Also

# Porting GoAhead

Porting any software is not for the novice. It requires considerable skill to read another person's code and adapt it to a new environment. These instructions are intended for experienced developers who want to port GoAhead to a new operating system or processor architecture.

GoAhead has been written to maximize the ease of porting to a new environment. The O/S and processor-dependent code have been contained while the bulk of the code is cross-platform. Most of this dependent code is in the runtime.c source file.

NOTE: When attempting a port, you should get the latest copy of the development source rather than using the download source package. You can get the latest development source by checking out a copy from the repository.

NOTE: Please read Building from Source before your read this document. It provides valuable background about building from source.

## Steps in Porting to a new Operating System

1. ### Pick a Name for the O/S

   If you are porting to a new operating system, you need to pick a symbolic name that will be used in conditional compilation, Makefiles, MakeMe files, and operating system specific directories. Some existing O/S names are: "linux", "windows", "freebsd", and "macosx".

   These names are used as upper-case pre-processor defines and in some cases as lower-case directory names.

2. ### Select the base O/S to Copy

   The easiest way to port to a new O/S is to find the closest existing supported O/S that the GoAhead software already supports and use it as a base to modify. For example, if you are porting to QNX, you may want to use the Linux port as a base.

3. ### Create the output products directory

   You need to create a directory for the build products: objects, binaries etc. This should be named OS-ARCH-PROFILE. For example: qnx-x86-debug. Under this directory create the inc, bin and obj directories.

       mkdir -p qnx-x86-debug/bin qnx-x86-debug/obj qnx-x86-debug/inc

4. ### Create the Makefile

   Create the Makefile by copying the makefile for the similar O/S. i.e. in our example, Copy the projects/goahead-linux.mk Makefile to projects/goahead-qnx.mk. Then edit the appropriate compiler and linker switches. Edit the top level Makefile if required to chain to this new Makefile.

       cp projects/goahead-linux.mk projects/goahead-qnx.mk
       vi projects/goahead-qnx.mk

5. ### Tailor the cross-platform O/S header.

   To insulate most of the GoAhead source code from the differences of various operating systems, the src/paks/osdep/osdep.h header file wraps all the required O/S headers and publishes a consistent set of types and prototypes. None of the source files include normal O/S headers like <string.h>. While this does slow the build by including more headers than are required — it is barely noticeable on modern CPUs.

   When porting the osdep.h, start by copying the sections in osdep.h that pertain to your base copied O/S. These will be protected by "#if BASEOS" defines. In the example of QNX, we would look for, and copy, any sections with "#if LINUX" and create "#if QNX" sections.

   DO NOT introduce conditional code in other O/S sections. It is better to copy the entire contents from the base O/S and modify. It is better to isolate the code for each O/S.

6. ### Test the Headers with a Hello World Program.

   Don't use the make system yet. Just create an empty C hello world program and include "osdep.h". Compile it and shake out the issues.

7. ### Port the per O/S runtime source code

   Now is the time for the real work. You will need to modify the runtime.c file to support your new platform. Search for conditionals for the BASEOS you chose and copy and modify these sections.

8. ### Test the runtime

   To start out, test compile just the runtime.

       make NEWOS-ARCH-debug/obj/runtime.o

   At this stage of the porting effort, the make command will undoubtedly provoke a stream of errors. Use this to work out the bugs in osdep.h and runtime.c for your O/S.

9. ### Compile the Rest

   After the runtime, it is more downhill. The rest of the code should compile and build more easily. It is quite cross-platform.

       make

10. ### Test GoAhead

        cd test
        goahead-test -v

## Working with the GoAhead Development Team

Once you have a basic port running, you should send it back for the team to look over. They can provide advice and suggestions. At the first opportunity, your changes may be merged back into the development tree so others can benefit from your work.

Good luck and have fun. Please give feedback to the development team at dev@embedthis.com.

© Embedthis Software LLC, 2003-2014. All rights reserved. Embedthis and Embedthis GoAhead are trademarks of Embedthis Software LLC.