Porting AppWeb

Porting any software is not for the novice, it requires considerable skill to read someone else's code and to adapt it to a new environment. These instructions are intended for experienced and talented developers who want to port the Mbedthis AppWeb product to a new O/S or processor architecture.

Mbedthis AppWeb has been written to maximize the ease of porting to a new environment. The O/S and processor dependent code has been contained to a few files while the bulk of the code is cross-platform. Most of this code is under the mpr sub-directory which represents the Mbedthis Portable Run-time Executive.

NOTE: When attempting a port, you should get the latest copy of the development source branch rather than using the download source package. You can get the latest development source by checking out a copy from the Subversion repository. Send email to to request to be added to the Subversion authorization database. You will then be given checkout instructions.

NOTE: Please read Building from Source before your read this document. It provide valuable background about the AppWeb build system.

Porting to a new Operating System

Follow the following steps:

  1. Pick a Name for the Operating System Port

    This symbolic name will be used in Makefiles, build scripts and for per operating system directories. Use all CAPS for your OS name without any "_" or "-" characters. For example: "LINUX" is the AppWeb name for the Linux specific portions. For the rest of this document, we will use the name NEWOS for the O/S symbolic name.

  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. You will need to copy some base O/S directories and configuration files to become the starting point for your new port. The directories to copy are (assuming we are copying the LINUX port)

    cp -R mpr/UNIX mpr/NEWOS

    At this stage, don't copy all the per O/S package directories and files. These are used to create installable packages (E.g. RPM packages). If your system is UNIX-like, then you will use the mpr/UNIX/*.cpp files.

  3. Tailor the Build Configuration Files

    Next, you will copy the factory defaults file into a test defaults file. When you have completed your port, you may be able to use the standard defaults files. However, while debugging, you will almost certainly need to disable features as you progressively test and debug the product. A good place to start is by copying conf/appWeb/normal .defaults.

    cp conf/appWeb/normal.defaults conf/appWeb/test.defaults
    cp conf/appWeb/test.defaults conf/config.defaults

    In your defaults file, pay attention to the BLD_OS, BLD_CPU and your required FEATURE selections. You may need to define new MPR_CPU constants in the mpr/mprOs.h file.

    You should turn BLD_FEATURE_MULTITHREAD off (use configure --disable-multi-thread) for your first porting effort as it will make debugging much easier. Disable all the features that your O/S does not support. See the Building from Source document for definitions of all the build variables used in these files.

    If your system is UNIX like, make sure you set BLD_UNIX to 1 in the conf/appWeb configuration files described below. If your system is not UNIX like, then you will need to copy mpr/UNIX or mpr/WIN (which ever is closer to NEWOS) into mpr/NEWOS.

    Also remember to modify the BLD_DEFAULTS setting to the name of your defaults file.

  4. Tailor the make.os.NEWOS file

    This step is probably one of the longest. You need to edit the conf/make.os.NEWOS file and change all the compiler and linker flag values for your operating system. See the Building from Source document for definitions of all the make variables used in this file. When finished, copy this to make.os in the top level directory. It will be included by all Makefiles.

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

    To insulate most of the AppWeb source code from the differences of various operating systems, the mprOs.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 . While this does slow builds down by including more headers than are required -- on modern CPUs it is barely noticeable.

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

    Also look for the string "PORTERS" for tips of what to modify.

    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. Replication here benefits greatly later on by isolating subtle changes from one O/S to another.

  6. Tailor the Primary MPR header

    Next we edit the mpr.h header. Some operating system differences escape from mprOs.h and must be dealt with here. Search for sections that pertain to the base O/S and modify. It is acceptable and indeed preferable to modify sections rather than replicate. For example

    #if LINUX || QNX

    is better and clearer than duplicate code.

  7. 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 "mpr.h". Compile it and shake out the issues. You will need to define "-DNEWOS" on your compiler command line.

  8. Port the Per O/S MPR Source Code

    Now is the time for the real work. Most of the operating system dependent code is confined to three source files: thread.cpp, mprOs.cpp and daemon.cpp. Thread.cpp contains the multiprocessing thread, lock and condition variable code. If you only intend to support single-threading, you can largely skip these code sections. Copy these three files from your base O/S into the mpr/NEWOS directory and modify as required.

  9. Test the Make Subsystem

    To aid the porting to many operating systems, a simple build system is provided that is somewhat compatible with GNU configuration standards. While the GNU Autoconf/Libtool system could arguably do the job, it struggles in non-Unix environments. The AppWeb build and make system makes fewer demands on the underlying operating system and is simpler in scope.

    The make subsystem requires GNU make and a fairly compliant bash shell implementation. If you are using windows, the CYGWIN package will provide the GNU environment. If you are porting to an O/S that uses the GNU development tools, you probably have little to do in this step. If not, you may have more modifications required to your make.rules file.

  10. Test Compile the Mpr

    To start out, test compile one file in MPR first. Let's pick an easy one: buf.cpp. The AppWeb build system compiles objects for most directories into a common objects directory (./obj on Linux and on Windows: ./obj/Debug or ./obj/Release). This is done to make it easier to aggregate objects from various modules into common libraries. So to compile a single object, you need to specify the target object which will usually not be in the current directory.

    cd mpr
    make ../obj/buf.o

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

  11. Compile the Rest of the MPR

    Once you have buf.cpp compiling, try the rest of the MPR.


  12. Test your Port of thread.cpp and mprOs.cpp

    The mpr, ejs, http and appWeb directories all have extensive unit test suites to help you shake out the bugs.

    cd mpr/test
    make test

  13. Compile and Test ejs -- the Embedded JavaScript Interpreter

    This code should compile and build easily. It is quite cross-platform

    cd ejs
    make clean depend compile test

  14. Compile the HTTP Web Server and Modules

    We should be accelerating by now. Again, this module is mostly cross-platform. Try:

    cd http
    make clean depend compile

  15. Test HTTP

    cd test
    make test

  16. Port AppWeb

    The appWeb directory only contains the main programs. All other functionality it provided by mpr, ejs and http. You may have some modifications in the main programs to setup your run-time environment correctly. Issues like multithreading or single-threading are controlled here.

Working with the AppWeb Development Team

Once you have a basic port running, you should send it back for the team to look over and 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 all the best. Please give feedback to the development team at .

© Mbedthis Software LLC, 2003-2204. All rights reserved. Mbedthis is a trademark of Mbedthis Software LLC.