Porting Appweb

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 Appweb to a new operating system or processor architecture.

Appweb 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 under the src/deps/mpr sub-directory which represents the Multithreaded Portable Runtime (MPR).

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 doing a port for a new operating system, you need to pick a symbolic name that will be used in conditional compilation, Makefiles, bit 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 Appweb 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/appweb-linux.mk Makefile to projects/appweb-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/appweb-linux.mk projects/appweb-qnx.mk
   vi projects/appweb-qnx.mk
   

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

   To insulate most of the Appweb source code from the differences of various operating systems, the src/bitos.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 bitos.h, start by copying the sections in bitos.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 "bitos.h". Compile it and shake out the issues.

7. Port the S MPR Source Code

   The Multithreaded Portable Runtime (MPR) wraps the operating system services and exposes a portable, consistent interface for Appweb to utilize. So now is the time for the real work. You will need to modify the mprLib.c file to support your new platform. In mprLib.c, you will see banners marking where the various sub-files have been catenated together. The main sections to modify will be socket.c, thread.c time.c and wait.c. Search for conditional code sections for your base O/S and copy/modify as appropriate.

8. Test Compile the Mpr

   To start out, test compile just the MPR library.

   make NEWOS-ARCH-debug/obj/mprLib.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 mpr.h and mprLib.c for your O/S.

9. Compile the Rest

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

   make
   

10. Test Appweb

    cd test
    appweb -v
    

Working with the Appweb 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.