INSTALL

The release comes in two forms, source and binary. 

To get both the binary and source distributions working, you need Libxml2 from
http://xmlsoft.org/downloads.html

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

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 guththila xml parser. You can do it by giving
   "--enable-guththila=yes" as a configure option.
    
        ./configure --enable-guththila=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_util=${AXIS2C_HOME}/include/axis2-1.0
            --with-axiom=${AXIS2C_HOME}/include/axis2-1.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
        - libxml2.dll [http://www.xmlsoft.org - version >= libxml2-2.6.20.win32]
        - iconv.dll [http://www.xmlsoft.org - version >= iconv-1.9.1.win32]
        - zlib1.dll [http://www.xmlsoft.org - version >= zlib-1.2.3.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
      |         |
      |         +...
      |
      |
      +- conf        - codegen config files
      |
      +- 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 libxml2.dll, iconv.dll and zlib1.dll to C:\axis2c\lib
    (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 
        - libxml2 [http://www.xmlsoft.org - download the version >=  libxml2-2.6.20.win32]
        - iconv [http://www.xmlsoft.org - download the version >= iconv-1.9.1.win32]
        - zlib [http://www.xmlsoft.org - download the version >= zlib-1.2.3.win32]

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

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

    Example:
    Default location for libxml2 is C:\libxml2
        You can either extract libxml2 to this folder. Folder structure should 
        look like the following.
        C:\libxml2
            |
            +- 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. You may copy this dll to libxml2/lib.

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 libxml2.dll, iconv.dll, and zlib1.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.2 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 the 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.0.0 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.0.0 /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>
    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.

    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 i.e c:\axis2c
    Add a string value with the name log_file and a value of absolute path of the log file i.e 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 the Axis2/C soap engine!


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