Table of Contents
=================

1. Getting Axis2/C working with the binary release on Linux
2. Getting Axis2/C working with the source release on Linux
3. Getting Axis2/C working with the binary release on Windows (win32)
    3.1 Requirements
    3.2 Binaries in the release
    3.3 Running the binaries
4. Getting Axis2/C working with the source release on Windows (win32)
    4.1 Requirements
    4.2 Editing Configure.in file
    4.3 Compiling the source
    4.4 Running the binaries
5. Installing Apache2 Web Server integration module (mod_axis2)
    

1. Getting Axis2/C working with the binary release on Linux.
============================================================

1. Extract the binary tar package to a directory.

2. Set AXIS2C_HOME environment variable pointing to the location where you have
   extracted Axis2/C
        AXIS2C_HOME='/your_path_to_axis2c'
        export AXIS2C_HOME

   NOTE: You will need to set AXIS2C_HOME only if you need to run Axis2/C
         samples or tests. The reason is that the samples and test codes use 
		 AXIS2C_HOME to get the path to Axis2/C. To write your own services or
		 clients this is not a requirement.

3. Run the simple axis server:
        cd /your_path_to_axis2c/bin
        ./axis2_http_server
   This will start the simple axis server on port 9090. To see the possible
   command line options run
        ./axis2_http_server -h

   NOTE: If you run into shared lib problems, set the LD_LIBRARY_PATH
        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib

4. Run the sample clients in a new shell
        cd /your_path_to_axis2c/bin/samples
        ./echo
   This will invoke the echo service.

        ./math
   This will invoke the math service.

   To see the possible command line options for sample clients run them with
   '-h' option

   NOTE: If you run into shared lib problems, set the LD_LIBRARY_PATH
        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib


2. Getting Axis2/C working with the source release on Linux.
============================================================

1. Extract the source tar package to a directory

2. Set 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

   NOTE: You will need to set AXIS2C_HOME only if you need to run Axis2/C 
         samples or tests. The reason is that the samples and test codes use 
		 AXIS2C_HOME to get the path to Axis2/C. To write your own services or
		 clients this is not a requirement.

3. Go to the directory where you extracted the source
        cd /your_path_to_axis2c_source

4. Build the source
   This can be done by running the following command sequence in the directory
   where you have extracted the source.

        ./configure --prefix=${AXIS2C_HOME}
        make
        sudo make install

   Please run './configure --help' in respective sub folders for more
   information on these configure options. 

   NOTE: If you don't provide the --prefix configure option, it will by default
         be installed into '/usr/local/axis2c' directory.

   You could run 'make check' to test if everything is working fine. However,
   note that the test/core/clientapi/test_clientapi program would fail unless
   AXIS2C_HOME points to the installed location. (It's looking for Axis2/C 
   repository)  This means you really should run 'make && make install', 
   then set 'AXIS2C_HOME=/path/to/install', and then 'make check'.  
   That's a little different than the usual 'make && make check && make
   install' process.

   You may need to try Axis2/C with Libxml2 xml parser. You can do it by giving
   '--enable-libxml2=yes' as a configure option.
    
        ./configure --enable-libxml2=yes [other configuration options]
        make
        sudo make install

   If you need to get the samples working, you also need to build the samples.
   
   To build the samples:

        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/axis2c/lib/
        cd samples
        ./configure --prefix=${AXIS2C_HOME} --with-axis2=${AXIS2C_HOME}/include/axis2-1.4.0
        make
        sudo make install

   Please run './configure --help' in samples folder for more information on
   configure options.

   NOTE: If you don't provide a --prefix configure option, samples will by default
         be installed into '/usr/local/axis2c/samples' directory.

5. Go to the folder where you installed Axis2/C.

6. Start simple axis server
        cd ${AXIS2C_HOME}/bin
        ./axis2_http_server

   This will start the simple axis server on port 9090. To see the possible command
   line options run:
        ./axis2_http_server -h

   NOTE: You may need to be login as superuser to run the simple axis server.

8. Run the sample clients in a new shell
        cd ${AXIS2C_HOME}/bin/samples
        ./echo
   This will invoke the echo service.

        ./math
   This will invoke the math service.

   To see the possible command line options for sample clients, run them with
   '-h' option.


3. Getting Axis2/C working with the binary release on Windows.
==============================================================

3.1 Requirements
----------------

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

    Note: You can download Microsoft VS Express2005 Edition from Microsoft 
          website and install it to run these binaries

    * You also need the following dlls
        - iconv.dll [http://www.zlatkovic.com/pub/libxml - version >= iconv-1.9.1.win32]
        - zlib1.dll [http://www.zlatkovic.com/pub/libxml - version >= zlib-1.2.3.win32]
	
	* You might optionally need the following dlls
	    - libxml2.dll [http://www.zlatkovic.com/pub/libxml - version >= libxml2-2.6.20.win32]

3.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.

    axis2c
      |
      +- bin         - server and other executables
      |   |
      |   +- samples - samples go here
      |         |
      |         +...
      |
      |
      +- docs        - documentation 
      |
      +- include     - all include files of axis2 
      |
      +- lib         - library modules
      |
      +- logs        - system and client logs are written to this folder
      |
      +- modules     - deployed modules 
      |
      +- samples     - source files of the samples in bin
      |
      +- services    - deployed services 
      
    Copy the downloaded iconv.dll and zlib1.dll to C:\axis2c\lib
	You might optionally require to copy the libxml2.dll as well
    (Or you can have these dll's some other place and add the location to PATH 
     environment variable)


3.3 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)
    Add the path to lib directory to the PATH variable (%AXIS2C_HOME%\lib)

    Now everything is set to run the server!

    C:\axis2c\bin>axis2_http_server.exe 

    You should see the message:
        Started Simple Axis2 HTTP Server...

    By default the log is created under %AXIS2C_HOME%\logs folder with the name
    axis2.log.

    NOTE: You may provide command line options to change the default behaviour.
    Type '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\bin\samples>echo.exe


4. Getting Axis2/C working with the source release on Windows.
============================================================

4.1 Requirements
----------------

    * The makefile shipped with this version needs Microsoft Visual Studio 
      compiler (cl) and nmake build tool 
    
    NOTE: You can download Microsoft VS Express2005 Edition and Platform SDK from
          Microsoft website. You will need to add the path to Platform SDK Include
          and Lib folders to the makefile.

    * You also need 
        - 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]
	
	* You might optionally need the following dlls
	    - libxml2.dll [http://www.zlatkovic.com/pub/libxml - version >= libxml2-2.6.20.win32]

4.2 Editing configure.in file
-----------------------------

    The default places for iconv and zlib are specified in configure.in. 

    Example:
    Default location for zlib is C:\zlib
        You can either extract zlib to this folder. Folder structure should 
        look like the following.
        C:\zlib
            |
            +- include
            |
            +- bin
            |
            +- lib

    Or extract to whatever place of your choice and edit the configure.in
	accordingly.

    You need to have zlib1.dll in a library path.

	In order to use the Libxml2 xml parser set 'ENABLE_LIBXML2 = 1'. This will
	require you specifying the path to libxml2.

4.3 Compiling the source
------------------------

    Extract the source distribution to a folder of your choice.
	(Example: C:\axis2c)
    Open a DOS shell and type:
        cd C:\axis2c\build\win32
        C:\axis2c\build\win32>vcvars32.bat
                       to access .Net tools
                       (Note: You may need to set the PATH environment
                       variable to  vcvars32.bat if Windows complains 
                       that it cannot find this bat)
        C:\axis2c\build\win32>nmake install

    That's it! This will build the system and create a directory named 'deploy'
    under the build directory.

    The deploy folder structure is as follows.

    deploy
      |
      +- bin         - server and other executables
      |   |
      |   +- samples - samples go here
      |         |
      |         +...
      |
      +- lib         - library modules
      |
      +- services    - deployed services 
      |
      +- modules     - deployed modules 
      |
      +- include     - all include files of axis2 
      |
      +- logs        - system and client logs are written to this folder

4.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 lib directory to the PATH variable (%AXIS2C_HOME%\lib)

    Copy iconv.dll and zlib1.dll to the Axis2/C lib folder
    (%AXIS2C_HOME%\lib)

	You might optionally require to copy the libxml2.dll to the Axis2/C lib
	folder (%AXIS2C_HOME%\lib)

    Now everything is set to run the server!

    C:\axis2c\build\deploy\bin>axis2_http_server.exe 

    You should see the message
        Started Simple Axis2 HTTP Server...

    By default, the log is created under %AXIS2C_HOME%\logs folder with the 
    name axis2.log.
    (Note: You may provide command line options to change the default
	behaviour. Type '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


5. Installing Apache2 Web Server integration module (mod_axis2)
---------------------------------------------------------------

5.1 Building mod_axis2 from the source tree 

5.1.1 On the Linux Platform

    Provide the Apache2 include file location as a configure option
        ./configure --with-apache2="<apache2 httpd include files location>" [other configure options]

    NOTE: Some apache2 distributions install APR (Apache Portable Run-time) 
    include files in a separate location which is required to build mod_axis2.
    In that case use:
        ./configure --with-apache2="<apache2 directornclude files location>>" 
            --with-apr="<apr include files location>" [other configure options]

    Then build the source tree
        make
        make install

    This will install mod_axis2.so into your "<your_path_to_axis2c>/lib"

5. 1.4.0 On Win32 platform

    Provide the apache2 location in configure.in file in APACHE_INSTALL_DIR
    Example:
    APACHE_INSTALL_DIR = E:\Apache

    After compiling the sources (as described in section 4.3) build the
    mod_axis2.dll by issuing the command 'nmake axis2_apache_module'.
    This will build mod_axis2.dll and copy it to %AXIS2C_HOME%\lib directory.
    Example:
    C:\axis2c\build\deploy\lib 

5.2 Deploying in Apache2 Web Server

    NOTE: To do the following tasks, you might need super user privileges in your 
          machine.

    Copy the mod_axis2 (libmod_axis2.so.0.3.1 on Linux and mod_axis2.dll
	in Windows) to "<apache2 modules directory>" as mod_axis2.so 
    Example:
    cp $AXIS2C_HOME/lib/libmod_axis2.so.0.3.1 /usr/lib/apache2/modules/mod_axis2.so
        in Linux or

    copy C:\axis2c\build\deploy\lib\mod_axis2.dll C:\Apache2\modules\mod_axis2.so
        in Windows

    Edit the Apache2's configuration file (generally httpd.conf) and add the
    following directives

    LoadModule axis2_module <apache2 modules directory>/mod_axis2.so
    Axis2RepoPath <axis2 repository path>
    Axis2LogFile <axis2 log file path>
    Axis2MaxLogFileSize <maximum size of log file>
    Axis2LogLevel LOG_LEVEL
    <Location /axis2>
        SetHandler axis2_module
    </Location>

    NOTE: Axis2 log file path should have write access to all users because by
          default Apache Web Server runs as nobody.
    NOTE: If you want to use a Shared Global Pool with Apache you have to give
	      another entry called Axis2GlobalPoolSize.You have to give the size of
		  the shared global pool in MB.If you doesn't set the value or if you
		  set a negative value Apache module doesn't create shared global pool.
        
          Axis2GlobalPoolSize <global pool size in MB>        

    LOG_LEVEL can be one of following
        crit - Log critical errors only
        error - Log errors critical errors
        warn - Log warnings and above
        info - Log info and above
        debug - Log debug and above (default)
        trace - Log trace messages

    NOTE: Use forward slashes "/" for path separators in
	      <apache2 modules directory>, <axis2 repository path> and
		  <axis2 log file path>

    Make sure that the apache2 user has the correct permissions to above paths
        - Read permission to the repository
        - Write permission to the log file

    Restart apache2 and test whether mod_axis2 module is loaded by typing the URL
        http://localhost/axis2/services


6. Installing IIS (Interner Information Server) integration module (mod_axis2_IIS)
----------------------------------------------------------------------------------

6.1 Building mod_axis2_IIS from the source tree

    After compiling the sources (as described in section 4.3) build the
    mod_axis2.dll by issuing the command 'nmake axis2_IIS_module'.
    This will build the mod_axis2_IIS.dll and copy it to %AXIS2C_HOME%\lib
	directory.
    Example:
    C:\axis2c\build\deploy\lib 

6.2 Deploying in the IIS
    
    Add the following key to the registery.

    HKEY_LOCAL_MACHINE\SOFTWARE\Apache Axis2c\IIS ISAPI Redirector

    Under this registry key add the following entries.

    Add a string value with the name axis2c_home and a value of the axis2c home
	path
	Example: c:\axis2c
    Add a string value with the name log_file and a value of absolute path of
	the log file
	Example: c:\axis2c\logs\axis2.log
    Add a string value with the name log_level. The value can be one of the
	following		
		trace    - Log trace messages
 		error    - Log errors critical errors
 		info     - Log info and above
 		critical - Log critical errors only 
		debug	 - Log debug and above (default)
	 	warning  - Log warnings

    Using the IIS management console, add a new virtual directory to the
	IIS/PWS web site called "axis2" The physical path of this virtual
	directory should be the axis2\lib directory (Where the mod_axis2_IIS.dll
	is in)
    Assign excecute permissions to this virtual directory.

    Using the IIS management console, add mod_axis2_IIS.dll as a filter to the
	IIS/PWS web site. The name of the filter can be any meaningful name. 

    Restart IIS and test whether mod_axis2_IIS module is loaded by typing the
	URL http://localhost/axis2.
    Enjoy Axis2/C!


FAQ
===

1. Although I was able to get simple axis server up, unable to run samples.

        This could happen because the AXIS2C_HOME environment variable is not 
        set to the correct axis2 installation path.


2. What are the other dependencies Axis2/C has?
     
        Basically if you are willing to use libxml2 as your parser, you need to
        have it installed on your system. 
        libxml2 - http://xmlsoft.org/downloads.html

3. I installed libxml2 installed in my system, but ./configure fails saying
   "libxml2 not found"

        Yes, you need to install libxml2-dev packages. 
        
        1. If you are using a debian based system
                apt-get install libxml2-dev
        2. If you are using redhat/fedora based system.
                yum install libxml2-dev
        3. If you compile libxml2 from source you will not get this error.

4. Is there any recommended packages, that I need to instal in my system?

        1. automake, autoconf, libtool, aclocal
        2. libxml2 and libxml2-dev
        5. pkg-config
          
5. I tried several methods, browse through axis-c-dev and axis-c-user mail 
   archives but I was not able solve it.

        Then you can ask from Axis2/C users or Axis2/C developers about it by
        sending your question to 
            user      = axis-c-user@ws.apache.org    
            developer = axis-c-dev@ws.apache.org 

        You can get subscribe to

            axis-c-user list by sending request to  
                <axis-c-user-subscribe@ws.apache.org>

            axis-c-dev  list by sending request to  
                <axis-c-dev-subscribe@ws.apache.org>

            subject of the request should be "subscribe"


6. This FAQ is not enough...
       
       You can help us by reporting your suggestions, complaints, problems and bugs


Thank you for using Axis2/C ...