roshan 2004/10/27 21:23:30 Added: site/src/documentation/content/xdocs/cpp antbuild-guide.ihtml Log: Added antbuild-guide to the site. Added by Rangika Revision Changes Path 1.1 ws-axis/site/src/documentation/content/xdocs/cpp/antbuild-guide.ihtml Index: antbuild-guide.ihtml =================================================================== ANT Build Guide

Axis C++ ANT Build Guide

This document provides instructions for using and extending the ANT based build for the AXIS C++ project.

Preparing system
Getting necessary third party software
Property Files
Getting a CVS checkout
Setting the Environment
Running the ANT build
Enabling Trace and Debug
Adding an extra platform

Preparing system

To use the ANT based build you will need to install the following:

Getting necessary third party software

Axis Cpp Developers can use either Xerces-c or the Expat XML Parsers to build the Axis Cpp. Additionally, you can opt to build Apache mod files for Apache 1.3 or 2.0.

Expat XML Parser

You can get expat binaries from http://sourceforge.net/projects/expat/.

Xerces-C XML Parser

You can get Xerces-C binaries from http://xerces.apache.org.

Apache

You can get Apache 1.3 or 2.0 from http://httpd.apache.org/

Property Files

To aid in the portability of the ANT scripts, a number of property files are used. The script will decide which to use based on the platform in which it is currently running. The property files are found in ws-axis/c with the following naming convention:

build.[platform].properties

A number of example property files are provided for Windows, Linux, AIX and Solaris, it is intended that you update these files to suit your development and buid environment. This includes location of third party software dependencies and target packaging structure.

These property files also allow you to make some selection on which artefacts will be produced by the build:

The default selections are Xerces as XML parser, axis2 transport implementation and both the Apache 1.3 and Apache 2.0 modules.

Setting the Environment

Before running ANT the following environment variables must be set:

The default property files make use of the following environment variables to locate the various third party software dependencies.

Getting a CVS checkout

Visit http://ws.apache.org/ Click on “axis” and then on “CVS Repository” to find details on how to access the CVS Repository.
In short summary:
Anyone can checkout the source code from our anonymous CVS server. To do so, simply use the following commands (if you are using a GUI CVS client, configure it appropriately):

cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
password: anoncvs

cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout ws-axis

The checkout of the repository will be created in the current directory in a folder named “ws-axis

The checked out folder ws-axis/c will be referred to as [CHECKOUT_HOME] from this point on.

Running the ANT build

Once you have configured your environment and property files the build is a simple two step process. The first step is to build all the generated artefacts. At the comment prompt change to [CHECKOUT_HOME] and run:

ant

This will carry out the following:

The second step is to package the generated artefacts. From [CHECKOUT_HOME] run:

ant -f package.xml

This will carry out the following:

To remove artefacts from a previous build use the following command:

ant clean

Enabling Trace and Debug

By default, the ANT build scripts do not produce libraries with trace or debug symbols. To include these make use of one of the following to build:

ant buildWithTrace
ant buildWithDebug
ant buildWithTraceAndDebug

The packaging step remains the same. Although it the source release package will automatically select the trace instrumented source code.

When trace is selected, the ant build adds in trace entry and exit statements into many of the methods in Axis C++. Then at runtime, in axiscpp.conf, set ClientLogPath to a file in a directory somewhere and Axis C++ will write out trace to that file. Omitting ClientLogPath from axiscpp.conf switches trace off.

Adding an extra platform

The AXIS community would greatly appreciate your input, if you're working on a platform not currently supported by the ANT scripts.
Below, are the steps required to add an additional platform;

  1. Add platform detection to pre-init target in buildIntialize.xml, eg:
    <condition property="linux">
    <os name="Linux"/>
    </condition>
  2. Update platform property within initialize target in buildIntialize.xml, eg:
    <condition property="platform" value="Linux">
    <isset property="linux"/>
    </condition>
  3. Provide an additional property file in ws-axis/c to match your platform. This uses the naming convention build.[platform].properties, where platform is as specified in step 2.
  4. Provide compiler definition for platform in buildIntialize.xml, include a condition check for the correct platform and any debug flags should be conditional on the debug property being set, eg:
    <compiler id="Linuxgcc" name="g++" if="linux">
    <compilerarg value="-g" if="debug"/> <compilerarg value="-Wall"/>
    <compilerarg value="-Wshadow"/>
    <compilerarg value="-O2"/>
    <defineset>
    <define name="ENABLE_AXIS_EXCEPTION"/>
    <define name="HAVE_CONFIG_H"/>
    <define name="PIC"/>
    </defineset>
    <includepath path="${dir.include}"/>
    </compiler>
    Note: Compilers may extend one another, which can be useful if an additional platform uses the same compiler, but maybe only small variations in the parameters.
  5. Provide linker definition for platform in buildIntialize.xml, include a condition check for the correct platform and any debug flags should be conditional on the debug property being set, eg:
    <linker id="LinuxLinker" name="g++" libtool="true" if="linux">
    <linkerarg value="-g" if="debug"/>
    <libset libs="stdc++"/>
    </linker>
    Note: As for compilers, linkers may extend one another.
  6. Add new compiler and linker to the cc task within each of compileAxisClient, compileAxisTransport, compileAxisXMLParser, compileSimpleAxisServer, compileAxisServerEngine, compileApache13Module and compileApache20Module targets, eg:
    <cc outfile="${dir.bin}/${transportLibraryName}" objdir="${dir.objects}"
    exceptions="true" failonerror="false" outtype="shared" multithreaded="true">
    <!-- Compilers -->
    <compiler refid="Linuxgcc"/>
    <compiler refid="AIXxlc"/> ...
    <!-- Linkers -->
    <linker refid="LinuxLinker"/>
    <linker refid="AIXLinker"/>
    ...
    </cc>