Apache Axis2/C - Installation Guide

This document guides you on how to install Axis2/C, and run the server and client samples on Linux and Microsoft Windows operating systems.

This release comes in two forms, source and binary. This document covers both forms.

Please send your feedback to the developer mailing list: axis-c-dev@ws.apache.org (Subscription details are available on the Axis2 site.) Please remember to prefix the subject with [Axis2].

Installing and Running on Linux
- Using the Binary Release
- Using the Source Release
Installing and Running on Microsoft Windows (win32)
- Using the Binary Release
- Using the Source Release

1. Installing and Running on Linux

This can be done using binary or source distributions. (Download the two distributions)

To get both the binary and source distributions working, you need Libxml2.

Note: Most Linux systems have Libxml2 installed by default. On MS Windows, you need to download and install Libxml2.

1.1. Installing the Binary Distribution

The following steps have to be followed to install and run the Axis2/C binary distribution on Linux :

Extract the binary tar package to a folder.
Set the AXIS2C_HOME environment variable pointing to the location where you have extracted Axis2/C
- AXIS2C_HOME='/your_path_to_axis2c'
- export AXIS2C_HOME
Run the simple axis server:
- To start the simple axis server on the default port 9090, run the following commands.
  - cd /your_path_to_axis2c/bin
  - ./axis2_http_server
- To see the possible command line options run ./axis2_http_server -h
  Note: If you run into shared library problems, try setting the LD_LIBRARY_PATH to include the lib folder containing the Axis2/C libs.
  - LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib
  - export LD_LIBRARY_PATH
Run the sample clients in a new shell
- cd /your_path_to_axis2c/bin/samples
- To run the client for echo service
  - ./echo
- To run the client for math service
  - ./math
- To see the possible command line options for the sample clients, run them with the '-h' option

1.2. Installing the Source Distribution

The following steps have to be followed to install and run Axis2/C using the source distribution on Linux :

Extract the source tar package to a folder.
Set the AXIS2C_HOME environment variable pointing to the location where you want to install Axis2/C
- AXIS2C_HOME='/your_desired_path_to_axis2c_installation'
- export AXIS2C_HOME
Then go to the folder where you extracted the source.
- cd /your_path_to_axis2c_source
Build the source
- This can be done using the following command sequence, in the directory where you have extracted the source:
  - ./configure
  - make
  - make install
- Use ./configure --help for possible command line options.
- Note: If you do not provide a --prefix configure option, the default installation would be in the /usr/local/axis2c directory.
- You may have to try Axis2/C with Guththila XML parser. You can do that by providing the --enable-guththila=yes option when configuring.
  - ./configure --enable-guththila=yes [other configuration options]
  - make
  - make install
- If you want to get the samples working, you have to build the samples.
  
  To build the samples:
  - LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path_you_installed_axis2c/lib/
  - export LD_LIBRARY_PATH
  - cd samples
  - ./configure --prefix=${AXIS2C_HOME} --with-axis2=${AXIS2C_HOME}/include/axis2-1.2
  - make
  - make install
- Please run ./configure --help in the samples folder for more information on the configure options.
- Note: If you do not provide a --prefix configure option, by default, the samples will be installed into the "/usr/local/axis2c/bin/samples" directory.
Go to where you installed Axis2/C.
Start the simple axis server.
- To start the simple axis server on port 9090, run the following command lines.
  - cd /path_you_installed_axis2c/bin
  - ./axis2_http_server
- To see the possible command line options, run ./axis2_http_server -h
- Note: You may have to be logged in as a superuser to run the simple axis server if you installed Axis2/C as a super user.
Run the sample clients in a new shell using the following command lines.
- cd /path_you_installed_axis2c/bin/samples
- To run the client for the echo service
  - ./echo
- To run the client for the math service
  - ./math
- To see the possible command line options for the sample clients, run them with the '-h' option

2. Installing and Running on Microsoft Windows

This too can be done using binary or source distributions. (Download the two distributions.)

For both binary and source distributions, you have to download Libxml2, if you are not using Guththila parser which comes with the distribution.

2.1. Installing the Binary Distribution

2.1.1. Requirements

The binaries shipped with this version are compiled with the Microsoft Visual Studio compiler (cl)

(Note: you can download the Microsoft VSExpress2005 edition from the Microsoft Web site and install it to run these binaries.)

You also need the following DLLs:
- libxml2.dll [http://www.zlatkovic.com/pub/libxml/ - download the version >= libxml2-2.6.27.win32] (optional - required only if you are not using Guththila parser)
- iconv.dll [http://www.zlatkovic.com/pub/libxml/ - download the version >= iconv-1.9.1.win32]
- zlib1.dll [http://www.zlatkovic.com/pub/libxml/ - download the version >= zlib-1.2.3.win32]

2.1.2. Binaries in the Release

Extract the binary distribution to a folder of your choice. (example: C:\axis2c)
The C:\axis2c folder structure is as follows:

$Figure: c:\axis2c Folder Structure$

The above folders contain the following files:

bin - server and other executables
bin\samples - client samples
lib - library modules
services - deployed services
modules - deployed modules
include - all Include files of Axis2/C
logs - system and client logs are written to this folder

Copy libxml2.dll, iconv.dll, and zlib1.dll downloaded to C:\axis2c\lib

2.1.3. Running the Binaries

First, you need to set a couple of environment variables before you can run the server and samples.
- Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c)
- Add the path to the lib directory to the PATH variable (%AXIS2C_HOME%\lib)
Now everything is set to run the server.
C:\axis2c\bin\>axis2_http_server.exe
If the server is running successfully, you will see the message "Started Simple Axis2 HTTP Server..."
By default, the log is created in the %AXIS2C_HOME%\logs folder with the name axis2.log.
(Note: You can provide command line options to change the default behavior. Use the command axis2_http_server.exe -h to learn about the usage)
Now you can run any sample client located in %AXIS2C_HOME%\bin\samples\
- Example: C:\axis2c\bin\samples\> echo.exe

2.2. Installing the Source Distribution

2.2.1. Requirements

The makefile shipped with this version needs Microsoft Visual Studio Compiler (cl) and the NMake build tool.

(Note: You can download the Microsoft VSExpress2005 edition and Platform SDK from the Microsoft Web site. You will need to add the path to the Platform SDK Include and Lib folders to the makefile)

You also need
- libxml2 [http://www.zlatkovic.com/pub/libxml/ - download the version >= libxml2-2.6.27.win32] (optional - required only if you are not using Guththila parser)
- iconv [http://www.zlatkovic.com/pub/libxml/ - download the version >= iconv-1.9.1.win32]
- zlib [http://www.zlatkovic.com/pub/libxml/ - download the version >= zlib-1.2.3.win32]

2.2.2. Editing the configure.in File

Please edit the <source_distribution>\build\win32\configure.in file to include the following information.

The paths for the following required external libraries are specified in configure.in. Please note that you need to specify the path to the extracted folder.

libxml2 (required if you are not using Guththila) [LIBXML2_BIN_DIR]
iconv [ICONV_BIN_DIR]
zlib [ZLIB_BIN_DIR]

The default paths for these external libraries are already specified in configure.in file.

Example: If libxml2 is installed into C:\libxml2, edit the configure.in file accordingly.

You can either extract libxml2 to this folder, in which case the folder structure for C:\libxml2 should look like the following:

$Figure: C:\libxml2 Folder Structure$

Else, extract it to a location of your choice and edit the configure.in file accordingly.

If you need the parser to use Guththila XML parser, set the ENABLE_GUTHTHILA option to 1 in configure.in file.

Example: ENABLE_GUTHTHILA = 1

Other options available:

If you want to enable SSL client support, set ENABLE_SSL to 1 and set the path where OpenSSL is installed to OPENSSL_BIN_DIR.

If you want to enable libcurl based client transport, set ENABLE_LIBCURL to 1 and set the path where libcurl is installed to LIBCURL_BIN_DIR.

2.2.3. Compiling the Source

The following steps will take you through the source compilation.

Extract the source distribution to a folder of your choice. (Example: C:\axis2c)
Edit the configure.in file as explained in the section 2.2.3
Open a DOS shell
cd C:\axis2c\build\win32
to access .Net tools, run
- C:\axis2c\build\win32> vcvars32.bat
(Note: You may have to set the PATH environment variable to vcvars32.bat if MS Windows gives an error indicating that it cannot find this batch file. This file is located in <your MS Visual Studio install Directory>\VC\bin directory.)
To build the system and create the binary files in a directory named deploy under the build directory,
- C:\axis2c\build\win32>nmake install
The deploy folder structure is as follows:

Figure: deploy Folder Structure

The above folders contain the following files:

bin - server and other executable
bin\samples - client samples
lib - library modules
services - deployed services
modules - deployed modules
include - all include files of Axis2 C
logs - system and client logs are written to this folder

Please note that nmake install does not build the apache or the IIS module. Refer to Axis2/C manual to see how to install these modules.

2.2.4. Running the Binaries

You need to set a couple of environment variables before you can run the server and samples.
- Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c\build\deploy)
- Add the path to the lib directory to the PATH variable (%AXIS2C_HOME%\lib)
- Copy libxml2.dll, iconv.dll and zlib1.dll to Axis2/C lib folder (%AXIS2C_HOME%\lib)
Now run the server - C:\axis2c\build\deploy\bin> axis2_http_server.exe
If the server is running successfully, you will see the message "Started Simple Axis2 HTTP Server..."
By default, the log is created under the %AXIS2C_HOME%\logs folder with the name axis2.log.
(Note: You can provide command line options to change the default behavior. Use the command "axis2_http_server.exe -h" to learn about the usage)
Now you can run any sample client deployed under %AXIS2C_HOME%\bin\samples\
- Example: C:\axis2c\build\deploy\bin\samples> echo.exe