Building Appweb From Source Code

This document describes the configuration and build procedure to rebuild Appweb using the Appweb source code. The appweb source distribution contains all the necessary source files, headers, tools and test framework to reconfigure and build the Mbedthis Appweb Server. See Key Files below for a list of the important directories and files and their purposes.

For the product release notes and a detailed description of the installation procedure, please consult the Release Notes supplied with this release. The INSTALL.TXT file may also provide additional material - though is substantially similar to this document.

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.

Supported Platforms

A variety of build environments are supported on various platforms:

Linux

  • Linux 2.4, 2.6 with GNU C/C++, GNU make. (See cross-compilation below if using uClinux)

MAC OS X

  • Mac OS X 10.1 or later with GNU C/C++, GNU make.

Windows

  • Microsoft Windows XP or Windows Vista with Visual Studio 6.0 (service pack 5) or Microsoft Visual Studio 2005.

VxWorks

  • Wind River Tornado II and VxWorks 5.4 (See cross-compilation below) or Wind River Workbench 6.3.

summary Overview

The build procedure is substantially the same for all supported platforms. A configure program is first used to select the target host, required features, options and modules. Then the make program is used to build Appweb.

On Windows and when doing cross-development on a Windows system, you need the Cygwin UNIX emulation development tools. These provide UNIX like commands for Windows and provides a consistent development environment on Windows and Unix/Linux. Building on windows is performed using the Microsoft C compiler and the GNU make and shell utilities. Microsoft Visual Studio may be used for debugging, but building is performed using make.

The Appweb source code has been ported to BSD, Linux, MAC OSX, Solaris, Windows and VxWorks. It has been thoroughly tested using the following O/S distributions: Ubuntu Linux, Fedora Linux, MAC OS X 10.1, Red Hat Linux 9.0 using the 2.4 Kernel, Microsoft Windows XP, Windows Vista and VxWorks 5.4 and 6.3. 

Many CPU architectures are supporting including single and multi-cpu systems. You will find that 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 for Building

Linux, Unix and MAC OS

If you wish to debug programs locally in your build tree, you will need to modify your environment to define the LD_LIBRARY_PATH variable so that Appweb programs can locate the dynamically loadable modules and libraries. If you only wish to build and install without running in the build tree, you do not need to modify your environment. If you are using MAC OS, then you need to use the corresponding variable: DYLD_LIBRARY_PATH.

Set the LD_LIBRARY_PATH environment variable to include the lib and lib/modules directories in the source directory. This overrides the default 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:

export LD_LIBRARY_PATH=/usr/src/appweb-VERSION/lib:/usr/src/appweb-VERSION/lib/modules:$LD_LIBRARY_PATH

Where /usr/src/appweb-VERSION is the path to your installed appweb source distribution. 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.

Windows

If you are building for Windows or using Windows for cross development, you need to define certain Microsoft compiler environment variables as described in the Microsoft installation procedure. These variables are the PATH, INCLUDE and LIB variables so that they will contain references to the where the Microsoft compiler and libraries are installed on your system. Consult your Microsoft Visual Studio documentation for details.

You will also need to download Cygwin tools from www.cygwin.com. These tools provide a Unix like environment for building Appweb. When building, you need to invoke make from within a Cygwin command window called a bash window. The bash command is the command shell, similar to the Windows dos command window.

Configuring the Build

Before building, you must first configure what settings you require for Appweb. To do this, you run the configure command. If you are familiar with the open source autoconf configure program, you will feel at home.

The configure program will use the default configuration supplied in the build/standard.defaults file when first configuring your build. You can edit the standard.defaults file to modify the settings to suit your requirements. The configure script will create and modify the build control files buildConfig.make, buildConfig.sh and buildConfig.h. These configuration files are included by make files, shell scripts and also by C/C++ source files to control the build process.

Running Configure

The "configure" program is the master Appweb configuration tool. You may run configure with no options to accept the "factory" defaults, which is a good starting point.

To run the configure program, type:

./configure

or supply options, for example:

./configure --type=RELEASE --enable-shared \
--disable-access-log --without-egi --with-esp=loadable

Cross Compilation

To configure for cross compilation must specify the --host and --build switches. 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. These take system architecture specifications are in the form: CPU-VENDOR-OS. For example:

i386-pc-linux

or

powerpc-wrs-vxworks

Use x86_64 for the CPU component to select Intel/AMD 64 bit. If you don't specify the build system using the --build switch, configure will do its best to guess your current system configuration. Here is a typical cross-compilation example that builds on a windows PC and targets VxWorks on a Power PC cpu.

./configure --host powerpc-wrs-vxworks --build pentium-pc-windows

Discovery Methods for Tools and SDKs

To build Appweb, many tools are required. These include a compiler, linker and other utilies such as: nm and strip. Some operating systems require entire SDKs such as VxWorks. Once located, configure define constants in buildConfig.* for all tools and SDKs.

The configure program has two differnet methods to locate the required tools and SDKs to build apweb.

  1. Auto tool discovery
  2. Explicit tool paths

The first method is to let Appweb discover the tools by searching the system according to defined search paths. This is the simplest and quickest way to configure Appweb.

The second method is usually only used when cross compiling. In this method, you supply explicit paths for required tools via environment variables.

Auto Tool Discovery

The configure program can auto-discover most required tools and SDKs. Appweb comes pre-configured with the typical install locations of all the required tools and SDKs. To use auto-discovery, just type configure:
./configure

And let configure do the rest. In the rare case where you have tools installed in atypical locations, you can modify the build/tools.config file to add custom directories to the pre-configured search paths so configure can find the a specific tools or SDK.

Required and Optional Tools

The set of required tools is described by the BLD_REQUIRED_TOOLS, BLD_OPTIONAL_TOOLS, BLD_REQUIRED_SDKS and BLD_OPTIONAL_SDKS variables in the build/product.config file. The tool names are symbolic names. For example:

BLD_REQUIRED_TOOLS="AR CC LD DOXYGEN"

These upper case tool names are translated into O/S specific tool names by the build/os/config.* files. For example, BLD_HOST_CC will be defined as "cc" in build/os/config.MACOSX. Once translated, configure will search for this tool in the tool search paths.

Directory Search Order

Configure will search for for tools in a preset order. It will search the SEARCH_PATH environment variable first, then the TOOL_SEARCH_PATH (or BUILD_TOOL_SEARCH_PATH if making local build tools) defined in build/tools.config and finally the PATH environment variable. Normally the SEARCH_PATH variable is not defined. Its purpose is to allow user overrides of the search paths without having to edit build/tools.config by supplying search paths in the enviroment. For example:
SEARCH_PATH=/usr/src/myTools ./configure

This will search for tools first under the /usr/src/myTools directory. If a given tool is not found, the relevant TOOL_SEARCH_PATH and the directories contained in PATH will be searched in turn.

The configure program can auto-discover most required tools and SDKs. The build/tools.config file contains pre-configured search paths so configure can find tools and SDKs required to build Appweb. You may edit build/tools.config and add custom directories if you require.

The build/tools.config file can be customized to define new directories or modify directories as required for your system. The default search paths for tools is defined as:

TOOL_SEARCH_PATH="
'\$BLD_HOST_VXWORKS/gnu/*/\$BLD_BUILD_SYSTEM_VX/bin'
'\$BLD_HOST_VXWORKS/gnu/*/\$BLD_BUILD_SYSTEM_VX/\$BLD_HOST_SYSTEM/bin'
'\$BLD_HOST_VXWORKS/\$BLD_HOST_DIST-\$BLD_HOST_DIST_VER/host/\$BLD_BUILD_SYSTEM_VX/bin'
'\$BLD_HOST_VXWORKS/\$BLD_HOST_DIST-\$BLD_HOST_DIST_VER/host/resource/hutils/tcl'
'\$BLD_HOST_VXWORKS/workbench*/foundation/*/\$BLD_BUILD_SYSTEM_VX/bin'
'\$BLD_HOST_VXWORKS/host/*/bin'
'\$BLD_HOST_VXWORKS/host/*/\$BLD_HOST_SYSTEM/bin'
'/cygdrive/*/Program Files/Microsoft Visual Studio*/*/bin'
'/cygdrive/*/Program Files/java/jdk*/bin'
'/cygdrive/*/Program Files/Inno*'
'/cygdrive/*/j2sdk*/bin'
'/Program Files/Microsoft Visual Studio*/*/bin'
'/Program Files/java/jdk*/bin'
'/Program Files/Inno*'
'/j2sdk*/bin'
'/usr/java/latest/bin'
'/usr/lib/jdk*/bin'
'/usr/local/jdk*/bin'
'/bin'
'/usr/bin'
'/usr/local/bin'
'.'
"

Each line describes a set of directories to search for tools. Lines must be within single quotes and may use "*' as a wildcard to match multiple directories.

Explicit Tool Paths

When cross-compiling, it is often convenient to supply explicit paths for tools via environment variables. Using this configuration method, you tell configure about the names of your compiler, library archiver and other utilities via explicit environment variables. The configure program listens to the environment variable settings of the AR, CC, LD, MUNCH, NM, RANLIB, STRIP, TCLSH, CFLAGS, IFLAGS and LDFLAGS environment variables and will pass their values into the build system. Not all these variables are required on all operating systems. MUNCH and TCLSH are only required when targetting VxWorks. By default, these variables are used for the compiler and linker when building for the host system, whereas variants with a "BUILD" prefix apply to the local build system. For excample:

CC=/usr/local/bin/cc386       # This will be used for the host system
BUILD_CC=/usr/bin/cc          # This will be used for the local build system


Environment Variables

When cross compiling, it is usually necessary to define various cross compiler tool chain settings via environment variables. These environment variables are typically passed into configure to alter its behavior. For example:

CC=/mypath/mycc ./configure

The following table lists the possible environment variables.

Variable
Description
AR
Path to the archiver program to use to archive libraries for the target system.
BUILD_CCPath to the C/C++ compiler to use for building tools required for building on the local development system.
BUILD_LDPath to the C/C++ compiler to use for building tools required for building on the local development system.
CC
Path to the C/C++ compiler to use to compile for the target system.
LD
Path to the linker program to use to link objects for the target system.
MT Path to the windows manifest program.
NM Path to the nm program to extract symbols from objects.
RANLIB
Path to the ranlib program to use if required.
STRIP Path to command to strip symbols from libraries.
CFLAGS
Compiler flags
IFLAGS
Preprocessor and include flags. E.g. -Idir to specify a non-standard directory for include headers.
LDFLAGS
Linker flags. E.g. -Ldir to specify a non-standard directory for libraries.
LD_LIBRARY_PATH
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. Use DYLD_LIBRARY_PATH on MAC OS X.

Example Use

CC=/tornado/host/x86-win32/bin/cc386 \
LD=/tornado/host/x868-win32/bin/ld3868 configure

Configure Command Line Options

The following command lines options are supported by the configure program. The tables below describe the configuration program options and the variables defined in the buildConfig.make configuration files. The defaults below are the defaults in the supplied binary distribution.

Installation Directory Options

Option
Description
--prefix
Set the installation directory path for the primary product distribution files.
--docDir=PATH
Set the installation directory path for the product manual documentation.
--incDir=PATH
Set the installation directory path for the include header files.
--libDir=PATH
Set the installation directory path for the libraries.
--sbinDir=PATH
Set the installation directory path for system binaries.
--srcDir=PATH
Set the installation directory path for source code.
--webDir=PATH
Set the installation directory path for web documents (DocumentRoot).


System Build Types

Option
Description
--build=cpu-vendor-os
Configure for building on the system specified by "cpu-vendor-os". This value is guessed by default.
--host=cpu-vendor-os
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

Option
Description
--buildNumber=NUMBER
Set the build number part of the version (the last digit of a version number, e.g. 1.0.0-X).
--defaults=FILE
Set the file name of the default settings file. Supply the bare filename without the .defaults extension.
--help
Display the usage help.
--name=NAME
Set the full product multi-word product name (BLD_NAME define).
--port=PORT
Set the default HTTP port to listen on.
--product=NAME
Set the one word (no spaces) name of the product (BLD_PRODUCT).
--quiet, -q, --silent
Run quietly.
--reset
Reset all values to their factory default settings.
--setLibVersion
Set the shared library version number of the Appweb shared library (Should not need to change).
--setVersion
Set the version number of the Appweb product.
--sslPort=PORT
Set the default SSL port to listen on.
--type=BUILD
Set the build type (DEBUG | RELEASE)
--version=X.Y.Z
Set the product version number (Major.Minor.Patch)

Feature Options

Option
Default
Description
--disable-FEATURE

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

Include the FEATURE. This is the general form to enable the features described below.
--enable-access-log
Enabled
Enable logging of HTTP requests into the Appweb access log
--enable-assert
Disabled
Build with debug assert checking on. This will slow Appweb somewhat.
--enable-c-api-clientEnabledBuidl with the HTTP client C language API.
--enable-config-parse
Enabled
Build with the ability to parse the Apache-style configuration files used by Appweb.
--enable-config-saveDisabledBuild with the ability to write out the Appweb configuration file.
--enable-cookie
Enabled
Build with cooking handling support.
--enable-digest-auth
Enabled
Build with Digest authentication support.
--enable-ejsEnabledInclude the EJScript language.
--enable-floating-pointEnabledInclude floating point support in EJScript.
--enable-if-modified
Enabled
Build with the HTTP If-Modified checking. Only return documents to the browser if they have been modified.
--enable-ipv6DisabledBuild with IPv6 support.
--enable-keep-alive
Enabled
Build with the HTTP Keep-Alive support.
--enable-legacy-apiDisabledBuild with legacy API support for backwards compatibility.
--enable-log
Enabled
Build with the Appweb trace log facility. Use the "-l" appweb switch to enable at run-time.
--enable-modules
Enabled
Build with the ability to load Appweb dynamic modules.
--enable-multi-thread
Enabled
Build Appweb multi-threaded. Use --disable-multi-thread to build single-threaded.
--enable-rom-fs
Disabled
Build with the ability to load web pages from a compiled web page store in ROM.
--enable-run-as-service
Enabled
Build with the ability to run as a system service or daemon.
--enable-safe-strings
Disabled
Enforce the use of safe string handling routines (ie. prevent sprintf and other unsafe routines)
--enable-session
Enabled
Build with HTTP session support.
--enable-shared
Enabled
Build a shared Appweb library and program using shared libraries. Can be used with --enable-static to also build static versions.
--enabled-shared-libc
Enabled
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.
--enable-squeeze
Disabled
Build in squeeze mode for a minimal memory footprint.
--enable-static
Enabled
Build a static Appweb library and program using static libraries. Can also be used with --enable-shared to build shared versions.
--enable-stdc++
--enable-stdcpp
DisabledBuild with the standard libc libstdc++ library instead of the builtin Appweb alternative. Results in bigger memory requirements if enabled.
--enable-testDisabledBuild with the test framework. (Requires SVN checkout)

Optional Modules and Handlers

Option
Default
Description
--with-MODULE

Include the MODULE when building Appweb. The MODULEs are described below.
--without-MODULE

Do not include the MODULE when building Appweb.
--with-admin
Enabled
Include the administration handler. This is for debug purposes and creates security risks. It should not be loaded in a production server.
--with-auth
Enabled
Include the authorization handler.
--with-c-api
Enabled
Include the C API. Only necessary if creating or loading modules that use the C API.
--with-cgi
Enabled
Include the CGI handler.
--with-copyEnabledInclude support for the copy handler. This is the default document handler that will copy a files contents back to the client browser.
--with-gacompat
Disabled
Include GoAhead WebServer API compatibility. Only needed if migrating applications from the GoAhead WebServer.
--with-egi
Enabled
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.
--with-esp
Enabled
Include support for the Embedded Server Pages (ESP) module.
--with-ssl
Enabled
Include support for the SSL protocol. You also need to define an SSL provider such as Openssl.
--with-upload
Disabled
Include support for the file upload handler.

Optional Packages

Use these switches for the php5, matrixssl and openssl packages.

Option
Description
--with-PACKAGE=[builtin, | loadable]
Specify if a PACKAGE should be included in the build. The package may be either built-into the Appweb images using static linking or it may be built as a loadable module. Normally you should choose either builtin or module.
--without-PACKAGE
Do not include the PACKAGE in the build.
--with-PACKAGE-dir=DIR
Set the source directory for the PACKAGE.
--with-PACKAGE-libpath=DIR Set the directory where the package places its built libraries. Usually some directory under the PACKAGE-dir directory.
--with-PACKAGE-libs=LIBRARIES
List of libraries to use when linking with the PACKAGE.
--with-PACKAGE-iflags="-Idir ...." Include flags to use when compiling
--with-PACKAGE-cflags="compile flags" Compiler flags to use when compiling
--with-PACKAGE-ldflags="link flags" Link flags to use when building the PACKAGE module. Only relevenat for loadable modules.
--with-matrixssl=[builtin, | module] Build with the MatrixSSL package. The source distribution default is disabled. Requires dir, libpath, libs, cflags, iflags and ldflags to be defined.
--with-php5=[builtin, | module]
Build with the PHP5 package. The source distribution default is disabled. Requires dir, libpath, libs, cflags, iflags and ldflags to be defined.
--with-openssl=[builtin, | module]
Build with the Openssl package. The source distribution default is disabled. Requires dir, libpath, libs, cflags, iflags and ldflags to be defined.

As an example. To build with PHP5, you will need to use a configure command similar to the following:

DIR=/Users/mob/svn/packages/php/php-5.2.0 ; \
./configure -with-php5=builtin --with-php5-dir=$DIR \
--with-php5-iflags="-I$DIR -I$DIR/main -I$DIR/Zend -I$$DIR/TSRM" \
--with-php5-libpath="$DIR/libs" --with-php5-libs="libphp5 crypt resolv db z

Build Variables (Reference)

The configure program will define the following variables (among others) in the relevant buildCconfig.* and buildConfig.h configuration files.

Variable
Typical Value
Description
BLD_BUILD_CC
cc (cl on windows)
C/C++ compiler to use when building bootstrap tools that are used in the build process.
BLD_BUILD_CPU_ARCH MPR_CPU_IX86 Build system CPU architecture. Possible values defined in mpr/mprOs.h.
BLD_BUILD_CPU
i586 Build system CPU. Possible values defined in conf/config.sub. Used in the --build switch to configure.
BLD_BUILD_LD
ld (link on windows)
Linker program to use when building bootstrap tools that are used in the build process.
BLD_BUILD_OS WIN Build system operating system. Used in cross-development.
BLD_COMPANY
"Mbedthis"
Name of the company distributing the product. You may change this.
BLD_DEBUG
1
Set to 1 if BLD_TYPE is set to DEBUG.
BLD_DOC_PREFIX
/usr/share/appweb-1.1.2
Default product documentation and samples installation prefix.
BLD_HOST_AR
ar (lib on windows)
Archiver / library program for target host.
BLD_HOST_CFLAGS
""
The value of the CFLAGS environment variable when configure was run. Used for compiling programs for the target host.
BLD_HOST_CC
cc (cl on windows)
C/C++ compiler for compiling programs for the target host.
BLD_HOST_CPU_ARCH MPR_CPU_IX86 Target host CPU architecture. Possible values defined in mpr/mprOs.h.
BLD_HOST_CPU
i586 Target host CPU. Possible values defined in conf/config.sub. Used in the --host switch to configure.
BLD_HOST_OS LINUX Target operating system.
BLD_HOST_UNIX
1
Set to TRUE if the target O/S is UNIX-like.
BLD_HTTP_PORT
80
The default HTTP port to listen on.
BLD_INC_PREFIX
/usr/include/appweb
Default product header location.
BLD_HOST_IFLAGS
""
The value of the IFLAGS environment variable when configure was run.
BLD_HOST_LD
ld (link on windows)
Linker program.
BLD_HOST_LDFLAGS
""
The value of the LDFLAGS environment variable when configure was run.
BLD_LIB_PREFIX
/usr/lib
Default product shared library location.
BLD_NAME
"Mbedthis Appweb"
Multiword name of the product.
BLD_NUMBER
1
Build version number. This is the fourth digit of a version number.
BLD_PREFIX
/etc/appweb
Default installation directory prefix.
BLD_PRODUCT
appweb
One word name of the product.
BLD_HOST_RANLIB
ranlib
Program to rebuild library symbol tables for the target host.
BLD_SBIN_PREFIX
/usr/sbin
Default location for product system binaries.
BLD_SRC_PREFIX
/usr/src/appweb-1.1.2
Default product documentation and samples installation prefix.
BLD_SSL_PORT
443
The default SSL port to listen on.
BLD_TYPE
DEBUG
Build type. Set to RELEASE or DEBUG.
BLD_VERSION
1.1.2
Version number of the format Major.Minor.Patch
BLD_WEB_PREFIX
/var/appweb/web
Default web document root.
BLD_FEATURE_NAME
0 or 1
Enable or disable the feature by NAME.
BLD_FEATURE_NAME_MODULE
0 or 1
Enable the building of the module by NAME.
BLD_FEATURE_NAME_MODULE_BUILTIN
0 or 1
Statically link the module into Appweb.
BLD_FEATURE_NAME_MODULE_LOADABLE
0 or 1
Build the module as a dynamically loadable module.

Building

Building from Source

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

 make        

This will first make the build bootstrap utilities and will then create the make dependencies before compiling the code. It achieves this by automatically doing the following command sequence:

  1. make clean

  2. make compile -C bootstrap

  3. make depend

  4. make compile

  5. make install

  6. make uninstall

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

Installing

You can install by typing "make install" and remove via "make uninstall". If you are installing to the default system locations for Appweb, you will need to login as root or attain root/administration privilege before running "make install".

You can also install other Appweb components by typing:

Command Description Configure Location Option
make install Install only the binaries (same as make install-binary) --prefix
make install-binary Install minimal binary files only to run Appweb --prefix --webDir
make install-dev Install the product documentation --libDir --incDir

make install-doc

Install the product documentation --docDir
make install-samples Install the samples --docDir
make install-src Install the source code --srcDir
make install-all Install everything except the source code ALL

You can remove the components by using make uninstall-ITEM. Where ITEM is one of the above components: binary, dev, doc, samples, src, or all.

You can selectively modify installation directories by setting the appropriate configure location option. For example:

./configure --prefix=/home/myDir --webDir=/www/html

If you want to install to a local directory before copying the installation to another system, you can rebase all the installation directories by setting the ROOT_DIR environment variable. This will prepend the ROOT_DIR to all the installation directories specified to configure. For example:

 make ROOT_DIR=/myDir install

This will copy the binary installation files to /myDir.

Building from the Source Code Repository

To get a latest copy of Appweb source code, you will need to have installed the Subversion source code control client. Subversion is similar to CVS, only better. Most major linux distributions now include the client. To download a copy, go to:

 http://subversion.tigris.org/

Once you have the Subversion client installed, you will need to send email to dev@mbedthis.com to receive a login name and password so you can access the repository. Once you have these details, you can checkout a copy of the Appweb source code via:

 svn checkout http://www.mbedthis.com/svn/appweb/main

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
samples



C++
Appweb samples written in C++

C
Appweb samples written in C
bin

Directory to hold generated executables

build

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
utils Utility programs: httpComp, httpPassword
lib Directory to hold generated libraries
modules Directory to hold dynamically loaded modules
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
test Unit tests for the MPR
WIN Windows dependent files
obj
obj Directory to hold generated objects. Windows will have Debug and Release subdirectories
tools
bootstrap
Bootstrap tools used in the build process


Key Build Files

build/os/config.*
Key configure settings for a given operating system.
build/make/make.os.* Makefile definitions for a given operating system.
build/make/make.rules Key make targets and rules for all make files.
buildConfig.make Build configuration file created by configure and used by Make.
buildConfig.sh
Build configuration file created by configure and used by shell scripts including the bld program.
buildConfig.h
Build header created by configure and included in all source files.
configure Build configuration program.
tools/bld Program to create executables and libraries (like GNU/libtool).
tools/makedep First time generation of dynamic dependency files (make.dep).

topThe Make System

Appweb uses a customized build system using the standard GNU make tools. Its goals are 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.

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 (buildConfig.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.

Target
Description
build
Perform a make clean compile test
clean
Remove intermediate and generated targets
compile
Compile source files
depend
Create the make.dep dependency file
romfs
Create a rom file system image of the distribution. Used in the appweb directory. Used by uClinux.
package
Create an installable distribution package
test
Run unit tests

An Appweb Makefile looks similar to this example:
COMPILE         := *.cpp
COMPILE_SHARED := yes
POST_DIRS := test
include make.dep
compileExtra: myLib$(BLD_ARCHIVE) myProg$(BLD_EXE)
myLib$(BLD_ARCHIVE): $(FILES)
@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

Variable
Typical Value
Description
MAKE_CFLAGS

Any local compiler flags.
COMPILE
*.cpp
List of files to be compiled. Can contain wild cards.
COMPILE_SHARED
yes
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
yes
Export objects into a common object directory, typically BLD_TOP/obj.
MAKE_IFLAGS

Any local include flags.
MAKE_LDFLAGS

Any local link flags.
PRE_DIRS

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

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)/buildConfig.make
FILES = \
$(BLD_OBJ_DIR)/mprSample$(BLD_OBJ) \
$(BLD_OBJ_DIR)/mprWinSample$(BLD_OBJ)

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

#
# Read the Makefile rules
#
include $(BLD_TOP)/build/make/make.rules
ifeq ($(BLD_NATIVE),1)
include $(BLD_TOP)/build/make/make.os.$(BLD_BUILD_OS)
else
include $(BLD_TOP)/build/make/make.os.$(BLD_HOST_OS)
endif


The BLD_TOP variable defines the top of the source tree and the FILES variable lists all files to be compiled. Three files are included. The first, buildConfig.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 any operating system. The make.os.$(BLD_HOST_OS) contains the rules for this operating system. You should not hand edit the make.dep files. All changes should go into the Makefile.

Supplimentary Make Variables

Variable
Description
BLD_TOP
Top level directory in the source tree.
BUILD_CHECK
Used only by the top level makefile to check that the environment has been correctly setup.
FILES
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.

buildConfig.make Variables

The following variables are used by buildConfig.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.

Variable
Typical Value (Linux)
Description
BLD_ARCHIVE
.a
File extension for static libraries.
BLD_BIN_DIR
${BLD_TOP}/bin
Directory to hold executable and libraries.
BLD_CFLAGS
""
The value of the CFLAGS environment variable when configure was run.
BLD_CLASS
.class
File extension for Java classes.
BLD_EXE
(.exe on Windows)
File extension for executables.
BLD_EXP_OBJ_DIR
${BLD_TOP}/obj
Common directory to hold exported objects.
BLD_IFLAGS
""
The value of the IFLAGS environment variable when configure was run.
BLD_INC_DIR
${BLD_TOP}/include
Include directory.
BLD_LDFLAGS
""
The value of the LDFLAGS environment variable when configure was run.
BLD_LIB
${BLD_TOP}/lib
Convenience variable set to either "Static${BLD_ARCHIVE}" or ${BLD_SHOBJ}
BLD_OBJ
.o
File extension for objects.
BLD_OBJ_DIR
${BLD_TOP}/obj
Directory to hold objects. May be "." if EXPORT_OBJECTS is not defined.
BLD_PIOBJ
.lo
File extension for position independent objects.
BLD_SHLIB
(.lib on windows)
Shared library extension when shared objects and shared libraries are separate files.
BLD_SHOBJ
.so
File extension for shared objects.
BLD_TOOLS_DIR
${BLD_TOP}/tools
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.

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

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

Bld Program Switches

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

Switch
Description
--c++Library or executable includes components written in C++ and so must link with a relevant stdc++ library. See the configure --enable-stdc++ setting.
--debug
Not implemented
--dry-run
Trace commands but do not execute
--entry NAME
Shared library entry point
--executable NAME
Name of executable to build
--graphical
Create a windowed program instead of a console program (Windows only)
--help
Print usage information
--library NAME
Name of library to link
--libraryPath "PATHS..."
Paths to search for the libraries
--libs "LIBRARIES ..."Extra libraries to link with
--native
Build for local execution not for execution on the target system
--objects "OBJECTS ..."
String containing list of objects to link
--objectsDir PATH
Directory to find / store objects
--quiet
Run quietly without tracing actions to stdout
--preferShared
Link with shared libraries by preference
--preferStatic
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)
--shared
Only make a shared library
--soname
Create a versioned shared library with a SONAME
--static
Only make a static library
--syslibs librariesExtra system libraries with which to link.
--version
Print the bld version number.
--versionSonameCreate a versioned shared library with soname.
--verboseVerbose operation.

The bld program also uses the following environment variables:

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


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