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 dev@mbedthis.com 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:
- Select the Required AppWeb Features
Copy conf/appWeb/normal.conf to conf/appWeb/myport.conf and edit and modify the feature selection as required. In your myport.conf defaults file, pay attention to the BLD_HOST_OS, BLD_HOST_CPU and your required FEATURE
selections. You may need to define new MPR_CPU constants in the mpr/mprOs.h file if you are doing a port to a new CPU architecture that is not already supported.
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_FOR_HOST to 1 in the conf/appWeb configuration files described below. Also remember to modify the BLD_DEFAULTS setting to the name of your defaults file.
- Run configure for the new target operating system.
Run the configure program and specify the --host and --build switches. These switches take arguments of the form: CPU-VENDOR-OS. The conf/config.sub script validates these arguments. Most probably, your O/S and CPU architecture are already in this file. Review the file to see what is the best way to refer to your required O/S and CPU architecture. If you can't find your choices, you may need to modify this script to add a new operating system or CPU.
When ready, run configure to generate the config.make, config.sh and config.h master build files. For example:
./configure --product appWeb --defaults myport --host powerpc-wrs-vxworks --build i586-pc-cygwin --disable-multi-thread
- Pick a Name for the Operating System Port
If you are doing a port for a new operating system you need to pick a symbolic name that 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 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 <string.h>. 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 dev@mbedthis.com.
|