Google Git
Sign in
apache / axis-axis2-c-core / refs/tags/0.94 / . / xdocs / docs / installationguide.html
blob: 7002b4be6c31f4572f23e480d8d4ab39ca22607c [file] [log] [blame]
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Axis2-C Installation Guide</title>
<meta name="generator" content="amaya 9.51, see http://www.w3.org/Amaya/" />
</head>
<body xml:lang="en">
<h1>Axis2/C Installation Guide</h1>
<p>This document will guide you on how to install Axis2/C and run the server
and client samples on Linux and Microsoft Windows operating systems.</p>
<p>This release comes in two forms, source and binary. Instructions are given
below to install using any of those two forms.</p>
<p>Please send your feedback to the developer mailing list: <a
href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a> (please
remember to prefix the subject with [Axis2]). To subscribe to developer
mailing list see <a href="../mail-lists.html">here</a></p>
<h2>Contents</h2>
<ul>
<li><a href="#linux">Installing and running on Linux</a>
<ul>
<li><a href="#linux_binary">Using binary release</a></li>
<li><a href="#linux_source">Using source release</a></li>
</ul>
</li>
<li><a href="#win">Installing and running on Microsoft Windows (win32)</a>
<ul>
<li><a href="#win_binary">Using the binary release</a>
<ul>
<li><a href="#bin_req">Requirements</a></li>
<li><a href="#bin_binaries">Binaries in the release</a></li>
<li><a href="#bin_run">Running the binaries</a></li>
</ul>
</li>
<li><a href="#win_source">Using the source release</a>
<ul>
<li><a href="#src_req">Requirements</a></li>
<li><a href="#edit">Editing Configure.in file</a></li>
<li><a href="#src_compile">Compiling the source</a></li>
<li><a href="#src_run">Running the binaries</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#installing-apache2">Installing Apache2 Web Server integration
module (mod_axis2)</a>
<ul>
<li><a href="#building-apache2">Building mod_axis2 from source
tree</a></li>
<li><a href="#deploying-apache2">Deploying in Apache2 Web
Server</a></li>
</ul>
</li>
</ul>
<a id="linux"></a>
<h2>1. Installing and running on Linux</h2>
<p>This can be done using binary or source distributions</p>
<p>To get both the binary and source distributions working, you need libxml2,
which can be downloaded from <a
href="http://xmlsoft.org/downloads.html">here</a>.</p>
<p><b>NOTE:</b> Most Linux systems have libxml2 installed by default. On
Windows you need to download and install libxml2.</p>
<a id="linux_binary"></a>
<h3>1.1. Using binary release</h3>
<p>The following steps need to be taken to install and run Axis2/C using
binary distribution on Linux</p>
<ol>
<li>Extract the binary tar package to a folder.</li>
<li>Set AXIS2C_HOME environment variable pointing to the location where you
have extracted Axis2C</li>
<ul>
<li>AXIS2C_HOME='/your_path_to_axis2c'</li>
<li>export AXIS2C_HOME</li>
<br />
<li><strong>NOTE:</strong> You will need to set AXIS2C_HOME only if you
need to run Axis2C samples or tests. The reason is that the samples and
test codes use AXIS2C_HOME to get the path to Axis2C. To write your own
services or clients this is not a requirement.</li>
</ul>
<li>Run the simple axis server:</li>
<ul>
<li>To start the simple axis server on default port 9090, run the following
commands.
<ul>
<li>cd /your_path_to_axis2c/bin</li>
<li>./axis2_http_server</li>
</ul>
</li>
<li>To see the possible command line options run ./axis2_http_server -h</li>
<br />
<li><strong>NOTE:</strong> If you run into shared lib problems, try setting
the LD_LIBRARY_PATH
<ul>
<li>export
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
</ul>
</li>
</ul>
<li>Run the sample clients in a new shell</li>
<ul>
<li>cd /your_path_to_axis2c/bin/samples</li>
<li>to run client for echo service
<ul>
<li>./echo</li>
</ul>
</li>
<li>to run client for math service
<ul>
<li>./math</li>
</ul>
</li>
<li>To see the possible command line options for sample clients run them
with '-h' option</li>
<br />
<li><strong>NOTE:</strong> If you run into shared lib problems, try setting
the LD_LIBRARY_PATH
<ul>
<li>export
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
</ul>
</li>
</ul>
</ol>
<ai id="linux_source"></a>
<h3>2. Using source release</h3>
<p>The following steps need to be taken to install and run Axis2/C using
source distribution on Linux</p>
<ol>
<li>Extract the source tar package to a folder.</li>
<li>Set AXIS2C_HOME environment variable pointing to the location where you
want to install Axis2C.
<ul>
<li>AXIS2C_HOME='/your_desired_path_to_axis2c_installation'</li>
<li>export AXIS2C_HOME</li>
<br />
<li><strong>NOTE:</strong> You will need to set AXIS2C_HOME only if you
need to run Axis2C samples or tests. The reason is that the samples
and test codes use AXIS2C_HOME to get the path to Axis2C. To write
your own services or clients this is not a requirement.</li>
</ul>
</li>
<li>Then go to the folder where you extracted the source
<ul>
<li>cd /your_path_to_axis2c_source</li>
</ul>
</li>
<li>Build the source
<ul>
<li>This can be done using the following command sequence in the
directory where you have extracted the source:
<ul>
<li>./configure --prefix=${AXIS2C_HOME}</li>
<li>make</li>
<li>make install</li>
</ul>
</li>
<li>use './configure --help' for possible command line options.</li>
<li><strong>NOTE:</strong> If you don't provide a --prefix configure
option, it will by defaul be installed into /usr/local/axis2c
directory.</li>
<li>You may need to try axis2c with guththila xml parser. You can do it
by giving --enable-guththila=yes
<ul>
<li>./configure --enable-guththila=yes [other configuration
options]</li>
<li>make</li>
<li>make install</li>
</ul>
</li>
<li>In order to build rampart (axis2c security module)
<ul>
<li>./configure --enable-rampart=yes [other configuration
options]</li>
<li>make</li>
<li>make install</li>
</ul>
</li>
<li>If you need to get the samples working, you also need to build the
samples.
<br />To build the samples:
<ul>
<li>export
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/axis2c/lib/</li>
<li>cd samples</li>
<li>./configure --prefix=${AXIS2C_HOME}</li>
<li>--with-axis2_util=${AXIS2C_HOME}/include</li>
<li>--with-axiom=${AXIS2C_HOME}/include</li>
<li>make</li>
<li>sudo make install</li>
</ul>
</li>
<li>Please run "./configure --help" in samples folder for more
information on configure options.</li>
<li><strong>NOTE:</strong> If you don't provide a --prefix configure
option, samples will by default be installed into
"/usr/local/axis2c/samples" directory.</li>
</ul>
</li>
<li>Go to where you installed axis2c.</li>
<li>Start simple axis server
<ul>
<li>To start the simple axis server on port 9090 run the following
command lines
<ul>
<li>cd ${AXIS2C_HOME}/bin</li>
<li>./axis2_http_server</li>
</ul>
</li>
<li>To see the possible command line options run ./axis2_http_server
-h</li>
<li> <strong>NOTE:</strong> You may need to be login as superuser to
run the simple axis server.</li>
</ul>
</li>
<li>Run the sample clients in a new shell using the following command lines
<ul>
<li>cd ${AXIS2C_HOME}/bin/samples</li>
<li>to run client for echo service
<ul>
<li>./echo</li>
</ul>
</li>
<li>to run client for math service
<ul>
<li>./math</li>
</ul>
</li>
<li>To see the possible command line options for sample clients run
them with '-h' option</li>
</ul>
</li>
</ol>
<a id="win"></a>
<h2>Installing and running on Microsoft Windows (win32)</h2>
<p>This too can be done using either binary or source distributions</p>
<p>For both the binary and source distributions, you need libxml2 from <a
href="http://xmlsoft.org/downloads.html">here</a>.</p>
<p>(NOTE: most Linux systems has libxml2 by default. On Windows you need to
download and install libxml2)</p>
<a id="win_binary"></a>
<h3>1. Using binary release</h3>
<a id="bin_req"></a>
<h4>Requirements</h4>
<ul>
<li>The binaries shipped with this version is compiled with Microsoft
visual studio compiler (cl)</li>
<p>(Note: you can download Microsoft VSExpress2005 edition from Microsoft
web site and install it to run these binaries)</p>
<li>You also need the following dlls
<ul>
<li>libxml2.dll [http://www.xmlsoft.org - download the version &gt;=
libxml2-2.6.20.win32]</li>
<li>iconv.dll [http://www.xmlsoft.org - download the version &gt;=
iconv-1.9.1.win32]</li>
<li>zlib1.dll [http://www.xmlsoft.org - download the version &gt;=
zlib-1.2.3.win32]</li>
</ul>
</li>
</ul>
<a id="bin_binaries"></a>
<h4>Binaries in the release</h4>
<ul>
<li>Extract the binary distribution to a folder of your choice. (example:
C:\axis2c)</li>
<li>The C:\axis2c folder structure is as follows:</li>
<p><img alt="Figure: c:\axis2c Folder Structure"
src="images/binary_folder_structure.jpg" /></p>
<p><em>The above folders contain the following files:</em></p>
<ul>
<li>bin - server and other executables</li>
<li>bin\samples - client samples go here</li>
<li>lib - library modules</li>
<li>services - deployed services</li>
<li>modules - deployed modules</li>
<li>include - all include files of Axis2 C</li>
<li>logs - system and client logs are written to this folder</li>
</ul>
<li>Copy libxml2.dll, iconv.dll and zlib1.dll downloaded to
C:\axis2c\lib</li>
</ul>
<a id="bin_run"></a>
<h4>Running the binaries</h4>
<ul>
<li>First you need to set couple of environment variables before you can
run the server and samples.
<ul>
<li>Set the varibale AXIS2C_HOME to the deploy folder (C:\axis2c)</li>
<li>Add the path to lib directory to PATH variable
(%AXIS2C_HOME%\lib)</li>
</ul>
</li>
<li>Now everything is set to run the server (C:\axis2c\bin\&gt;
axis2_http_server.exe)</li>
<li>If the server is running successfully you should see the message
"Started Simple Axis2 HTTP Server..."</li>
<li>The log is by default created in %AXIS2C_HOME%\logs folder with the
name axis2.log.</li>
<li>(Note: you may provide command line options to change the default
behaviour. Use the command "axis2_http_server.exe -h" to learn about the
usage)</li>
<li>Now you can run any sample client located in %AXIS2C_HOME%\bin\samples\
<ul>
<li>Example: C:\axis2c\bin\samples\&gt; echo.exe</li>
</ul>
</li>
</ul>
<a id="win_source"></a>
<h3>2. Using the source release.</h3>
<a id="src_req"></a>
<h4>Requirements</h4>
<ul>
<li>The makefile shipped with this version needs Microsoft visual studio
compiler (cl) and nmake build tool</li>
<p>(Note: you can download Microsoft VSExpress2005 edition and Platform SDK
from Microsoft web site. You will need to add the path to Platform SDK
Include and Lib folders to makefile)</p>
<li>You also need
<ul>
<li>libxml2 [http://www.xmlsoft.org - download the version &gt;=
libxml2-2.6.20.win32]</li>
<li>iconv [http://www.xmlsoft.org - download the version &gt;=
iconv-1.9.1.win32]</li>
<li>zlib [http://www.xmlsoft.org - download the version &gt;=
zlib-1.2.3.win32]</li>
</ul>
</li>
</ul>
<a id="edit"></a>
<h4>Editing configure.in file</h4>
<ul>
<li>The default paths for libxml2 and iconv are speceficed in configure.in.
<ul>
<li>Example:Default location for libxml2 is C:\libxml2</li>
</ul>
</li>
<li>You can either extract libxml2 to this folder, in which case folder
structure for C:\libxml2 should look like the following.</li>
<p><img alt="Figure: C:\libxml2 Folder Structure"
src="images/folder_structure_libxml2.jpg" /></p>
<p>Or extract to whatever place of your choice and edit the configure.in
accordingly.</p>
<li>You need to have zlib1.dll in a library path. You may copy this dll to
libxml2/lib.</li>
</ul>
<a id="src_compile"></a>
<h4>Compiling the source.</h4>
<p>The following steps will take you through the source compilation</p>
<ul>
<li>Extract the source distribution to a folder of your choice. (Example:
C:\axis2c)</li>
<li>Open a DOS shell</li>
<li>cd C:\axis2c\build\win32</li>
<li>to access .Net tools, run
<ul>
<li>C:\axis2c\build\win32&gt; vcvars32.bat</li>
</ul>
<p>(Note: You may need to set the PATH environment variable to
vcvars32.bat if windows complaints that it cannot find this bat)</p>
</li>
<li>build the system and create a directory named deploy under build
directory:
<ul>
<li>C:\axis2c\build\win32&gt;nmake install</li>
</ul>
</li>
<li>The deploy folder structure is as follows:</li>
<p><img alt="Figure: deploy Folder Structure"
src="images/folder_structure.jpg" /></p>
<p><em>The above folders contain the following files:</em></p>
<ul>
<li>bin - server and other executables</li>
<li>bin\samples - client samples</li>
<li>lib - library modules</li>
<li>services - deployed services</li>
<li>modules - deployed modules</li>
<li>include - all include files of Axis2 C</li>
<li>logs - system and client logs are written to this folder</li>
</ul>
</ul>
<a id="src_run"></a>
<h4>Running the binaries</h4>
<ul>
<li>You need to set couple of environment variables before you can run the
server and samples.
<ul>
<li>Set the variable AXIS2C_HOME to the deploy folder
(C:\axis2c\build\deploy)</li>
<li>Add the path to lib directory to PATH variable
(%AXIS2C_HOME%\lib)</li>
<li>Copy libxml2.dll, iconv.dll and zlib1.dll to axis2c lib folder
(%AXIS2C_HOME%\lib)</li>
</ul>
</li>
<li>Now run the server - C:\axis2c\build\deploy\bin&gt;
axis2_http_server.exe</li>
<li>If server is running successfully you should see the message "Started
Simple Axis2 HTTP Server..."</li>
<li>The log is by default created under %AXIS2C_HOME%\logs folder with the
name axis2.log.</li>
<li>(Note: you may provide command line options to change the default
behaviour. Use the command "axis2_http_server.exe -h" to learn about the
usage)</li>
<li>Now you can run any sample client deployed under
%AXIS2C_HOME%\bin\samples\
<ul>
<li>Example: C:\axis2c\build\deploy\bin\samples&gt; echo.exe</li>
</ul>
</li>
</ul>
<a id="installing-apache2"></a>
<h3>3. Installing Apache2 Web Server integration module (mod_axis2).</h3>
<a id="building-apache2"></a>
<h4>3.1 Building mod_axis2 from source tree</h4>
<h4>3.1.1 On Linux Platform</h4>
<ul>
<li>Provide the apache2 include files location as configure option
./configure --with-apache2="&lt;apache2 include files location&gt;"
[other configure options] - Some apache2 distributions install APR
(Apache Portable Runtime) include files in a seperate location which is
requred to build mod_axis2. In that case use
<p>./configure --with-apache2="&lt;apache2 include files location&gt;"
--with-apr="&lt;apr include files location&gt;" [other configure
options]</p>
</li>
<li>Then build the source tree<br />
make<br />
make install<br />
- This will install mod_axis2.so into your
"&lt;your_path_to_axis2c&gt;/lib"</li>
</ul>
<h4>3.1.2 On Win32 platform</h4>
<ul>
<li>Provide the apache2 location in configure.in file in
APACHE_INSTALL_DIR<br />
eg : APACHE_INSTALL_DIR = E:\Apache</li>
<li>After compiling the sources (as described in section 2) build the
mod_axis2.dll by issuing the command "nmake axis2_apache_module".</li>
<li>This will build the mod_axis2.dll and copy it to %AXIS2C_HOME%\lib
directory.<br />
eg: C:\axis2c\build\deploy\lib</li>
</ul>
<a id="deploying-apache2"></a>
<h4>3.2 Deploying in Apache2 Web Server</h4>
<p><b>Note: To do the following tasks you might need super user privileges in
your machine.</b></p>
<ul>
<li>Copy the mod_axis2 (libmod_axis2.so.0.0.0 on Linux and mod_axis2.dll in
Windows) to "&lt;apache2 modules directory&gt;" (eg:
/usr/lib/apache2/modules in Linux or C:\Apache2\modules in Windows) as
mod_axis2.so
<p>eg: cp $AXIS2C_HOME/lib/libmod_axis2.so.0.0.0
/usr/lib/apache2/modules/mod_axis2.so<br />
copy C:\axis2c\build\deploy\lib\mod_axis2.dll
C:\Apache2\modules\mod_axis2.so</p>
</li>
<li>Edit the Apache2's configuration file (generally httpd.conf) and add
the following directive
<pre> LoadModule axis2_module &lt;apache2 modules directory&gt;/mod_axis2.so
&lt;Location /axis2&gt;
SetHandler axis2_module
RepoPath &lt;axis2 repository path&gt;
LogFile &lt;axis2 log file path&gt;
Axis2LogLevel LOG_LEVEL
&lt;/Location&gt;
</pre>
<p>LOG_LEVEL can be one of following <br />
AXIS2_LOG_LEVEL_CRITICAL - Log critical errors only <br />
AXIS2_LOG_LEVEL_ERROR - Log errors critical errors <br />
AXIS2_LOG_LEVEL_WARNING - Log warnings and above <br />
AXIS2_LOG_LEVEL_INFO - Log info and above <br />
AXIS2_LOG_LEVEL_DEBUG - Log debug and above (default) <br />
AXIS2_LOG_LEVEL_TRACE - Log trace messages</p>
</li>
<li>Use forward slashes "/" for path seperators in &lt;apache2 modules
directory&gt;, &lt;axis2 repository path&gt; and &lt;axis2 log file
path&gt;</li>
<li>Make sure that the apache2 user has correct permissions to above
paths<br />
- Read permission to the repository<br />
- Write permission to the log file</li>
<li>Restart apache2 and test whether mod_axis2 module is loaded by typing
the URL http://localhost/axis2/services</li>
</ul>
</body>
</html>