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 Embedthis 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 Embedthis 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_CC	Path to the C/C++ compiler to use for building tools required for building on the local development system.
BUILD_LD	Path 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-client	Enabled	Buidl 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-save	Disabled	Build 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-ejs	Enabled	Include the EJScript language.
--enable-floating-point	Enabled	Include 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-ipv6	Disabled	Build with IPv6 support.
--enable-keep-alive	Enabled	Build with the HTTP Keep-Alive support.
--enable-legacy-api	Disabled	Build 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	Disabled	Build with the standard libc libstdc++ library instead of the builtin Appweb alternative. Results in bigger memory requirements if enabled.
--enable-test	Disabled	Build 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-copy	Enabled	Include 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	"Embedthis"	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	"Embedthis 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.embedthis.com/svn/appweb/main

Key Files and Directories

The Embedthis 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 Embedthis 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).

The 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 libraries	Extra system libraries with which to link.
--version	Print the bld version number.
--versionSoname	Create a versioned shared library with soname.
--verbose	Verbose 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.