Embedthis Appweb 4.3.4
Home >Source Code> Building with Bit

# Quick Nav

- Download Bit
- Configuring the Build
- Configure Options
- External Packages
- Building with Bit
- Static Linking
- Serving from ROM
- Installing
- Cross Compiling
- Building with Make
- Building with an IDE

# See Also

# Building with Bit

The procedure for building with Bit is the same for all supported platforms.

### Download Bit

You can download Bit from the Embedthis Bit Download download site. Packaged installations are provided for Windows and MACOSX. For Linux, use the source distribution. See the Bit Documentation for information regarding installing Bit.

### Configure Appweb

Before building with Bit, you need to do a one-time configuration. This customizes Appweb to select features, options, third-party packages available on your system. The configure script simply invokes bit configure and passes all command line options to bit.

### Running Configure

You may run the configure script with no options to accept the defaults — this is a good starting point:

    ./configure

You may also supply options to tailor the build:

    ./configure --release --without all

The --release switch instructs bit to build an optimized production release. This will disable debugging code and non-essential logging. The --without all switch will disable non-essential features to create a minimal build.

During configuration, bit will create:

- A bit file that specifies the platforms to build named: start.bit
- A bit file for each platform named: OS-ARCH-PROFILE].bit
- A source header with for the build configuration named: OS-ARCH-PROFILE/inc/bit.h
- An output products directory for each platform named: OS-ARCH-PROFILE

where OS is the name of the operating system, ARCH is the name of the cpu architecture and PROFILE is the build profile name, typically "debug" or "release". For example: linux-x86-debug.

The generated Bit files are readable Javascript files that contain the settings to control the build when Bit is run. When compiling, source code may include the bit.h header to read the Appweb configuration.

## Configure Options

The tables below describe the key configuration options.

### Basic Configure Options

Option | Description
--- | ---
--debug | Build a debug build. This builds a development, non-optimized build with debug symbols.
--help | Display the bit program usage help.
--set KEY=VALUE | Set the value of a property in the bit settings collection. For example: "--set mpr.tracing=false".
--quiet, -q | Run quietly without progress trace.
--release | Build a release build. This builds an optimized, production-ready build of the software.
--verbose, -v | Run verbosely and emit more detailed progress trace.

### Cross Compiling

Option | Description
--- | ---

--platform OS-ARCH-PROFILE

Specify the target platform for which to build. For example "-platform linux-arm-debug". Supported operating systems are: freebsd, linux, macosx, solaris, vxworks and windows. Supported architectures are: arm, mips, ppc, x64 or x86.

If the -platform option is omitted, the local system is added as the target platform. You may use the 'local' alias to indicate the local platform. Multiple platforms may be specified.

The ARCH component may specify a CPU instance to tune for. The CPU setting is used in a -DCPU=VALUE compiler define. For example: "-platform linux-arm:arm7tdmi-debug".

NOTE: the platform switch is not a typical configure --host argument. i.e. The second component is a system architecture and not a distribution name.

### Feature Options

Option | Default | Description
--- | --- | ---
--without all |  | Disable all non-essential possible packages.
--set tune=MODE | size | Tune the build to optimize for "size", "speed". You can also select "balanced" for a balance between speed and size.

### Optional Packages

Option | Description
--- | ---
--with PACKAGE[=dir] | Specify if a PACKAGE should be included in the build. The optional directory is the path to the source distribution of the package. If the directory is omitted, bit will search the local system for the package in well known places.
--without PACKAGE | Do not include the PACKAGE in the build.

### Example Use

    configure --with openssl=/usr/src/openssl

### Packages

The following table describes the packages that can extend the Appweb configuration. The use of the Integrated field states whether the package is shipped internally with the Appweb source code, or whether it is an external third party package.

Package | Integrated | Description
--- | --- | ---
cgi | Internal | Common Gateway Interface (CGI).
dir | Internal | Directory Listing Handler.
ejscript | Internal | Ejscript web framework.
esp | Internal | Embedded Server Pages web framework.
est | Internal | Embedded Security Transport. SSL stack. (Prototype)
matrixssl | External | MatrixSSL SSL stack. Requires a commercial license from PeerSec.
nanossl | External | Mocana NanoSSL stack. Requires a commercial license from Mocana.
openssl | External | OpenSSL SSL stack. Requires OpenSSL libraries.
php | External | PHP framework. Requires PHP libphp5 library.
sqlite | Internal | SQLite SQL database.

The following table describes the tool packages that can be used when building, running and managing Appweb. The use of the Internal/External field documents whether the package is shipped internally with the Appweb source code, or whether it is an external third party package.

Package | Integrated | Description
--- | --- | ---
doxygen | External | C API documentation generator.
dsi | External | Dev Side Includes. Simple static web page templates.
ejs | External | Ejscript command shell. See http://ejscript.org.
http | Internal | Http test client program.
man | External | Manual page reader and renderer.
man2html | External | Program to convert man pages to HTML.
pmaker | External | Native package maker. This resolves to InnoSetup on Windows and PackageMaker on MAC OSX.
utest | External | Ejscript unit test framework. See http://ejscript.org.
zip | External | Zip compression program. Used when creating installable packages.

### Environment Variables

When cross compiling, certain environment variables may be passed to the configure script and on to bit to configure the compiler and linker paths and flags.

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.
CFLAGS | Compiler control flags.
DFLAGS | Compiler preprocessor defines.
IFLAGS | Include directory options.
LD | Path to the linker program to link objects for the target system.
LDFLAGS | Linker flags. E.g. -Ldir to specify a non-standard directory for libraries.

### Example Use

    CC=/opt/bin/ccarm configure

### Bit Configure Examples

Here are some useful configure command options.

To configure for building outside a source tree. This supports building from source from a read-only file system.

    configure --configure /path/to/source

To configure for a debug build with debug symbols:

To configure without TLS/SSL:

    configure --without ssl

To configure using PHP from a specific source location:

    configure --with php=/path/to/php-source

To configure to build for 32-bit X86 (when on a 64-bit system):

    configure --platform linux-x86-debug

To display all configure options:

    configure --help
    Usage: bit [options] [targets|actions] ...
      Options:
      --benchmark                              # Measure elapsed time
      --configure path-to-source               # Configure for building
      --continue                               # Continue on errors
      --debug                                  # Same as --profile debug
      --depth level                            # Set utest depth level
      --diagnose                               # Emit diagnostic trace
      --dump                                   # Dump the full project bit file
      --endian [big|little]                    # Define the CPU endianness
      --file file.bit                          # Use the specified bit file
      --force                                  # Override warnings
      --gen [make|nmake|sh|vs|xcode|main|start]# Generate project file
      --help                                   # Print help message
      --import                                 # Import standard bit configuration
      --keep                                   # Keep intermediate files
      --log logSpec                            # Save errors to a log file
      --nocross                                # Build natively
      --overwrite                              # Overwrite existing files
      --out path                               # Save output to a file
      --platform os-arch-profile               # Build for specified platform
      --pre                                    # Pre-process a source file to stdout
      --prefix dir=path                        # Define installation path prefixes
      --profile [debug|release|...]            # Use the build profile
      --quiet                                  # Quiet operation. Suppress trace
      --rebuild                                # Rebuild all specified targets
      --reconfigure                            # Reconfigure with existing settings
      --release                                # Same as --profile release
      --rom                                    # Build for ROM without a file system
      --set [feature=value]                    # Enable and a feature
      --show                                   # Show commands executed
      --static                                 # Make static without shared libraries
      --unicode                                # Set char size to wide (unicode)
      --unset feature                          # Unset a feature
      --version                                # Display the bit version
      --verbose                                # Trace operations
      --with PACK[=PATH]                       # Build with package at PATH
      --without PACK                           # Build without a package
    Feature Selection:
        --set http.pam=value                   # Enable Unix Pluggable Auth Module (true|false)
        --set mpr.logging=value                # Enable application logging (true|false)
        --set mpr.tracing=value                # Enable debug tracing (true|false)
    Extension Packages (--with PACK):
        doxygen                                # Doxygen Documentation Generator
        dsi                                    # Developer Server Side Include Tool
        est                                    # Embedded Security Transport (Prototype)
        man                                    # Manual Page Formatting Tool
        man2html                               # Manual Page to HTML Converter
        matrixssl                              # MatrixSSL (SSL)
        nanossl                                # Mocana NanoSSL (SSL)
        openssl                                # OpenSSL (SSL)
        pmaker                                 # Package Maker Tool
        sqlite                                 # SQLite Database
        zip                                    # Zip Compression Tool

### Configuring External Packages

The Bit configuration process supports the resolution of external packages that extend and enhance Appweb, such as 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 configure --with PACKAGE=PATH switch. This specifies the path to the package source directory.

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

1. Download MatrixSSL from http://www.peersec.com.
2. Build MatrixSSL (See Building SSL for additional instructions)
3. Then, from the Appweb source directory run the Appweb configure:

       ./configure --with matrixssl=/path/to/matrixssl

During configuration, the required Matrixssl libraries and headers will be copied into the Appweb source tree.

## Building Appweb with Bit

After configuring, you may proceed to build the source code by typing:

    bit

This will fully build the software. If cross compiling and depending on your configuration, it may build twice: once for the local system and once for the target platform. This may be necessary to build required tools. If Ejscript is enabled, this is required.

### Useful Bit options and targets

Here are some useful bit examples:

    bit --show     # Show actual commands while building
    bit --why      # Show why each target is or is not being built
    bit --dump     # Dump the combined bit configuration in one file
    bit rebuild    # Rebuild all targets
    bit clean      # Clean all built targets
    bit rebuild    # Rebuild all targets
    bit install    # Install the built software locally
    bit help       # Show bit usage

## Static Linking

On some platforms, it is desirable to statically link the Appweb web server. The default Appweb Bit files will build Appweb using shared libraries. This is so that appweb can dynamically load modules at run-time. It is best to use dynamic linking if using ESP so that it can dynamically reload applications to update them. This is ideal when developing so that you can quickly reload applications by simply clicking reload in your browser.

However, if you want to statically link Appweb and the modules together, run configure with the --static option and then rebuild.

    ./configure --static
    bit

If using ESP with static linking, you must take extra steps to pre-compile your ESP pages and applications. These steps are:

1. Pre-compile your ESP pages and applications.
2. Link the ESP initializer code into appweb.

### Pre-compile ESP

You can pre-compile ESP pages and applications for static linking and create a static library that can be linked with appweb when rebuilding appweb. Use the following command to compile all ESP pages and applications that are defined in the appweb.conf file.

    cd src/server
    esp --static --flat --genlink slink.c compile

This will create a static library in the cache directory for each ESP application and in the src/server/cache directory for stand-alone ESP pages.

The --genlink slink.c option will generate the slink.c file which contains a function appwebStaticInitialize() that will invoke the ESP initializers for the ESP pages and applications. Appweb contains a reference to this function in src/server/appweb.c. When rebuilt, it will then resolve and link with the ESP static libraries.

## Serving from ROM

Appweb supports systems without a file system where web documents are compiled into C code and served from ROM. To enable this, configure with the --rom switch.

    configure --rom
    bit

Note that static linking implies significant limitations on Appweb:

- Modules cannot be dynamically loaded and must be statically linked
- Reloading ESP applications without restarting the server is not possible

See Serving Pages from ROM for more information.

## Installing

You can install the newly built software via bit:

    sudo bit install

You can remove by:

    sudo bit uninstall

## Cross Compiling

To build a product for platform different to that of the local system is called cross compiling. Sometimes this compiling is just for a different instruction set (say x64 instead of x86). Other times, it is for a completely different operating system and/or CPU architecture. In such cases a cross-compiler is typically required to build for the target platform.

Bit supports cross compiling via the -platform PLATFORM bit configure option. This option adds a platform to the list of platforms to be made. Multiple platforms may be specified and the 'local' platform alias may be used for the local development platform.

    bit -platform linux-arm-debug -configure .

This will create a windows-x64.bit configuration file and a start.es that references it. The platform switch does not need to be restated after configuration.

### Platforms

A platform specification is of the form OS-ARCH-PROFILE, where the supported operating systems are: freebsd, linux, macosx, solaris, vxworks and windows. The ARCH field is one of arm, mips, ppc, x64 or x86. X64 is the AMD/Intel 64-bit instruction set and x86 is the Intel X86 Pentium instruction set. You may also use i386 or i686 for specific Intel X86 instruction sets.

The ARCH field may contain an optional CPU field to specify a CPU to tune for. This is specified as a :CPU suffix for the ARCH field.

Note the configuration options apply to the preceding platform. If not preceding platform, the option applies to the local platform.

    configure -with ejscript -platform linux-arm-debug -without ejscript

This will build Ejscript for the local development system, and without Ejscript for the target.

### Environment Variables

When cross compiling, you may need to inform configure about your cross-compilation tool chain. Bit will do its best to discover the installed cross tool chain and will look in well known directories to locate the compiler, linker and other required tools. If bit cannot locate the tool chain, you can supply the tool chain details via the environment variables: CC, CFLAGS, DFLAGS, IFLAGS LD and LDFLAGS. These will be used to define and configure the cross-compilation tool chain.

For example, here is a cross-compilation configure command line to create a debug build of Appweb for Linux on ARM7:

    CC=/opt/bin/cc.exe \
    LD=/opt/bin/cc.exe \
    CFLAGS=-I/opt/include \
    configure --debug --platform linux-arm:arm7tdi-debug

## Create an Installable Release

After building, bit can create installable packages of the software:

    bit package

The release packages are placed under the releases directory. The appweb-tar.tgz image is a simple compressed tar archive of the binary release.

## Deploying

If you are embedding Appweb into another application or installing to a target device, you can deploy the required Appweb files to a staging directory.

    bit --sets core deploy

This will copy the required Appweb files to the deploy directory under the platform output directory.

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