Building Practical Map Server

Introduction

This document describes how to build the PMS web application from the source distribution.

Structure of the source distribution

The root directory of the PMS source distribution contains the following:

Name	Description
`applet`	Source code for the MapViewer applet
`bin`	Scripts for managing Tomcat, the standard open-source Servlet container I use to develop and test PMS (note that PMS is a standard Java web application and should run in any J2EE-compliant Servlet container).
`build.sh`	Wrapper script to execute Ant, a common open-source, Java-based build tool I use to build PMS.
`build.xml`	Ant configuration file.
`doc`	Documentation.
`etc`	Miscellaneous supporting files, including property files and the web application deployment descriptor (`web.xml`).
`lib`	Third-party code libraries on which PMS depends.
`src`	PMS source code.
`web`	JSPs for map display pages.

Prerequisites

In addition to what is included in the source distribution, the following software is required to build PMS:

JDK version 1.2 or higher
The Oracle Java libraries jndi.zip and classes12.zip, both located in $ORACLE_HOME/jdbc/lib (note that this is not a hard requirement to use PMS, but is currently necessary to build it from the source distribution without modification).

Preparing to Build

Before performing the build, you must ensure that the Java classpath references the Java and Oracle packages on which PMS depends. The classpath is specified in the file build.sh in the root directory of the distribution. Edit this file, modifying the value of JAVA_HOME to ORACLE_HOME to the appropriate values for your system.

Performing the Build

To perform a build, change directory to the root of the source distribution. Then execute the build.sh script you edited in the previous step:

$ ./build.sh

This command will first create a new subdirectory named build within the current directory. It will then build the complete web application (including servlets and the applet) in the directory build/pms.

The web application is then ready to configure and deploy within a Servlet container.

Build Targets

Following is the complete set of available build targets:

Name	Description
`clean`	Deletes all files from the latest build in `build/pms`, except those in `build/pms/data`. WARNING: This will destroy all changes you have applied to the build, including configuration and data files, even if those files are symbolically linked from other directories. Use with caution!
`prepare`	Creates the directory structure of the web application and copies over all static files, including documentation, code libraries, resources and configuration files.
`compile`	Selectively recompiles any server class files that have been modified since the last build.
`javadoc`	Rebuilds the source code documentation in `build/pms/doc/javadoc`.
`applet`	Selectively rebuilds the applet class files that have been modified since the last build, and refreshes the `MapViewer.jar` file for client download.
`all`	Default target. Performs all of the above tasks except for the dreaded `clean`.
`dist`	Builds source (`build/pms.jar`) and web application (`build/pms.war`) archives for distribution.

To build one of these targets, simply specify it as an argument to the build script:

$ build.sh applet

Last modified: $Id: build.html,v 1.2 2001/06/24 21:11:58 karl Exp $