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.
|
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. |
CC=/tornado/host/x86-win32/bin/cc386 \
LD=/tornado/host/x868-win32/bin/ld3868 configure
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 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) |
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) |
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. |
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
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. |
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: 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.
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
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 |
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). |
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. |
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.
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 |
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. |
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 |
--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. |
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. |