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.

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

./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

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.

Example Use

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

Configure Command Line Options

Installation Directory Options

System Build Types

Basic Configure Options

Feature Options

Optional Modules and Handlers

Optional Packages

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

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.

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:

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.

Key Build Files

The Make System

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)

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