Quick Nav
See Also
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/mpr sub-directory which represents the Embedthis Portable Runtime (MPR).
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 repository.
NOTE: Please read Building from Source before your read this document. It provides valuable background about the Appweb build system.
Steps in Porting to a new Operating System
-
Select the required Appweb features
Edit the build/standard.defaults configuration file. This file contains the factory defaults for the configure program. Select the features you wish to support. But start with the smallest set possible.
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.
-
Define your O/S configuration string
The configure program uses two programs to parse --host and --build switches. They are: build/bin/config.guess and build/bin/config.sub. Most probably, your O/S and CPU architecture are already in this file, but if you are porting to a new operating system, these script programs may not recognize your --host settings.
The --host and --build switches take a system architecture specifications in the form: CPU-VENDOR-OS. For example: i386-pc-linux, or, powerpc-wrs-vxworks. The host system is the target system that will eventually run Appweb. The build system is the system being used to compile and build Appweb. The config.sub program takes an abbreviated system string and emits a fully qualified architecture specification. The config.guess program attempts to sleuth your build string.
You may need to define new MPR_CPU constants in the mpr/mpr.h file if you are doing a port to a new CPU architecture that is not already supported. You also may need to edit build/bin/config.guess. This program is run by configure to parse the --host and --build configuration values.
-
Prepare configure for the new target operating system.
If you create porting to a new unsupported operating system, you will need to create a new configure template in the "build/config" directory. The configure templates supply the default values for various configuration options including file extensions and system directories.
You may also need to modify the component search scripts in build/components. These scripts are run by configure to scan your system for supported components. Configure will load the "build/env.config", "build/standard.defaults" and "build/product.config" files. These have key parameters used by configure. You may need to modify these files.
-
Run configure for the new target operating system.
When ready, run configure to generate the buildConfig.make, buildConfig.sh and buildConfig.h master build files. For example:
./configure --disable-all --host=powerpc-wrs-vxworks
After running configure, check the output in build/buildConfig.make. If your system is UNIX like or windows like, you may need to edit the parseSystemConfiguration function in the configure script and add a new definition for your O/S. This function controls the UNIX_LIKE and WIN_LIKE defines.
-
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 operating system specific 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.
-
Tailor the Make directives file: make.os.NEWOS
This step is probably one of the longest. You need to edit the build/make/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.
-
Tailor the cross-platform O/S header.
To insulate most of the Appweb source code from the differences of various operating systems, the include/mpr.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 mpr.h, start by copying the sections in mpr.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. It is better to isolate the code for each O/S.
NOTE: the mpr.h and mprLib.c files are an all-in-one amalgamation of lots of smaller mpr files. When you have finished your port, the changes to mpr.h and mprLib.c will need to be back-ported to the Mpr release at https://github.com/embedthis/mpr-r.
-
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. You will probably need to modify the mprLib.c file.
In it, you will see banners marking where the various sub-files have been catenated together. The main sections to modify will be mprOs.c, mprSocket.c, mprThread.c mprTime.c and mprWait.c. The mprThread.c file contains the multiprocessing thread, lock and condition variable code. If you only intend to support single-threading, you can largely skip these code sections.
When you have finished your port, the changes to mprLib.c and mprLib.c will need to be back-ported to the Mpr release at https://github.com/embedthis/mpr-3.
-
Test the Make Subsystem
To aid the porting to many operating systems, a simple build system that is somewhat compatible with GNU configuration standards is provided. While the GNU Autoconf/Libtool system could arguably do the job, it struggles in non-Unix environments and lacks control for some cross-compilation scenarios. 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 require 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 top level objects directory (./obj). 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 src/mpr make
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, mprLib.c and make.rules for your O/S.
-
Compile the Reset
The rest of the code should compile and build easily. It is quite cross-platform.
cd src make clean depend compile test
-
Test Appweb
cd test make test
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 all the best. Please give feedback to the development team at dev@embedthis.com.