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:

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Compile the Rest of the MPR

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

make
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.
Run:

cd mpr/test
make test
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
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
Test HTTP
cd test
make test
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 .

Quick Nav

Porting to a new O/S
Working with the Team

Porting AppWeb

Porting to a new Operating System

Working with the AppWeb Development Team

Quick Nav

See Also