Quick Nav

Define the Environment
Configuring the Build
Cross Compilation
Building
Customizing
Installing
Source Repository
Key File and Directories

Build Steps

These steps (and links) to rebuild from source are defined below:

Define the Build Environment
Configure
Make
Install

If you want to build using source from the source code repository, please read these additional instructions.

Define the Environment for Building

Building on Windows

To use the configure program on Windows, you will need to install the Cygwin UNIX emulation development tools. These provide UNIX-like commands under Windows and provide a consistent development environment on Windows and Unix. If you wish to build on Windows and not install the Cygwin tools, you can use the supplied Microsoft Visual Studio project file and hand-edit the supplied buildConfig.h header file.

You also need to define certain Microsoft compiler environment variables as described in the Microsoft Visual Studio installation. These variables are the PATH, INCLUDE and LIB variables. They need to be defined so they will contain references to where the Microsoft compiler and libraries are installed on your system. The vcvars32.bat command supplied with Visual Studio is the normal way to define these variables.

If you wish to be able to run the configure program or use the make command to build from the command line, then you will need to download the Cygwin tools from www.cygwin.com. You will need to install the binutils package, but we recommend you install all of cygwin if you have the room. Once installed, you should add the Cygwin programs directories to your PATH environment variable.

Configuring the Build

The configure program is used to tailor the software's configuration to suit your needs. It is the master configuration tool and it will create the "build/buildConfig.*" configuration files. These files are included by make files, shell scripts and by C source files to control the build process.

You may run configure with no options to accept the factory defaults — this is a good starting point. The configure program will begin with the default settings supplied in the "build/standard.default" file. Then it will apply the various options specified on the command line.

Running Configure

To run the configure program, type:

./configure

Use the "--help" switch to see the available options or see the Configure Program document for more details.

External Packages

The Appweb configure command supports the resolution of external packages such as Ejscript, OpenSSL and PHP. By default, Appweb can locate these packages if the source distributions are installed in standard locations. Otherwise, the packages can be identified by using the configure --with-PACKAGE=PATH switch. This specifies that path to the source directory containing the package source distribution.

For example, to build with Ejscript, follow these steps:

Download Ejscript. You can download the open source version of Ejscript from https://github.com/embedthis/ejs-2. Contact sales@embedthis.com if you require a commercial license.
Configure and build Ejscript via the Ejscript configure command in the Ejscript directory:
```
./configure
make
```
From the Appweb source directory run the Appweb configure:
```
./configure --with-ejscript=/path/to/ejscript
make
```

The Appweb configure program and Makefiles will import the required libraries and headers into the Appweb source tree. NOTE: Ejscript will provide the MPR and HTTP library as they must be common between Appweb and Ejscript.

Cross Compilation

To configure for cross compilation you need to specify the --host and --build switches. These take system architecture specifications in the form: CPU-VENDOR-OS. For example: i386-pc-linux or powerpc-wrs-vxworks. The host system is the target system that will eventually run the software. The build system is the development system being used to compile and build the software. For example:

./configure --host powerpc-wrs-vxworks --build pentium-pc-windows

If you don't specify the build system, configure will do its best to guess your current system configuration. Other typical host configurations are: --host arm-ms-wince for Windows CE on Arm, --host i386-wrs-vxworks for VxWorks on X86, --host i686-apple-darwin for Mac OS X in 32 bit.

Specifying the Tool Chain

When cross compiling, you also need to inform configure about your cross-compilation tool chain. This means the names of your compiler, library archiver and other utilities and flags.

The configure program listens to the settings of the AR, CC, NM, RANLIB, STRIP, CFLAGS, IFLAGS and LDFLAGS environment variables and will pass their values into the build system. These will be used to define the cross-compilation tool chain. You can also specify an alternate build tool chain by using the same variables but with a BUILD_ prefix.

For example, here is a simple cross-compilation configure command line:

DIR=/path/to/cross-tools ; \
AR=$DIR/bin/ar.exe \
CC=$DIR/bin/cc.exe \
LD=$DIR/bin/cc.exe \
NM=$DIR/nm.exe \
RANLIB=$DIR/ranlib.exe \
STRIP=$DIR/strip.exe \
CFLAGS="-I$DIR/include \
./configure --type=DEBUG --host=arm--linux

Uclibc

You can use the cross-compilation techniques to support compact C libraries such as the popular uclibc system library. While not strictly cross-compilation, the techniques of setting CFLAGS, IFLAGS and LDFLAGS are used to redirect the compiler to use the uclibc libraries and headers instead of the standard libc versions.

If using the Ubuntu linux operating system, you can install uclibc by typing:

apt-get install libuclibc-dev

This will install uclibc in the /usr/i386-uclibc-linux directory. The following command will run configure and support a uclibc based build.

CFLAGS="-nostdlibs -fno-stack-protector" \
IFLAGS="-I/usr/i386-uclibc-linux/include" \
LDFLAGS="-nodefaultlibs -nostartfiles \
    /usr/i386-uclibc-linux/lib/crt1.o \
    /usr/i386-uclibc-linux/lib/crti.o \
    /usr/i386-uclibc-linux/lib/crtn.o \
    /usr/i386-uclibc-linux/lib/libc.a \
    /usr/lib/gcc/i486-linux-gnu/4.1.2/libgcc.a" \
./configure --type=debug --static --tune=size

Building via Make

Once the build configuration is complete, you may proceed to build the source code by typing:

make

This will first make the build tools will then create the make dependencies before compiling the code. To understand more about the make system, read the Make Scheme document.

Customizing

Appweb includes the src/customize.h header when building. This file may be used to customize or override certain Appweb settings.

#define BLD_SERVER_ROOT — Path to the Appweb configuration directory
#define BLD_CONFIG_FILE — Path to the appweb.conf configuration file
#define BLD_APPWEB_PATH — Path to the Appweb executable image

On VxWorks, it is required to define BLD_APPWEB_PATH so that Appweb can load modules which are located relative to the Appweb executable image.

Define BLD_CONFIG_FILE and BLD_SERVER_ROOT to set default locations for Appweb initialization.

Static Linking

On VxWorks, it is sometimes required to statically link the Appweb web server. The default src/server/Makefile is setup to build Appweb and the loadable modules separately. If you want to statically link the modules, edit the Makefile and add the required modules to the MODULES variable.

Installing

You can install the newly built software via:

sudo make install

You can remove by:

sudo make uninstall

You can also install other components by typing the following commands.

Command	Description	Configure Location Option
make install	Install the program binaries and libraries	--prefix
make install-dev	Install the product documentation and headers	--libDir --incDir

You can remove the components by using make uninstall-ITEM. Where ITEM is one of the above components. If you want to see what files get installed and where, set TRACE=1.

make TRACE=1 install

Capturing Install Files

If you want to capture the files to be installed, you can install to a local directory via "make deploy". This will prompt for a local directory in which to install Appweb. This can also be done by rebasing the ROOT_DIR variable. This will prepend the ROOT_DIR to all the installation directories. This is useful to stage all the files necessary for deployment on another system. From this directory, the files can be zipped or packaged for convenience. For example:

 make ROOT_DIR=/myDir install

This will copy the binary installation files to /myDir.

Building from the Source Code Repository

You can checkout a copy of the product source code via:

 git clone http://github.com/embedthis/appweb-4

Once checked out, the normal instructions for building from source apply.

Key Files and Directories

Source trees contain the following key directories under the top directory.

Directory	Subdirectory	Description
build		Build configuration and tools.
	bin	Binary build tools.
	config	Configure scripts for each O/S.
	packages	Default settings for 3rd party packages.
	make	Make rules and per O/S default settings.
	src	Source code for build tools.
doc		Product documentation.
out		Build output directory.
	bin	Directory to hold generated executables and DLLs on windows.
	inc	Include headers
	lib	Generated libraries.
	obj	Directory to hold generated objects.
	releases	Generated release distributions.
package		Scripts for creating release distribution packages.
projects		Microsoft Visual Studio and Eclipse project and workspace files.
src		Product source code.
	deps	Dependant libraries including MPR, Http, Pcre.
	samples	Sample source code and examples
test		Unit and integration tests.

Key Build Files

Name	Description
build/make/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.
out/inc/buildConfig.h	Build header created by configure and included in all source files. On Windows, this file may be edited to modify the build.
configure	Build configuration program.
build/bin/bld	Program to create executables and libraries (like GNU/libtool).
build/config/config.OS	Configuration defaults for each operating system. Configure uses these as the default O/S settings.