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 Embedthis
Appweb product to a new O/S or processor architecture.
Embedthis 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 Embedthis 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:
- 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 Required Appweb Features
Copy build/standard.defaults to build/myport.defaults and edit
and modify the feature selection as required.
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.
- Edit the configure script
Edit ./configure and add your O/S to the
setSystemConfiguration function. If your system is UNIX like,
make sure you set eval ${unix}=1. You may also want to add code
here to detect the O/S distribution.
- Create build/make/make.os.NEWOS
This step is probably one of the longest. You
need to create a build/make/make.os.NEWOS file and change all
the compiler and linker flag values for your operating system.
Copy a version from an O/S that is closest to your target O/S.
See the Building from Source
document for definitions of all the make variables used in this
file.
- Create build/os/config.NEWOS
You also need to create a build/os/config.NEWOS
file. This file describes the various tool names and file
extensions used by your O/S. There are two conditional
sections, one used for definitions for the host (target) system
and ones for the build system.
-
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 tools/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 buildConfig.make,
buildConfig.sh and buildConfig.h master build files. For
example:
./configure --defaults myport --host powerpc-wrs-vxworks --build i586-pc-cygwin --disable-multi-thread
-
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 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.
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 build/make/*
and build/os/* files.
-
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.
|