This document contains a description of the build process to rebuild AppWeb on a supported platform using the AppWeb source code package. Additional instructions apply to building the source code from the Subversion source code repository. If you are wanting to port AppWeb to a new platform, please read Porting AppWeb. For the product release notes and a detailed description of the installation procedure, please consult the Release Notes supplied with this release. OverviewThe appWeb source distribution contains all the necessary source files, headers, tools and test framework to reconfigure, build and verify the Mbedthis AppWeb Server. See Key Files below for a list of the important directories and files and their purposes.
Supported Platforms
|
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). |
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 defaults master file in conf/appWeb. Just 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 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) |
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-config |
Enabled |
Build with the ability to parse the Apache-style configuration files used by AppWeb. |
--enable-cookie |
Enabled |
Build with cooking handling support. |
--enable-digest-auth |
Enabled |
Build with Digest authentication support. |
--enable-fast-malloc |
Disabled |
Build with the Mbedthis fast memory allocator. About 5% faster than standard implementations. |
--enable-if-modified |
Enabled |
Build with the HTTP If-Modified checking. Only return documents to the browser if they have been modified. |
--enable-keep-alive |
Enabled |
Build with the HTTP Keep-Alive support. |
--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. |
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-gacompat |
Disabled |
Include GoAhead WebServer API compatibility. Only needed if migrating applications from the GoAhead WebServer. |
--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-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. |
--with-xdb |
Disabled |
Include support for the Xml Database. (Not yet supported). |
Option |
Default |
Description |
--with-PACKAGE=[builtin, | module] |
|
Specify if a PACKAGE should be included in the build. The package may be either built-into the AppWeb images using static linking and/or it may be built as a module. Normally you should choose either builtin or module. |
--without-PACKAGE |
|
Do not include the PACKAGE in the build. |
--with-PACKAGE-dir=DIR |
|
Set the source directory for the PACKAGE. |
--with-PACKAGE-libs=LIBRARIES |
|
Set a list of libraries to use when linking with the PACKAGE. |
--with-php4=[builtin, | module] |
Enabled
|
Build with the PHP4 package. The source distribution default is disabled. |
--with-php5=[builtin, | module] |
Enabled
|
Build with the PHP5 package. The source distribution default is disabled. |
--with-openssl=[builtin, | module] |
Enabled
|
Build with the Openssl package. The source distribution default is disabled. |
Variable |
Description |
AR |
Path to the archiver program to use to archive libraries for the target system. |
CC |
Path to the C/C++ compiler to use to compile for the target system. |
CC_FOR_BUILD |
Path to the C/C++ compiler to use for building bootstrap tools on the local system. |
LD |
Path to the linker program to use to link objects for the target system. |
RANLIB |
Path to the ranlib program to use if required. |
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. |
configure --type=DEBUG --enable-multi-thread --enable-shared \
--with-php4 --with-php4-dir=/usr/src/php-4.3.6 \
--with-php4-libs="php4 crypt resolv db z"
The configure program will modify the following variables in the relevant config.* and config.h configuration files.
Variable |
Typical Value |
Description |
BLD_AR |
ar (lib on windows) |
Archiver / library program. |
BLD_CFLAGS |
"" |
The value of the CFLAGS environment variable when configure was run. |
BLD_CC |
cc (cl on windows) |
C/C++ compiler. |
BLD_CC_FOR_BUILD |
cc (cl on windows) |
C/C++ compiler to use when building bootstrap tools that are used in the build process. |
BLD_COMPANY |
"Mbedthis" |
Name of the company distributing the product. You may change this. |
BLD_CPU |
MPR_CPU_IX86 |
Target CPU. Possible values defined in mpr/mprOs.h. |
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_IFLAGS |
"" |
The value of the IFLAGS environment variable when configure was run. |
BLD_INC_PREFIX |
/usr/include/appWeb |
Default product header location. |
BLD_HTTP_PORT |
80 |
The default HTTP port to listen on. |
BLD_LD |
ld (link on windows) |
Linker program. |
BLD_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_RANLIB |
ranlib |
Library symbol table index rebuild. |
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_UNIX |
1 |
Set to TRUE if the target O/S is UNIX-like. |
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. |
Once the build configuration is complete, you may proceed to build the source code by typing:
make clean
make depend
make compile
make test
make install
make uninstall
To understand more about the make system, read about the AppWeb make system below.
For Windows, Mbedthis AppWeb is supplied with both Visual Studio 6.0 project files and a Cygwin configure/make build system identical to the LINUX/UNIX build system. The Visual Studio project files provide a simple, fixed way of building AppWeb. However, you cannot modify the build configuration. The Cygwin build system offers complete control over the configuration via the supplied configure command.
appWebServer | Builds all files necessary for the appWeb program. Includes building all loadable modules. |
appWebClient | Builds the HTTP client. |
appWebUtils | Builds various utilities. |
The appWebServer project will build a the appWeb server program..
Cygwin is a Linux-like environment for Windows. It provides a complete set of GNU utilities such that the procedure for building AppWeb with Cygwin is the same as the Linux procedure described above. Also read the Running Configure section.
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 | |
appWebSamples |
||
C++ |
AppWeb samples written in C++ |
|
C |
AppWeb samples written in C |
|
bin | Directory to hold generated executables and DLLs (shared libraries). Windows will have Debug and Release subdirectories. |
|
bootstrap |
Bootstrap tools used in the build process |
|
conf |
Essential configuration files and Makefile rules |
|
doc | AppWeb documentation | |
ejs | Embedded JavaScript Engine for AppWeb | |
test | Unit tests for EJS | |
http | The core HTTP web server for AppWeb | |
modules | Dynamically loadable modules and handlers. Also used for statically linked modules. | |
test | Unit tests for the http server | |
utils | Utility programs: httpComp, httpPassword | |
mpr | The Mbedthis Portable Runtime (MPR) that provides a cross-platform executive for AppWeb to use | |
UNIX | UNIX dependent files for Linux, Solaris and other UNIX like operating systems. |
|
samples | MPR sample files | |
test | Unit tests for the MPR | |
WIN | Windows dependent files | |
obj |
Directory to hold generated objects. Windows will have Debug and Release subdirectories. |
|
visualStudio |
Microsoft Visual Studio workspace files |
make.os |
Key make settings for a given operating system. This is a copy of the master file conf/make.os.OS. |
make.rules | Key make targets and rules for all make files. This is a copy of the relevant make.rules.OS file from the conf directory. |
config.make | Build configuration file created by configure and used by Make. |
config.sh |
Build configuration file created by configure and used by shell scripts including the bld program. |
config.h |
Build header created by configure and included in all source files. |
configure | Build configuration program. |
bin/bld | Program to create executables and libraries (like GNU/libtool). |
conf/config.defaults.OS |
Configuration defaults for AppWeb for each operating system. Configure uses these defaults when first run and when the --reset switch is used to reset to factory defaults. |
conf/setupTree |
Used only when initializing a source tree for the first time after checking out from the Mbedthis Subversion source code repository. This file is not included in the source distribution but is included in the Subversion repository. |
conf/config.cache |
Cache of the current settings in effect for configure. Configure will reuse the last settings as a base. |
For Microsoft Visual Studio users who wish to customize the features of the AppWeb server, you will need to edit the config.make, config.sh and config.h header files. Key constants and settings are defined here and these files are included by C source, Makefiles and scripts. Many constants are repeated in two or three of the configuration files so be very careful and make sure you change each setting in every place it is mentioned. You must maintain consistency between the files. When editing be very careful to preserve quotes where they appear.
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 by uClinux. |
projects |
Make VisualStudio project files |
package |
Create an installable distribution package |
test |
Run unit tests |
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)
Variable |
Typical Value |
Description |
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. |
IFLAGS |
Any local include flags. |
|
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. |
all: compile
BLD_TOP := ../..
#
# Read the build configuration settings and make
# variable definitions.
#
include $(BLD_TOP)/config.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)/make.rules
include $(BLD_TOP)/make.os
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. |
Variable |
Typical Value (Linux) |
Description |
BLD_ARCHIVE |
.a |
File extension for static libraries. |
BLD_BIN_DIR |
${BLD_TOP}/bin/Debug |
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}/bin |
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}/bin |
Directory to hold build tools. |
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. |
Switch |
Description |
--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 |
--libs "LIBRARIES ..." |
Extra libraries to link with |
--libraryPath "PATHS..." |
Paths to search for the libraries |
--native |
Build for local execution not for execution on the target system |
--objects "OBJECTS ..." |
String containing list of objects to link |
--objectsList FILE |
File containing list of objects to link |
--objectsDir PATH |
Directory to find / store objects |
--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 |
--smartLibs "LIBRARIES ..." |
Use shared or static libraries intelligently depending on --preferShared, --preferStatic, BLD_FEATURE_STATIC and BLD_FEATURE_SHARED |
--version |
Print the bld version number. |
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. |