This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata

This section refers to the XAP build system. If you simply want to use XAP within your web application you can skip this page. If you would like to modify the XAP code or create custom XAP profiles, read on.

Installing XAP

To install XAP, you must perform the following major steps. See below for details on each step.

  • Install prerequisites
  • Download the XAP source
  • Build XAP
  • Deploy to a Web server

Installing Prerequisites

In order to use the build system of XAP you'll need:

  • Java 2 Standard Edition (J2SE) Java Development Kit (JDK)
  • Apache Ant
  • A web server (for example, Apache Web Server)
  • Perl (optional: used for generating the documentation)

Installing a Java Development Kit (JDK)

The XAP build requires Sun J2SE JDK 5 (1.5).

To download the latest Sun J2SE JDK 5 (1.5):

  • Go to:
  • Locate and select J2SE 5.0.
  • Look for the JDK 5.0 Update (Latest) banner.
  • Click Download JDK 5.0 (Latest) to install it on your development system. Note: This installer includes JS2E Runtime Environment 5.0.

Installing Apache Ant

Install Apache Ant (1.6.1 or greater) to use the build system.

To install Apache Ant:

  • Download and install Ant from
  • Follow instructions for installing Apache Ant available in the manual.

Important Notes

Note for Windows users:

The XAP build system requires the ant bin directory to be in your path -or - ANT_HOME to be defined. From the command line: set PATH=%PATH%;"C:\Program Files\Ant\bin" - or right click on My Computer, choose Advanced and click Environment Variables.

Note for Linux and Unix users:

The build scripts require manually editing of the exec function to work properly. This is a known issue that we are working to resolve.

Installing a Web Server

Deploying the XAP source and example code requires a web server such as Apache web server available at

Follow your Web server's instructions to perform a typical installation of the Web server on your local system.

Installing Perl (Optional)

Perl is used with JSDoc to create documentation from the JavaScript source file. If you are on a Windows system you will need to download Perl from Note: If JSDoc informs you that you are missing a library, see JSDoc homepage for the appropriate instructions.

Downloading the Source

Download the XAP source from the XAP subversion repository:

Versions available:

Building XAP

To build XAP, use the XAP build scripts.

The XAP build scripts provide the following directives:




Runs the JSUnit tests. You will need to modify the jsunit-server-properties.xml to point to your web browser of choice.


Deploys examples without rebuilding profile.


Rebuilds profile and redeploys examples.


Compresses based on a profile in buildscripts/profiles.


Builds the documentation.


Compiles the JAR needed for source compression.


Compresses all system JS files and places the output in \compressedSource.


Runs all directives.

To view a list of the build directives, at a command prompt:

  1. Navigate to the root directory into which you downloaded XAP. 2. Type: build

The following output appears:

     [echo] Build script help
     [echo] This build script requires jdk1.5 for JSUnit
     [echo] Available targets:
     [echo] tests: runs JSUnit tests. You will need to modify
     [echo]     jsunit-server-properties.xml to point to a
     [echo]     browser on your machine.
     [echo] deploy-examples: deploys examples without rebuilding profile
     [echo]     usage: ant deploy-examples -DwebappsRoot=[dir]
     [echo]             -DexamplesAppName=[name]
     [echo] examples: rebuilds profile and redeploys examples
     [echo]     usage: ant examples
     [echo] build-profile: compresses based on a profile in
     [echo]     buildscripts/profiles to a specified directory
     [echo]     usage: ant build-profile -Dprofile=[profile_name]
     [echo]             -Drelease_dir=[dir]
     [echo] doc: builds JSDoc to doc/xap directory
     [echo] all: runs tests, examples and doc
     [echo] help: prints this message

Total time: 0 seconds

To build XAP and all of its components, at a command prompt:

  1. Navigate to the root directory into which you downloaded XAP.
  2. Type:
    build all

To build the sample files only, at a command prompt, type:

    build examples

If a message similar to the following appears, you can ignore it:

    Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre1.5.0_08\lib\tools.jar

This messages indicates that only a JRE is installed on your system and not a JDK. However, for XAP you need a JRE only.

Deploying to a Web Server

After running the build, a \staging directory appears in the XAP directory structure. Copy the contents of the staging directory to your Web server and you will be able to run the example files.

Important Notes

  1. IIS does not recognize files with a .XAL extension. Add a mime type text/xml handler for this file extension with the IIS configuration.
  2. By default web browsers cache .XAL files - meaning you won't see changes when you hit refresh. You can work around this by adding a cache-control: no-cache HTTP header, either by changing the server configuration or by using a server side script to generate the XAL files.
  • No labels