You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ro...@apache.org on 2004/10/28 06:23:30 UTC
cvs commit: ws-axis/site/src/documentation/content/xdocs/cpp antbuild-guide.ihtml
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
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>ANT Build Guide</title>
<meta name="Author" content="Adrian Dick">
<meta name="Keywords" content="">
<meta name="Description" content="">
</head>
<body>
<h1>Axis C++ ANT Build Guide</h1>
<p>
This document provides instructions for using and extending the ANT
based build for the AXIS C++ project.</p>
<p><a href="#prepareSystem">Preparing system</a><br>
<a href="#thirdPartySoftware">Getting necessary third party software</a><BR>
<A href="#PropertyFiles">Property Files</A><br>
<a href="#cvsExtract">Getting a CVS checkout</a><br>
<a href="#SettingTheEnvironment">Setting the Environment</a><br>
<a href="#runningTheBuild">Running the ANT build </a><BR>
<A href="#EnablingTraceAndDebug">Enabling Trace and Debug</A><br>
<a href="#addingExtraPlatform">Adding an extra platform </a></p>
<h2><a name="prepareSystem"></a>Preparing system</h2>
<p>
To use the ANT based build you will need to install the following:</p>
<ul>
<li>Apache ANT
<ul>
<li>Available from <a href="http://ant.apache.org">http://ant.apache.org</a></li>
<li>These scripts have been developed and tested using version
1.6.x</li>
</ul>
</li>
<li>Java SDK - required for running of ANT scripts, and the
compilation of WSDL2Ws tool
<ul>
<li>Require version 1.4+</li>
</ul>
</li>
<li>Ant-Contrib - provide numerous extensions to ANT, including the
compilation of C/C++.
<ul>
<li>Available from <a href="http://ant-contrib.sourceforge.net">http://ant-contrib.sourceforge.net</a></li>
<li>Place JARs into <code>[ANT INSTALL DIR]/lib</code>.</li>
<li>Require both ant-contrib and cpptasks</li>
</ul>
</li>
<li>Doxygen - Used for generating API documentation
<ul>
<li>Available from <a href="http://www.doxygen.org">http://www.doxygen.org</a></li>
</ul>
</li>
<li>Compiler / Linker
<ul>
<li>For Windows - Microsoft Visual C++ v6</li>
<li>For Linux - gcc / g++</li>
<li>For AIX - IBM Visual Age for C++</li>
</ul>
</li>
</ul>
<h2><a name="thirdPartySoftware"></a>Getting necessary third party
software</h2>
<p>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.</p>
<p><b>Expat XML Parser</b></p>
<p>You can get expat binaries from <a
href="http://sourceforge.net/projects/expat/">http://sourceforge.net/projects/expat/</a>.</p>
<p><b>Xerces-C XML Parser</b></p>
<p>You can get Xerces-C binaries from <a
href="http://xerces.apache.org">http://xerces.apache.org</a>.</p>
<P><B>Apache</B></P><P>You can get Apache 1.3 or 2.0 from <A
href="http://httpd.apache.org/">http://httpd.apache.org/</A></P>
<H2><A name="PropertyFiles"></A>Property Files</H2>
<P>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 <CODE>ws-axis/c</CODE> with the following naming convention:</P>
<BLOCKQUOTE><CODE>build.<I>[platform]</I>.properties</CODE></BLOCKQUOTE>
<P>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.</P>
<P>These property files also allow you to make some selection on which artefacts will be produced by the build:</P>
<UL>
<LI>Select which XML Parsers to use:
<UL>
<LI>For each one to be built, set the following to true:<BR>
<CODE>xmlParser.xml4c</CODE><BR>
<CODE>xmlParser.xerces</CODE><BR>
<CODE>xmlParser.expat</CODE></LI>
</UL>
</LI>
<LI>Select which transport implementation to use:<UL>
<LI>For each one to be built, set the following to true:<BR>
<CODE>transport.axis</CODE><BR>
<CODE>transport.axis2</CODE><BR>
<CODE>transport.libwww</CODE></LI>
</UL>
</LI>
<LI>Select which Apache module to produce:
<UL>
<LI>For each one to be built, set the following to true:<BR>
<CODE>server.apache13</CODE><BR>
<CODE>server.apache20</CODE></LI>
</UL>
</LI>
<LI>Select whether to build Simple Axis Server executable:
<UL>
<LI>If you wish to build this, set the following to true:<BR><CODE>server.simpleAxisServer</CODE>
</LI>
</UL>
</LI>
</UL>
<P>The default selections are Xerces as XML parser, axis2 transport implementation and both the Apache 1.3 and Apache 2.0 modules.</P>
<h2><A name="SettingTheEnvironment"></A>Setting the Environment</h2>
<P>Before running ANT the following environment variables must be
set:</P>
<UL>
<LI><CODE>ANT_HOME</CODE> - location of ant installation</LI>
<LI><CODE>JAVA_HOME</CODE> - location of java installation</LI>
<LI><CODE>PATH</CODE> - to include <CODE>[ANT_HOME]/bin</CODE> and <CODE>[JAVA_HOME]/bin</CODE>.
<UL>
<LI>Also ensure doxygen and compilers are available on the system
path.</LI>
</UL>
</LI>
</UL>
<P>The default property files make use of the following environment variables to locate the various third party software dependencies.</P>
<UL>
<LI><CODE>AXISJAVA_LIBS</CODE> - location of Axis Java JAR files, as required for WSDL2Ws tool</LI>
<LI><CODE>EXPAT_HOME</CODE> - location of Expat installation <I>(if
using Expat</I>)</LI>
<LI><CODE>XERCES_HOME</CODE> - location of Xerces installation (<I>if
using Xerces</I>)</LI>
<LI><CODE>XML4C_HOME</CODE> - location of XML4C installation (<I>if
using XML4C</I>)</LI>
<LI><CODE>APACHE_HOME</CODE> - location of Apache 1.3 installation (<I>if
building Apache 1.3 module</I>)</LI>
<LI><CODE>APACHE2_HOME</CODE> - location of Apache 2.0 installation (<I>if
building Apache 2.0 module</I>)</LI>
</UL>
<h2><a name="cvsExtract"></a>Getting a CVS checkout</h2>
<p>Visit <a href="windows/cpp/">http://ws.apache.org/</a> Click on
“axis” and then on “CVS Repository” to find details on how to access
the
CVS Repository. <br>
In short summary:<br>
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): </p>
<blockquote><code>cvs -d
:pserver:anoncvs@cvs.apache.org:/home/cvspublic
login<br>
password: anoncvs<br>
<br>
cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout ws-axis</code></blockquote>
<p>The checkout of the repository will be created in the current
directory
in a folder named “<code>ws-axis</code>”<br>
<br>
The checked out folder ws-axis/c will be referred to as <code>[CHECKOUT_HOME]</code>
from this point on.</p>
<h2><a name="runningTheBuild"></a>Running the ANT build</h2>
<P>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 <CODE>[CHECKOUT_HOME]</CODE> and run:</P>
<blockquote><code>ant</code></blockquote>
<p>This will carry out the following:</p><ul>
<li>Build Axis C Client library</li>
<li>Build Axis C Transport library
<UL>
<LI>Axis, axis2, libwww configurable through the property files</LI>
</UL>
</li>
<li>Build Axis C XML Parser library
<ul>
<li>Expat, Xerces-C, etc configurable through the property files</li>
</ul>
</li>
<li>Build Axis C Server library</li>
<LI>Build Axis C Apache module<UL>
<LI>Apache 1.3 or Apache 2.0 configurable through the property files</LI>
</UL>
</LI>
<LI>Build Axis C Simple Server Executable<UL>
<LI>Configurable through the property files</LI>
</UL>
</LI>
<LI>Build and package WSDL2Ws tool</LI>
<li>Generate API Documentation</li>
<li>Package artefacts into a distributable structure
<ul>
<li>This structure is configurable through the property files</li>
</ul>
</li>
<li>Validate all artefacts have been correctly generated</li>
</ul>
<P>The second step is to package the generated artefacts. From <CODE>[CHECKOUT_HOME]</CODE> run:</P>
<blockquote><CODE>ant -f package.xml</CODE></blockquote>
<P>This will carry out the following:</P>
<UL>
<LI>Package artefacts in to a binary release distributable</LI>
<LI>Package artefacts in to a source release distributable</LI>
</UL>
<p>To remove artefacts from a previous build use the following command:
</p>
<BLOCKQUOTE><CODE>ant clean</CODE></BLOCKQUOTE>
<h2><A name="EnablingTraceAndDebug"></A>Enabling Trace and Debug</h2>
<p>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:</p>
<BLOCKQUOTE><CODE>ant buildWithTrace</CODE></BLOCKQUOTE>
<BLOCKQUOTE><CODE>ant buildWithDebug</CODE></BLOCKQUOTE>
<BLOCKQUOTE><CODE>ant buildWithTraceAndDebug</CODE></BLOCKQUOTE>
<P>The packaging step remains the same. Although it the source release package will automatically select the trace instrumented source code.</P>
<P>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.</P>
<h2><a name="addingExtraPlatform"></a>Adding an extra platform</h2>
<p>The AXIS community would greatly appreciate your input, if you're
working on a platform not currently supported by the ANT scripts.<br>
Below, are the steps required to add an additional platform;</p>
<ol>
<li>Add platform detection to <code>pre-init</code> target in <CODE>buildIntialize.xml</CODE>, eg:
<pre><condition property="linux"><br> <os name="Linux"/><br></condition></pre>
</li>
<li>Update platform property within <code>initialize</code> target in <CODE>buildIntialize.xml</CODE>,
eg:
<pre><condition property="platform" value="Linux"><br> <isset property="linux"/><br></condition></pre>
</li>
<li>Provide an additional property file in <code>ws-axis/c</code> to
match your platform. This uses the naming convention <code>build.[<i>platform</i>].properties</code>,
where platform is as specified in step 2.</li>
<li>Provide <code>compiler</code> definition for platform in <CODE>buildIntialize.xml</CODE>, include a
condition check for the correct platform and any debug flags should be conditional on the debug property being set, eg:
<pre><compiler id="Linuxgcc" name="g++" if="linux"><br> <compilerarg value="-g" if="debug"/>
<compilerarg value="-Wall"/><br> <compilerarg value="-Wshadow"/><br> <compilerarg value="-O2"/><br> <defineset><br> <define name="ENABLE_AXIS_EXCEPTION"/><br> <define name="HAVE_CONFIG_H"/><br> <define name="PIC"/><br> </defineset><br> <includepath path="${dir.include}"/><br></compiler></pre>
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.</li>
<li>Provide <code>linker</code> definition for platform in <CODE>buildIntialize.xml</CODE>, include a
condition check for the correct platform and any debug flags should be conditional on the debug property being set, eg:
<pre><linker id="LinuxLinker" name="g++" libtool="true" if="linux"><br> <linkerarg value="-g" if="debug"/><br> <libset libs="stdc++"/><br></linker></pre>
Note: As for compilers, linkers may extend one another.</li>
<li>Add new <code>compiler</code> and <code>linker</code> to the <code>cc</code>
task within each of <code>compileAxisClient</code>, <code>compileAxisTransport</code>, <code>compileAxisXMLParser</code>, <code>compileSimpleAxisServer</code>, <code>compileAxisServerEngine</code>, <code>compileApache13Module</code> and <code>compileApache20Module</code> targets, eg:
<pre><cc outfile="${dir.bin}/${transportLibraryName}" objdir="${dir.objects}"<br> exceptions="true" failonerror="false" outtype="shared" multithreaded="true"><br> <!-- Compilers --><br><FONT
color="green"> <compiler refid="Linuxgcc"/></FONT><br> <compiler refid="AIXxlc"/>
...<br> <!-- Linkers --><br> <FONT
color="green"><linker refid="LinuxLinker"/></FONT><br> <linker refid="AIXLinker"/><br> ...<br></cc></pre>
</li>
</ol>
</body>
</html>