Embedthis Appweb 3.4.0
Home >Source Code> Build Steps

Quick Nav

See Also

Build Steps

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

  1. Define the Build Environment
  2. Configure
  3. Make
  4. Install

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

Define the Environment for Building

Linux, Unix and MAC OS X

If you wish to debug programs for release builds locally in your build tree, you may need to modify your environment to define the LD_LIBRARY_PATH variable so that Appweb programs can locate the dynamically loaded modules and libraries. If you only wish to build and install without running in the build tree, or if you are doing a debug build (configure --type=debug) then you do not need to modify your environment. Either way, it won't hurt to define LD_LIBRARY_PATH. On MAC OS X, the variable is DYLD_LIBRARY_PATH.

Set the LD_LIBRARY_PATH environment variable to include the lib directory in the source directory. This overrides the library search path compiled into the various Appweb executables which is normally set to the build prefix (/usr/lib/ejs).

LD_LIBRARY_PATH has a format similar to PATH and can be set via the command:

export LD_LIBRARY_PATH=/usr/src/ejs/lib:$LD_LIBRARY_PATH

This command may vary if you specify a non-default source installation directory, but normally this location is:

/usr/src/ejs/lib

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 setup your environment each time you login.

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. If you have the disk space, it is simplest to install all cygwin packages. Once installed, you should add the Cygwin programs directories to your PATH enviroment 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.

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.

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 binaries and dev heders (same as make install-binary install-dev) --prefix
make install-binary Install minimal binary files only --prefix --webDir
make install-dev Install the product documentation --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 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-3

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 Subdir Description
bin Directory to hold generated executables and DLLs on windows.
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.
build Essential build configuration files and Makefile rules.
doc Product documentation.
obj Directory to hold generated objects.
package Scripts for creating release distribution packages.
projects Microsoft Visual Studio and Eclipse project and workspace files.
samples Sample source code and examples
src Product source code.
all Staging directory for all-in-one builds.
mpr Embedthis Portable Runtime (MPR) for cross-platform O/S services.
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.
buildConfig.h Build header created by configure and included in all source files. On Windows, this file may be edited to modify the build.
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.
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.

© Embedthis Software LLC, 2003-2012. All rights reserved. Embedthis, Ejscript and Appweb are trademarks of Embedthis Software LLC.