This document contains a description of the build process to rebuild AppWeb on a supported platform using the AppWeb source code package. Additional instructions apply to building the source code from the Subversion source code repository. If you are wanting to port AppWeb to a new platform, please read Porting AppWeb. For the product release notes and a detailed description of the installation procedure, please consult the Release Notes supplied with this release. The INSTALL.TXT file may also provide additional material - though is substantially similar to this document.
|
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-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-php5 --with-php5-dir=/usr/src/php-4.3.6 \
--with-php5-libs="php5 crypt resolv db z"
The configure program will modify the following variables (among others) in the relevant config.* and config.h configuration files.
Variable |
Typical Value |
Description |
BLD_AR_FOR_HOST |
ar (lib on windows) |
Archiver / library program for target host. |
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_OS | WIN | Build system operating system. Used in cross-development. |
BLD_CFLAGS_FOR_HOST |
"" |
The value of the CFLAGS environment variable when configure was run. Used for compiling programs for the target host. |
BLD_CC_FOR_HOST |
cc (cl on windows) |
C/C++ compiler for compiling programs for the target host. |
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_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_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_IFLAGS_FOR_HOST |
"" |
The value of the IFLAGS environment variable when configure was run. |
BLD_LD_FOR_HOST |
ld (link on windows) |
Linker program. |
BLD_LDFLAGS_FOR_HOST |
"" |
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_FOR_HOST |
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. |
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:
make clean
make compile -C bootstrap
make depend
make compile
make install
make uninstall
To understand more about the make system, read about the AppWeb make system below.
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.
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.
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 https://www.mbedthis.com/svn/appweb/main
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. | |
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/config.cache |
Cache of the current settings in effect for configure. Configure will reuse the last settings as a base. |
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 |
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 |
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. |
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. |