Building AppWeb From Source Code

This document contains a description of the build process to rebuild AppWeb on a supported platform using the AppWeb source code package. Additional instructions apply to building the source code from the Subversion source code repository. If you are wanting to port AppWeb to a new platform, please read Porting AppWeb.

For the product release notes and a detailed description of the installation procedure, please consult the Release Notes supplied with this release.


The appWeb source distribution contains all the necessary source files, headers, tools and test framework to reconfigure, build and verify the Mbedthis AppWeb Server. See Key Files below for a list of the important directories and files and their purposes.

Supported Platforms

A variety of build environments are supported on various platforms:


  • GNU C/C++, GNU make


  • Microsoft Visual Studio 6.0 (service pack 5) or Microsoft Visual Studio.NET 2003
  • GNU make via Cygwin using the Visual Studio compiler
On Windows, you can build using the supplied Visual Studio project files to build AppWeb in its default configuration. If you wish to modify the selected features or modules, you will need to use the Cygwin based development environment.

The source has been ported to Linux, Microsoft Windows, Solaris and the MAC. It has been tested under Fedora Linux based on the Linux 2.6 Kernel, Red Hat Linux 9.0 using the 2.4 Kernel and Microsoft Windows XP. Both single and multi-cpu systems are supported. Mbedthis AppWeb is quite portable and you are welcome to try your hand at porting it to a new platform. See the Porting Guide for more details.

Setup the Environment

On UNIX, you will need to setup your environment if you wish to debug programs locally in your build tree. If you only wish to build and install without running in the build tree, you do not need to modify your environment.

Set the LD_LIBRARY_PATH environment variable to include the bin directory in the source directory. This overrides the library search path compiled into the various AppWeb executables which is normally set to the build prefix (/etc/appWeb).

LD_LIBRARY_PATH has a format similar to PATH and can be set via the command:


This command may vary if you specify a non-default source installation directory, but normally this is location is:


If you have installed AppWeb in a non-default location, replace the path with the current installation directory for the source. You may wish to include these commands in your .profile or .bashrc login script to the environment is correctly setup each time you login.

Configuring the Build

If you are using Linux or the GNU/Cygwin tools on Windows, you have the options of configuring and controlling the build process via the configure script. This script is similar to the Linux autoconf and libtools configure programs. We do not use the GNU tools as we support operating systems that do not easily run them (e.g. Windows). The configure script will create and modify the build control files config.make, and config.h. These "magic" files are included by make files, shell scripts and also by C/C++ source files to control the build process.

If you are using Windows Visual Studio, you will need to manually edit the *.config configuration files if you wish to modify the configuration defaults. NOTE: this should not be necessary unless you wish to customize the feature set. If you are using Microsoft Visual Studio please see the Hand Editing section at the end of these notes. Also note that if you are building using the supplied Microsoft Visual Studio project files, some configuration options are restricted such as the ability to create statically linked libraries and executables.

Running Configure

The "configure" program is the master AppWeb configuration tool. It is a script that will create/modify the AppWeb configuration files that control the build settings. You may run configure with no options to accept the "factory" defaults, which is a good starting point.

Configure will remember the settings each time it is run in a conf/config.cache file and it will reuse these settings if a feature or option is not explicitly mentioned on the next invocation.

To run the configure program, type:


or supply options, for example:

configure --type=RELEASE --enable-shared --os=LINUX \
--disable-access-log --without-egi --with-esp

If you wish to cross-compile (Canadian-cross), configure will also listen to the settings of the AR, CC, CC_FOR_BUILD, LD, LD_FOR_BUILD, RANLIB, CFLAGS, IFLAGS and LDFLAGS environment variables and will pass their values into the build system. You can define the architecture of the hosting system via the --host switch.

The configure program will use the default values supplied in the conf/config.default file when first configuring your build. After running, it will save the current configuration in the config/config.cache file and will save the command line used to invoke configure in the config/config.args file. You can edit the config.default file to modify the defaults to suit your requirements. Once modified, run configure --reset to reparse the defaults file and update your configuration.

The tables below describe the configuration program options and the variables defined in the config.make configuration files. The defaults below are the defaults in the supplied binary distribution.

Installation Directory Options

Set the installation directory path for the primary product distribution files.
Set the installation directory path for the product manual documentation.
Set the installation directory path for the include header files.
Set the installation directory path for the libraries.
Set the installation directory path for system binaries.
Set the installation directory path for source code.
Set the installation directory path for web documents (DocumentRoot).

System Build Types

Configure for building on the system specified by "cpu-vendor-os". This value is guessed by default.
Cross-compile to run the product on the system specified by "cpu-vendor-os". This value is set by default to the value selected for the build host (see above).

Basic Configure Options

Set the build number part of the version (the last digit of a version number, e.g. 1.0.0-X).
Set the file name of the defaults master file in conf/appWeb. Just supply the bare filename without the .defaults extension.
Display the usage help.
Set the full product multi-word product name (BLD_NAME define).
Set the default HTTP port to listen on.
Set the one word (no spaces) name of the product (BLD_PRODUCT).
--quiet, -q, --silent
Run quietly.
Reset all values to their factory default settings.
Set the version number of the AppWeb shared library (Should not need to change).
Set the version number of the AppWeb product.
Set the default SSL port to listen on.
Set the build type (DEBUG | RELEASE)
Set the product version number (Major.Minor.Patch)

Feature Options


Do not include the FEATURE. This is the general form to enable the features described below.

Include the FEATURE. This is the general form to enable the features described below.
Enable logging of HTTP requests into the AppWeb access log
Build with debug assert checking on. This will slow AppWeb somewhat.
Build with the ability to parse the Apache-style configuration files used by AppWeb.
Build with cooking handling support.
Build with Digest authentication support.
Build with the Mbedthis fast memory allocator. About 5% faster than standard implementations.
Build with the HTTP If-Modified checking. Only return documents to the browser if they have been modified.
Build with the HTTP Keep-Alive support.
Build with the AppWeb trace log facility. Use the "-l" appWeb switch to enable at run-time.
Build with the ability to load AppWeb dynamic modules.
Build AppWeb multi-threaded. Use --disable-multi-thread to build single-threaded.
Build with the ability to load web pages from a compiled web page store in ROM.
Build with the ability to run as a system service or daemon.
Enforce the use of safe string handling routines (ie. prevent sprintf and other unsafe routines)
Build with HTTP session support.
Build a shared AppWeb library and program using shared libraries. Can be used with --enable-static to also build static versions.
Link with the shared version of the system libc library. This must be enabled if using glibc as it cannot statically link when using routines from the NSS library as AppWeb does. uClibc does not suffer from this limitation.
Build in squeeze mode for a minimal memory footprint.
Build a static AppWeb library and program using static libraries. Can also be used with --enable-shared to build shared versions.

Optional Modules and Handlers


Include the MODULE when building AppWeb. The MODULEs are described below.

Do not include the MODULE when building AppWeb.
Include the administration handler. This is for debug purposes and creates security risks. It should not be loaded in a production server.
Include the authorization handler.
Include the C API. Only necessary if creating or loading modules that use the C API.
Include the CGI handler.
Include GoAhead WebServer API compatibility. Only needed if migrating applications from the GoAhead WebServer.
Include support for the copy handler. This is the default document handler that will copy a files contents back to the client browser.
Include support for the Embedded Gateway Interface (EGI). This is a more modern replacement for CGI. In most cases the ESP handler is a better option.
Include support for the Embedded Server Pages (ESP) module.
Include support for the SSL protocol. You also need to define an SSL provider such as Openssl.
Include support for the file upload handler.
Include support for the Xml Database. (Not yet supported).

Optional Packages

--with-PACKAGE=[builtin, | module]

Specify if a PACKAGE should be included in the build. The package may be either built-into the AppWeb images using static linking and/or it may be built as a module. Normally you should choose either builtin or module.

Do not include the PACKAGE in the build.

Set the source directory for the PACKAGE.

Set a list of libraries to use when linking with the PACKAGE.
--with-php4=[builtin, | module]
Build with the PHP4 package. The source distribution default is disabled.
--with-php5=[builtin, | module]
Build with the PHP5 package. The source distribution default is disabled.
--with-openssl=[builtin, | module]
Build with the Openssl package. The source distribution default is disabled.

Environment Variables

These environment variables can be passed into configure to alter its behavior.

Path to the archiver program to use to archive libraries for the target system.
Path to the C/C++ compiler to use to compile for the target system.
Path to the C/C++ compiler to use for building bootstrap tools on the local system.
Path to the linker program to use to link objects for the target system.
Path to the ranlib program to use if required.
Compiler flags
Preprocessor and include flags. E.g. -Idir to specify a non-standard directory for include headers.
Linker flags. E.g. -Ldir to specify a non-standard directory for libraries.
Path on Unix to find shared libraries to override the compiled in search path. Normally set to the AppWeb bin directory when running appWeb locally in the source tree. This variable can be used anytime, not just to control the configure program.

Example Use

configure --type=DEBUG --enable-multi-thread --enable-shared \
--with-php4 --with-php4-dir=/usr/src/php-4.3.6 \
--with-php4-libs="php4 crypt resolv db z"


Basic Product Configuration Variables

The configure program will modify the following variables in the relevant config.* and config.h configuration files.

Typical Value
ar (lib on windows)
Archiver / library program.
The value of the CFLAGS environment variable when configure was run.
cc (cl on windows)
C/C++ compiler.
cc (cl on windows)
C/C++ compiler to use when building bootstrap tools that are used in the build process.
Name of the company distributing the product. You may change this.
Target CPU. Possible values defined in mpr/mprOs.h.
Set to 1 if BLD_TYPE is set to DEBUG.
Default product documentation and samples installation prefix.
The value of the IFLAGS environment variable when configure was run.
Default product header location.
The default HTTP port to listen on.
ld (link on windows)
Linker program.
The value of the LDFLAGS environment variable when configure was run.
Default product shared library location.
"Mbedthis AppWeb"
Multiword name of the product.
Build version number. This is the fourth digit of a version number.
Default installation directory prefix.
One word name of the product.
Library symbol table index rebuild.
Default location for product system binaries.
Default product documentation and samples installation prefix.
The default SSL port to listen on.
Build type. Set to RELEASE or DEBUG.
Set to TRUE if the target O/S is UNIX-like.
Version number of the format Major.Minor.Patch
Default web document root.
0 or 1
Enable or disable the feature by NAME.
0 or 1
Enable the building of the module by NAME.
0 or 1
Statically link the module into AppWeb.
0 or 1
Build the module as a dynamically loadable module.


Building on Linux

Once the build configuration is complete, you may proceed to build the source code by typing:

  1. make
Other make targets of interest are:
  1. make clean

  2. make depend

  3. make compile

  4. make test

  5. make install

  6. make uninstall

To understand more about the make system, read about the AppWeb make system below.

Building on Windows

For Windows, Mbedthis AppWeb is supplied with both Visual Studio 6.0 project files and a Cygwin configure/make build system identical to the LINUX/UNIX build system. The Visual Studio project files provide a simple, fixed way of building AppWeb. However, you cannot modify the build configuration. The Cygwin build system offers complete control over the configuration via the supplied configure command.

Building with Visual Studio

AppWeb includes several Visual Studio 6.0 project files for building various sections of the AppWeb server. These can also be read and upgraded by Visual Studio.NET.

appWebServer Builds all files necessary for the appWeb program. Includes building all loadable modules.
appWebClient Builds the HTTP client.
appWebUtils Builds various utilities.

To build using Visual Studio 6 open the workspace files located in the visualStudio directory with a "dsw" extension. To build using Visual Studio.NET, open the workspace files and upgrade them to Visual Studio.NET solution files.

The appWebServer project will build a the appWeb server program..

Building on Windows with Cygwin

Cygwin is a Linux-like environment for Windows. It provides a complete set of GNU utilities such that the procedure for building AppWeb with Cygwin is the same as the Linux procedure described above. Also read the Running Configure section.

Key Files and Directories

The Mbedthis AppWeb source tree contains the following key directories under the top directory.

appWeb   The main directory for the AppWeb main programs
  test Integration tests for AppWeb
  web HTML files used by appWeb

AppWeb samples written in C++

AppWeb samples written in C
bin   Directory to hold generated executables and DLLs (shared libraries). Windows will have Debug and Release subdirectories.

Bootstrap tools used in the build process

Essential configuration files and Makefile rules
doc   AppWeb documentation
ejs   Embedded JavaScript Engine for AppWeb
  test Unit tests for EJS
http   The core HTTP web server for AppWeb
  modules Dynamically loadable modules and handlers. Also used for statically linked modules.
  test Unit tests for the http server
  utils Utility programs: httpComp, httpPassword
mpr   The Mbedthis Portable Runtime (MPR) that provides a cross-platform executive for AppWeb to use
  UNIX UNIX dependent files for Linux, Solaris and other UNIX like operating systems.
  samples MPR sample files
  test Unit tests for the MPR
  WIN Windows dependent files

Directory to hold generated objects. Windows will have Debug and Release subdirectories.

Microsoft Visual Studio workspace files

Key Build Files

Key make settings for a given operating system. This is a copy of the master file conf/make.os.OS.
make.rules Key make targets and rules for all make files. This is a copy of the relevant make.rules.OS file from the conf directory.
config.make Build configuration file created by configure and used by Make.
Build configuration file created by configure and used by shell scripts including the bld program.
Build header created by configure and included in all source files.
configure Build configuration program.
bin/bld Program to create executables and libraries (like GNU/libtool).
Configuration defaults for AppWeb for each operating system. Configure uses these defaults when first run and when the --reset switch is used to reset to factory defaults.
Used only when initializing a source tree for the first time after checking out from the Mbedthis Subversion source code repository. This file is not included in the source distribution but is included in the Subversion repository.
Cache of the current settings in effect for configure. Configure will reuse the last settings as a base.

Hand Editing Configuration Files

For Microsoft Visual Studio users who wish to customize the features of the AppWeb server, you will need to edit the config.make, and config.h header files. Key constants and settings are defined here and these files are included by C source, Makefiles and scripts. Many constants are repeated in two or three of the configuration files so be very careful and make sure you change each setting in every place it is mentioned. You must maintain consistency between the files. When editing be very careful to preserve quotes where they appear.

topThe Make System

AppWeb uses a highly customized build system using the standard GNU make system. Its purpose is to allow fine-grained control over the features that are enabled in the product and what modules are included, to minimize the code required in each makefile and to be cross-platform. The make system will run on any system supporting the GNU make and GNU bash shell programs. For the Windows environment, the build system relies on the CYGWIN Unix emulation layer. Alternatively, Microsoft Visual Studio project files that are generated from the Makefiles, may be used.

The make system supports recursive compilation and building where each directory contains a Makefile. Typically, each makefile includes a dependency file called make.dep. This file is contains target dependencies and also references the primary configuration file (config.make) generated by the configure program. It also includes the make rules that are defined in the make.rules file which resides in the top directory of the source tree and make.os which contains per O/S make variables and transition rules.

Standard Make Targets

The make system supports the following targets and all except build, operate recursively applying the same target to all defined subdirectories. The directories recursed are specified in the PRE_DIRS and POST_DIRS make variables.

Perform a make clean compile test
Remove intermediate and generated targets
Compile source files
Create the make.dep dependency file
Create a rom file system image of the distribution. Used by uClinux.
Make VisualStudio project files
Create an installable distribution package
Run unit tests

An AppWeb Makefile looks similar to this example:
COMPILE         := *.cpp
POST_DIRS := test

include make.dep

compileExtra: myLib$(BLD_ARCHIVE) myProg$(BLD_EXE)

@bld --static --library myLib$(BLD_ARCHIVE) file$(BLD_OBJ)

myProg$(BLD_EXE): $(FILES)
@bld --executable myProg$(BLD_EXE) file$(BLD_OBJ)

The top section defines environment variables that control make for this and subdirectories. The following table describes the possible make variables supported by AppWeb.

User Make Variables

Typical Value

Any local compiler flags.
List of files to be compiled. Can contain wild cards.
True / false value if compiled objects must be sharable. On some systems, this implies position independent code. This only has effect if BLD_FEATURE_SHARED is true. See "configure --enable-shared"
Export objects into a common object directory, typically BLD_TOP/obj.

Any local include flags.

Any local link flags.

List of directories to be recursed before making the current directory.

List of directories to be recursed after making the current directory.

The make.dep file is generated by invoking "make depend" which will run the genDepend program to parse the source files and generate the file dependency lists. For the first time build, the command makedep will generate stub make.dep files. A typical make.dep file looks like the following:

all: compile

BLD_TOP := ../..

# Read the build configuration settings and make
# variable definitions.
include $(BLD_TOP)/config.make

$(BLD_OBJ_DIR)/mprSample$(BLD_OBJ) \

$(BLD_OBJ_DIR)/mprSample$(BLD_OBJ): \
../../mpr/mpr.h \
../../config.h \
../../mpr/mprOs.h \

$(BLD_OBJ_DIR)/mprWinSample$(BLD_OBJ): \
../../mpr/mpr.h \
../../mpr/mprOs.h \

# Read the Makefile rules
include $(BLD_TOP)/make.rules
include $(BLD_TOP)/make.os

The BLD_TOP variable defines the top of the source tree and the FILES variable lists all files to be compiled. Two files are included. The first, config.make, is generated by the configure program and contains the configuration settings for this build. The make.rules file contains the AppWeb make rules for this operating system. You should not hand edit the make.dep files. All changes should go into the Makefile.

Supplimentary Make Variables

Top level directory in the source tree.
Used only by the top level makefile to check that the environment has been correctly setup.
List of target objects to build. This is created by the genDepnd program which is run when "make depend" is invoked. It consults the variable COMPILE and creates the FILES list.

Config.make Variables

The following variables are used by config.make. To ensure the entire source tree is relocatable, all paths are always paths relative to the top of the source tree. Don't use absolute paths.

Typical Value (Linux)
File extension for static libraries.
Directory to hold executable and libraries.
The value of the CFLAGS environment variable when configure was run.
File extension for Java classes.
(.exe on Windows)
File extension for executables.
Common directory to hold exported objects.
The value of the IFLAGS environment variable when configure was run.
Include directory.
The value of the LDFLAGS environment variable when configure was run.
Convenience variable set to either "Static${BLD_ARCHIVE}" or ${BLD_SHOBJ}
File extension for objects.
Directory to hold objects. May be "." if EXPORT_OBJECTS is not defined.
File extension for position independent objects.
(.lib on windows)
Shared library extension when shared objects and shared libraries are separate files.
File extension for shared objects.
Directory to hold build tools.

The bld Program

The bld program is used to create executables, static libraries and shared libraries. It provides a cross-platform interface that requires minimal typing in makefiles and is controlled by the per-O/S make.rules make include file.

These make variabls are defined in the make.rules file and are passed to the bld program.

Set to either _LD_OPT_DEBUG or _LD_OPT_RELEASE depending whether the build is Debug or Release.
Link options when building a Debug version.
Link options when building a Release version.
Link flag when building a DLL (shared library).
Set to either _CC_OPT_DEBUG or _CC_OPT_RELEASE depending whether the build is Debug or Release.
Compiler options when building a Debug version.
Compiler options when building a Release version.
General compiler flags.
General compiler include flags.
General linker flags.
Standard libraries to use when building bootstrap tools that must be compiled natively.
Compiler warning control flags.
Standard shared libraries to use in every shared link.
Standard static libraries to use in every static link.
Path to directory containing libraries.

Bld Program Switches

In addition to the environment variables defined in the file, the bld program takes the following command line switches:

Not implemented
Trace commands but do not execute
--entry NAME
Shared library entry point
--executable NAME
Name of executable to build
Create a windowed program instead of a console program (Windows only)
Print usage information
--library NAME
Name of library to link
--libs "LIBRARIES ..."
Extra libraries to link with
--libraryPath "PATHS..."
Paths to search for the libraries
Build for local execution not for execution on the target system
--objects "OBJECTS ..."
String containing list of objects to link
--objectsList FILE
File containing list of objects to link
--objectsDir PATH
Directory to find / store objects
Run quietly without tracing actions to stdout
Link with shared libraries by preference
Link with static libraries by preference
--resources FILE
Resource file (menus and icons for Windows)
--rpath PATH
Specify the executable run-time library search path (Unix only)
Only make a shared library
Create a versioned shared library with a SONAME
Only make a static library
--smartLibs "LIBRARIES ..."
Use shared or static libraries intelligently depending on --preferShared, --preferStatic, BLD_FEATURE_STATIC and BLD_FEATURE_SHARED
Print the bld version number.

The bld program also uses the following environment variables:

Top of the source tree. This is automatically set by the genDepend program in the make.dep files.
Build shared libraries where relevant. This is defined by the configure --enable-shared switch.
Build static libraries where relevant. This is defined by the configure --enable-static switch.

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