| Table of Contents | |
| ================= | |
| 1. Getting Axis2/C Working on Linux | |
| 1.1 Setting up Prerequisites | |
| 1.1.1 Mandatory | |
| 1.1.2 Optional | |
| 1.2 Using Binary Release | |
| 1.3 Using Source Release | |
| 1.3.1 Basic Build | |
| 1.3.2 Build with Options | |
| (a) With Guththila | |
| (b) With libxml2 | |
| 1.3.3 Building Samples | |
| 1.4 Running Samples | |
| 1.4.1 HTTP Transport | |
| (a) Server | |
| (b) Clients | |
| 2. Getting Axis2/C Working on Windows | |
| 2.1 RECOMMENDED: Windows Subsystem for Linux (WSL2) | |
| 2.2 Native Windows Build (Legacy - Unsupported since 2009) | |
| 3. Installing Apache2 Web Server Integration Module (mod_axis2) | |
| 3.1 Building mod_axis2 from Source | |
| 3.1.1 On Linux | |
| 3.1.2 On Windows (Win32) - LEGACY/UNSUPPORTED | |
| 3.2 Deploying in Apache2 Web Server | |
| 3.3 HTTP/2 Support (Optional) | |
| 4. Using Axis2/C with CGI | |
| 4.1 Deploying in Apache2 | |
| 5. FAQ | |
| Note: IIS/ISAPI integration (mod_axis2_IIS) was removed in 2026 after being | |
| unmaintained since 2009. Windows users should use WSL2 (see Section 2). | |
| 1. Getting Axis2/C Working on Linux | |
| =================================== | |
| 1.1 Setting up Prerequisites | |
| ---------------------------- | |
| 1.1.1 Mandatory | |
| -------------- | |
| By default Axis2/C is not dependent on any other software libraries. | |
| 1.1.2 Optional | |
| -------------- | |
| (a) libxml2 - http://www.xmlsoft.org/ | |
| (b) zlib - http://www.zlib.net/ | |
| (c) libiconv - http://www.gnu.org/software/libiconv/ | |
| (d) openssl - http://www.openssl.org/ | |
| (e) HTTP/2 Transport Support (New in 2.0.0) - To enable HTTP/2 transport: | |
| libnghttp2 >= 1.0.0 - HTTP/2 C library for protocol implementation | |
| openssl >= 1.0.0 - Required for HTTPS and HTTP/2 ALPN negotiation | |
| Ubuntu/Debian installation: | |
| $ sudo apt install libnghttp2-dev libnghttp2-14 libssl-dev | |
| RedHat/CentOS installation: | |
| $ sudo yum install libnghttp2-devel openssl-devel | |
| # OR for newer systems: | |
| $ sudo dnf install libnghttp2-devel openssl-devel | |
| Build with HTTP/2 support: | |
| $ ./configure \ | |
| --prefix=$(pwd)/deploy \ | |
| --enable-http2 \ | |
| --enable-json=yes \ | |
| --enable-tests \ | |
| --enable-ssl \ | |
| --with-apache2=/usr/include/apache2 \ | |
| --with-apr=/usr/include/apr-1.0 \ | |
| PKG_CONFIG_PATH=/usr/lib/pkgconfig:/usr/lib/x86_64-linux-gnu/pkgconfig \ | |
| APACHE2_HOME=/usr \ | |
| CFLAGS="$CFLAGS -DAXIS2_H2_JSON_ONLY_BUILD -DAXIS2_JSON_ENABLED -O2" \ | |
| CPPFLAGS="$CPPFLAGS -DAXIS2_H2_JSON_ONLY_BUILD -DAXIS2_JSON_ENABLED" \ | |
| LDFLAGS="$LDFLAGS -L/usr/lib/x86_64-linux-gnu" | |
| Note: HTTP/2 transport provides: | |
| - Enterprise-grade stream multiplexing (100 concurrent streams) | |
| - Memory-efficient large payload processing (50MB+) | |
| - Automatic protocol negotiation (HTTP/2 with HTTP/1.1 fallback) | |
| - Integration with Apache mod_http2 for production deployment | |
| 1.1.3 For WSDL2C Code Generator (New in 2.0.0) | |
| ----------------------------------------------- | |
| To build and use the WSDL2C code generator, you need: | |
| (a) libxml2-dev - Development headers for libxml2 | |
| Ubuntu/Debian: sudo apt install libxml2-dev | |
| RedHat/CentOS: sudo yum install libxml2-devel | |
| (b) pkgconf - pkg-config implementation for dependency detection | |
| Ubuntu/Debian: sudo apt install pkgconf | |
| RedHat/CentOS: sudo yum install pkgconfig | |
| The native C generator provides fast, reliable WSDL to C code generation | |
| for SOAP-based web services with minimal dependencies (libxml2 only). | |
| Complete development package installation for Ubuntu/Debian: | |
| $ sudo apt update | |
| $ sudo apt install libxml2-dev pkgconf autoconf \ | |
| automake libtool make gcc g++ libssl-dev zlib1g-dev | |
| For testing and development (optional): | |
| $ sudo apt install libgtest-dev valgrind | |
| Note: On modern Ubuntu/Debian systems, libgtest-dev provides pre-built | |
| libraries that are automatically detected by the build system. | |
| Note: Apache httpd web server is NOT required for unit tests or basic | |
| development. Axis2/C includes a built-in simple HTTP server for testing. | |
| Apache httpd is only needed for production deployment via mod_axis2 module | |
| (see section 3 for Apache2 Web Server Integration). | |
| For production mod_axis2 development (optional): | |
| $ sudo apt install apache2-dev libapr1-dev libaprutil1-dev | |
| 1.2 Using Binary Release | |
| ------------------------ | |
| (a) Extract the binary tar package to a directory. | |
| (b) 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. | |
| 1.3 Using Source Release | |
| ------------------------ | |
| 1.3.1 Basic Build | |
| ----------------- | |
| (a) Extract the source tar package to a directory | |
| (b) 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. | |
| (c) Go to the directory where you extracted the source | |
| $ cd /your_path_to_axis2c_source | |
| (d) 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 | |
| $ make install | |
| Please run './configure --help' in respective sub directories 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. | |
| 1.3.1.1 Convenience Build Scripts | |
| --------------------------------- | |
| For developers familiar with C project conventions, Axis2/C provides | |
| convenience scripts that automate the typical autotools build process: | |
| $ ./build_for_tests.sh # Build with testing enabled, http/2 omitted - see section 3.3 | |
| $ ./run_tests.sh # Run the full test suite (make check) | |
| $ ./run_native_codegen_tests.sh # Run only native WSDL2C generator tests | |
| These scripts handle the complete configure-make-install-test cycle with | |
| appropriate options for development and testing. They are equivalent to | |
| the traditional C development workflow of running autogen.sh, configure | |
| with various flags, make, make install, and running tests. | |
| For quick one-liners equivalent to the convenience scripts: | |
| Build and install with testing enabled (equivalent to build_for_tests.sh): | |
| $ ./autogen.sh && ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes && make -j4 && make install && export AXIS2C_HOME=$(pwd)/deploy | |
| Run full test suite (equivalent to run_tests.sh): | |
| $ export AXIS2C_HOME=$(pwd)/deploy && export ASAN_OPTIONS=detect_odr_violation=1 && make check | |
| Run only native WSDL2C generator tests (equivalent to run_native_codegen_tests.sh): | |
| $ cd tools/codegen/native/test && make clean && make check | |
| Build and basic install (no unit tests): | |
| $ make clean; ./autogen.sh && ./configure --prefix=$(pwd)/deploy --enable-json=yes && make -j4 && make install && export AXIS2C_HOME=$(pwd)/deploy | |
| These commands demonstrate the standard C autotools workflow that the | |
| convenience scripts automate for you. Note: --enable-json=yes is optional | |
| and only needed for REST API support (requires libjson-c-dev package). | |
| The build with testing requires proper Google Test setup for full coverage. | |
| 1.3.1.2 Development Workflow - Making Code Changes | |
| ------------------------------------------------- | |
| When modifying Axis2/C source code during development, you MUST rebuild | |
| AND reinstall before running tests, because tests use installed libraries | |
| from the ./deploy directory: | |
| After making source changes: | |
| $ make && make install # Rebuild and install updated libraries | |
| $ bash run_tests.sh # Run tests with updated code | |
| Or as one-liner: | |
| $ make && make install && bash run_tests.sh | |
| IMPORTANT: Simply running 'make' is not sufficient - tests will use old | |
| installed libraries in ./deploy/ until 'make install' copies the updated | |
| libraries there. This is different from most C projects where 'make check' | |
| tests the build tree directly. | |
| Role of build_for_tests.sh: | |
| ---------------------------- | |
| The build_for_tests.sh convenience script is designed for INITIAL setup | |
| and FULL rebuilds from scratch. It runs the complete configure-make-install | |
| cycle with proper testing options. For incremental development after making | |
| code changes, you only need 'make && make install' since configuration is | |
| already done. | |
| Use build_for_tests.sh when: | |
| - Setting up a fresh checkout | |
| - Changing build configuration options | |
| - Doing a complete clean rebuild | |
| Use 'make && make install' when: | |
| - Making incremental source code changes | |
| - Continuing development after initial setup | |
| - You want to test your modifications quickly | |
| 1.3.1.3 Build System Maintenance Commands | |
| --------------------------------------- | |
| During development and troubleshooting, you may need to use additional | |
| build system maintenance commands to resolve build issues or start with | |
| a completely clean environment: | |
| make distclean: | |
| -------------- | |
| This command removes ALL generated files and returns the source tree to | |
| its pristine state as if freshly extracted from a tar archive. Use this | |
| when you need to completely reset your build environment. | |
| What 'make distclean' removes: | |
| - All compiled object files (*.o, *.lo) | |
| - All generated libraries (*.a, *.la, *.so) | |
| - All generated executables and test programs | |
| - All Makefiles generated by configure | |
| - All autotools cache files (autom4te.cache/) | |
| - All configuration headers (config.h, stamp-h1) | |
| - All libtool files (libtool, .deps/, .libs/) | |
| - The deploy/ directory and all installed files | |
| Example usage: | |
| $ make distclean | |
| $ ./autogen.sh | |
| $ ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes | |
| $ make && make install | |
| autoreconf -fiv: | |
| --------------- | |
| This command regenerates the autotools build system files (configure script, | |
| Makefiles, etc.) from their source templates. The flags mean: | |
| -f: Force regeneration even if files seem up-to-date | |
| -i: Install missing auxiliary files | |
| -v: Verbose output showing what's being regenerated | |
| What 'autoreconf -fiv' regenerates: | |
| - configure script from configure.ac | |
| - Makefile.in files from Makefile.am templates | |
| - aclocal.m4 from macro definitions | |
| - config.h.in from autoheader | |
| - Missing auxiliary files (install-sh, missing, etc.) | |
| WHEN TO USE THESE COMMANDS: | |
| Use 'make distclean' followed by 'autoreconf -fiv' when: | |
| - Build system files appear corrupted or inconsistent | |
| - You've modified configure.ac or Makefile.am files | |
| - You're getting strange autotools-related errors | |
| - You want to completely start over with a clean slate | |
| - Switching between different development branches | |
| - Build fails with "file not found" errors for generated files | |
| Use 'make distclean' alone when: | |
| - You want to clean up disk space (removes deploy/ directory) | |
| - Preparing to create a clean source distribution | |
| - Build artifacts are causing issues but autotools files are OK | |
| Use 'autoreconf -fiv' alone when: | |
| - You've modified build system files (configure.ac, Makefile.am) | |
| - autotools files seem out of sync but you want to keep build artifacts | |
| - You get warnings about outdated autotools files | |
| Complete Clean Rebuild Sequence: | |
| ------------------------------- | |
| For the most thorough reset when troubleshooting build issues: | |
| $ make distclean # Remove all generated files | |
| $ autoreconf -fiv # Regenerate build system | |
| $ ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes | |
| $ make && make install # Build and install | |
| This sequence is equivalent to starting with a fresh source extraction | |
| but preserves any local source code modifications you've made. | |
| 1.3.2 Build with Options | |
| ------------------------ | |
| (a) With Guththila | |
| ------------------ | |
| - Now Guththila is the default parser. Unless you enable libxml2 Guththila will be built. | |
| (b) With libxml2 | |
| ---------------- | |
| 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 | |
| $ make install | |
| (c) With openssl | |
| ---------------- | |
| You may need to try Axis2/C with openssl. You can do it by | |
| giving '--with-openssl=[Path to openssl directory]' as a configure option. Path will contain | |
| openssl include directory and lib directory. If path is not given, include files will be | |
| taken from /usr/include/openssl and lib will be taken from /usr/lib (or /usr/lib64). | |
| $ ./configure --with-openssl=/opt/openssl [other configuration options] | |
| $ make | |
| $ make install | |
| (d) With JSON Support (REST API Alternative) | |
| -------------------------------------------- | |
| If you need REST API support as an alternative to SOAP-based web services, | |
| you can enable JSON processing support. This requires the JSON-C library | |
| and can be enabled with '--enable-json=yes' as a configure option. | |
| Prerequisites for JSON support: | |
| Ubuntu/Debian: sudo apt install libjson-c-dev | |
| RedHat/CentOS: sudo yum install json-c-devel | |
| $ ./configure --enable-json=yes [other configuration options] | |
| $ make | |
| $ make install | |
| Note: JSON support is NOT required for SOAP-based web services or the | |
| WSDL2C code generator. It provides REST API capabilities as an alternative | |
| to traditional SOAP messaging. | |
| (e) With Google Test (C++ Unit Testing Support) - ADVANCED | |
| ----------------------------------------------------------- | |
| IMPORTANT: Google Test C++ unit tests are optional. The basic build and | |
| functionality testing works without Google Test (recommended for most users). | |
| WHY BUILD GOOGLE TEST FROM SOURCE? | |
| ---------------------------------- | |
| Axis2/C's build system (dating from ~2015) expects to compile Google Test | |
| source files directly (gtest-all.cc, gtest_main.cc) rather than using | |
| modern pre-built libraries. This is because: | |
| 1. Ubuntu's libgtest-dev provides CMake integration and pre-built libraries | |
| 2. Axis2/C's autotools build expects source compilation for direct control | |
| 3. Axis2/C Makefile.am files reference $(GTEST_DIR)/src/gtest-all.cc explicitly | |
| 4. Converting to modern Google Test would require significant build system changes | |
| This approach ensures compatibility with the existing test infrastructure | |
| while avoiding the complexity of modernizing the entire build system. | |
| Method 1A - Use existing system Google Test (if available): | |
| # First, check if Google Test source files are already installed | |
| $ ls /usr/src/googletest/googletest/src/gtest-all.cc | |
| # If the file exists, configure directly with existing installation: | |
| $ ./configure --enable-tests --with-gtest=/usr/src/googletest/googletest [other options] | |
| Note: Many Ubuntu systems have Google Test source pre-installed in /usr/src/ | |
| This method avoids downloading and recompiling Google Test unnecessarily. | |
| Method 1B - Build Google Test from source (if system version unavailable): | |
| $ sudo apt install cmake git | |
| $ cd /tmp | |
| $ git clone https://github.com/google/googletest.git -b v1.17.0 | |
| $ cd googletest | |
| $ mkdir build && cd build | |
| $ cmake .. && make | |
| $ sudo make install | |
| Then configure Axis2/C with: | |
| $ ./configure --enable-tests --with-gtest=/tmp/googletest/googletest [other options] | |
| Method 2 - Skip unit tests entirely (recommended for most users): | |
| $ ./configure [other configuration options] | |
| $ make && make install | |
| Method 3 - Manual functionality verification (after Method 2): | |
| # Test WSDL2C native generator | |
| $ cd tools/codegen/native | |
| $ ./wsdl2c-native --help | |
| # Test code generation and compilation | |
| $ mkdir /tmp/axis2c_test && cd /tmp/axis2c_test | |
| $ echo '<?xml version="1.0"?><definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://test/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://test/"><types><xsd:schema targetNamespace="http://test/"><xsd:element name="TestRequest" type="xsd:string"/><xsd:element name="TestResponse" type="xsd:string"/></xsd:schema></types><message name="TestMessage"><part name="body" element="tns:TestRequest"/></message><message name="TestResponseMessage"><part name="body" element="tns:TestResponse"/></message><portType name="TestPortType"><operation name="TestOperation"><input message="tns:TestMessage"/><output message="tns:TestResponseMessage"/></operation></portType><binding name="TestBinding" type="tns:TestPortType"><soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/><operation name="TestOperation"><soap:operation soapAction="urn:TestOperation"/><input><soap:body use="literal"/></input><output><soap:body use="literal"/></output></operation></binding><service name="TestService"><port name="TestPort" binding="tns:TestBinding"><soap:address location="http://localhost:8080/axis2/services/TestService"/></port></service></definitions>' > test.wsdl | |
| $ ${AXIS2C_HOME}/../tools/codegen/native/wsdl2c-native -uri test.wsdl -o output -d adb -u | |
| $ cd output/src && gcc -c adb_*.c -I. -I${AXIS2C_HOME}/include/axis2-2.0.0 -I/usr/include/libxml2 -Wall -Wno-unused-parameter | |
| Note: Methods 2 and 3 avoid the C++ Google Test compilation issues and | |
| are sufficient for most development and testing purposes. If all commands | |
| above succeed, your Axis2/C installation is working correctly. | |
| RECOMMENDATION: For comprehensive regression testing of HTTP/2 JSON processing | |
| and the revolutionary interface pattern, use Method 1A (if available) or 1B. | |
| FUTURE IMPROVEMENT OPPORTUNITY: | |
| ------------------------------ | |
| The Axis2/C build system could be modernized to use system Google Test | |
| packages (libgtest-dev) with CMake integration, which would eliminate | |
| the need for source compilation. This would involve: | |
| - Updating util/test/util/Makefile.am to use pkg-config or CMake | |
| - Converting from direct source compilation to library linking | |
| - Testing compatibility across different Linux distributions | |
| 1.3.3 Building Samples | |
| ---------------------- | |
| If you need to get the samples working, you also need to build the samples. | |
| To build the samples: | |
| $ export LD_LIBRARY_PATH=${AXIS2C_HOME}/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} | |
| $ cd samples | |
| $ ./configure --prefix=${AXIS2C_HOME} | |
| --with-axis2=${AXIS2C_HOME}/include/axis2-2.0.0 | |
| $ make | |
| $ 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. | |
| 1.4 Running Samples | |
| ------------------- | |
| 1.4.1 HTTP Transport | |
| -------------------- | |
| (a) Server | |
| ---------- | |
| You have to first start the axis2_http_server as follows. | |
| $ cd ${AXIS2C_HOME}/bin | |
| $ ./axis2_http_server | |
| You should see the message | |
| Started Simple 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 1 : You may need to login as superuser to run the axis2_http_server. | |
| NOTE 2 : If you run into shared lib problems, set the LD_LIBRARY_PATH as | |
| follows. | |
| $ export LD_LIBRARY_PATH=${AXIS2C_HOME}/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} | |
| (b) Clients | |
| ----------- | |
| When the axis2_http_server is up and running, you can run the sample | |
| clients in a new shell as follows. | |
| $ cd ${AXIS2C_HOME}/samples/bin | |
| $ ./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 as | |
| follows. | |
| $ export LD_LIBRARY_PATH=${AXIS2C_HOME}/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} | |
| 2. Getting Axis2/C Working on Windows | |
| ===================================== | |
| RECOMMENDED: Windows Subsystem for Linux (WSL2) | |
| ----------------------------------------------- | |
| For Windows users, we strongly recommend using WSL2 with Ubuntu. WSL2 | |
| provides full Linux kernel compatibility with minimal overhead and is | |
| the tested and supported path for Axis2/C on Windows. | |
| WSL2 Setup: | |
| (a) Install WSL2 (requires Windows 10 version 2004+ or Windows 11): | |
| Open PowerShell as Administrator and run: | |
| > wsl --install | |
| This installs Ubuntu by default. Restart when prompted. | |
| (b) Launch Ubuntu from the Start menu and complete initial setup. | |
| (c) Follow the Linux instructions in Section 1 above. | |
| $ sudo apt update | |
| $ sudo apt install build-essential autoconf automake libtool \ | |
| libssl-dev libnghttp2-dev libjson-c-dev libxml2-dev | |
| $ git clone https://github.com/apache/axis-axis2-c-core.git | |
| $ cd axis-axis2-c-core | |
| $ ./configure --prefix=$(pwd)/deploy [options] | |
| $ make && make install | |
| WSL2 Benefits: | |
| - Full compatibility with Linux build system and dependencies | |
| - Easy package installation via apt | |
| - Excellent performance (native Linux kernel) | |
| - Seamless file system integration with Windows | |
| - Supported by active Axis2/C development | |
| Native Windows Build (Legacy - Unsupported) | |
| -------------------------------------------- | |
| WARNING: The native MSVC build has not been actively maintained or tested | |
| by Axis2/C committers since 2009 (version 1.6.0). The instructions below | |
| are preserved for historical reference only. | |
| Known limitations of the legacy Windows build: | |
| - Does NOT support HTTP/2 (requires nghttp2, not ported to Windows) | |
| - Does NOT support JSON processing (requires json-c, not ported) | |
| - References outdated tools (Visual Studio 2005, Windows XP-era libraries) | |
| - May not compile with modern Visual Studio versions | |
| - No IIS integration testing on modern IIS versions (10+) | |
| If you require native Windows builds, community contributions to modernize | |
| the Windows build system are welcome. Please contact c-dev@axis.apache.org. | |
| --- BEGIN LEGACY INSTRUCTIONS (2009) --- | |
| 2.1 Setting up Prerequisites | |
| ---------------------------- | |
| 2.1.1 Mandatory | |
| --------------- | |
| (a) The binaries shipped with this version are compiled with | |
| Microsoft Visual Studio compiler (cl). And also the makefile that is | |
| shipped with this version needs Microsoft Visual Studio compiler (cl) | |
| and nmake build tool. | |
| 2.1.2 Optional | |
| -------------- | |
| (a) libxml2 | |
| (b) zlib | |
| (c) iconv | |
| (d) openssl | |
| 2.2 Using Source Release | |
| ------------------------ | |
| 2.2.1 Setting Build Options | |
| --------------------------- | |
| Please edit the <source_distribution>\build\win32\configure.in file | |
| to set the following build options. | |
| (a) Enable Guththila | |
| - Guththila is the default parser unless you enable libxml2. | |
| (b) Enable libxml2 | |
| - Set the ENABLE_LIBXML2 option to 1 | |
| - Set the LIBXML2_BIN_DIR to the location where libxml2 is installed | |
| - Set the ICONV_BIN_DIR to the location where iconv is installed | |
| (c) Enable SSL Support | |
| - Set ENABLE_SSL option to 1 | |
| - Set OPENSSL_BIN_DIR to the location where OpenSSL is installed | |
| (d) Setting zlib Location | |
| - Set the ZLIB_BIN_DIR to the location where zlib is installed | |
| 2.2.2 Compiling the Source | |
| -------------------------- | |
| Extract the source distribution to a folder of your choice. | |
| Open a DOS shell and type: | |
| > cd %AXIS2C_HOME%\build\win32 | |
| > vcvars32.bat | |
| > nmake install | |
| 2.3 Running 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) | |
| 2.3.1 HTTP transport | |
| -------------------- | |
| (a) Server | |
| > cd %AXIS2C_HOME%\bin | |
| > axis2_http_server.exe | |
| (b) Clients | |
| > cd %AXIS2C_HOME%\samples\bin | |
| > echo.exe | |
| --- END LEGACY INSTRUCTIONS --- | |
| 3. Installing Apache2 Web Server Integration Module (mod_axis2) | |
| =============================================================== | |
| 3.1 Building mod_axis2 from Source | |
| ---------------------------------- | |
| 3.1.1 On Linux | |
| -------------- | |
| First, install Apache2 development packages: | |
| Ubuntu/Debian: | |
| $ sudo apt install apache2-dev libapr1-dev libaprutil1-dev | |
| RedHat/CentOS: | |
| $ sudo yum install httpd-devel apr-devel apr-util-devel | |
| Then provide the Apache2 include file location as a configure option: | |
| $ ./configure --with-apache2="<apache2 httpd include files location>" | |
| [other configure options] | |
| Common locations: | |
| Ubuntu/Debian: --with-apache2="/usr/include/apache2" | |
| RedHat/CentOS: --with-apache2="/usr/include/httpd" | |
| NOTE : Some apache2 distributions install APR (Apache Portable Runtime) | |
| include files in a separate location which is required to build | |
| mod_axis2. | |
| In that case use: | |
| $ ./configure --with-apache2="<apache2 include files location>" | |
| --with-apr="<apr include files location>" | |
| [other configure options] | |
| Common APR locations: | |
| Ubuntu/Debian: --with-apr="/usr/include/apr-1.0" | |
| RedHat/CentOS: --with-apr="/usr/include/apr-1" | |
| Then build the source tree | |
| $ make | |
| $ make install | |
| This will install mod_axis2.so into your "<your_path_to_axis2c>/lib" | |
| 3.1.2 On Windows (Win32) - LEGACY/UNSUPPORTED | |
| --------------------------------------------- | |
| WARNING: Windows Apache module has not been maintained since 2009. | |
| See Section 2 for recommended WSL2 approach. | |
| --- BEGIN LEGACY INSTRUCTIONS --- | |
| Provide the apache2 location in configure.in file in APACHE_BIN_DIR | |
| Example: | |
| APACHE_BIN_DIR = E:\Apache22 | |
| After compiling the sources (as described in section 2) 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. | |
| --- END LEGACY INSTRUCTIONS --- | |
| 3.2 Deploying in Apache2 Web Server | |
| ----------------------------------- | |
| NOTE : To do the following tasks, you might need super user privileges | |
| on your machine. | |
| Copy the mod_axis2 (libmod_axis2.so.0.7.0 on Linux and mod_axis2.dll | |
| on Windows) to "<apache2 modules directory>" as mod_axis2.so | |
| NOTE: The 0.7.0 version in the library filename reflects libtool's shared library versioning for ABI compatibility tracking and differs from the project release version (2.0.0). | |
| Example: | |
| cp $AXIS2C_HOME/lib/libmod_axis2.so.0.7.0 | |
| /usr/lib/apache2/modules/mod_axis2.so (on Linux) | |
| copy C:\axis2c\build\deploy\lib\mod_axis2.dll | |
| C:\Apache2\modules\mod_axis2.so (on 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. | |
| 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 don'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 the followings | |
| 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 in your Web browser | |
| 3.3 HTTP/2 Support (Optional) | |
| ----------------------------- | |
| Axis2/C supports HTTP/2 when deployed with Apache httpd 2.4.17+ and properly configured. | |
| HTTP/2 provides performance improvements for web services, with benefits varying by payload type: | |
| **JSON/REST Services (with --enable-json)**: | |
| - 30-50% performance improvement due to better compression ratios | |
| - Significant header compression benefits (JSON APIs use more varied HTTP headers) | |
| - Excellent streaming performance for large JSON payloads (50MB+) | |
| - HPACK compression is highly effective with JSON content-type headers | |
| - Better multiplexing efficiency with RESTful API patterns | |
| **Key HTTP/2 Benefits**: | |
| - Single persistent connection replaces multiple HTTP/1.1 connections | |
| - Header compression (HPACK) reduces overhead, especially beneficial for JSON APIs | |
| - Stream multiplexing eliminates head-of-line blocking | |
| - Server push disabled by default (optimized for API responses, not web assets) | |
| Prerequisites for HTTP/2: | |
| - Apache httpd 2.4.17 or later | |
| - mod_axis2 properly installed (see section 3.1-3.2 above) | |
| - mod_http2 module enabled: `sudo a2enmod http2` | |
| - mod_ssl module enabled: `sudo a2enmod ssl` | |
| - OpenSSL 1.0.2+ with ALPN support | |
| - SSL certificates (can use self-signed for development) | |
| Ubuntu/Debian HTTP/2 setup: | |
| $ sudo a2enmod http2 | |
| $ sudo a2enmod ssl | |
| $ sudo systemctl restart apache2 | |
| RedHat/CentOS HTTP/2 setup: | |
| $ sudo yum install mod_http2 # or dnf install for newer versions | |
| $ sudo systemctl restart httpd | |
| Complete HTTP/2 configuration instructions are provided in docs/*HTTP2* and | |
| docs/userguide/json-httpd-h2-userguide.md . | |
| Note: HTTP/2 is entirely optional. Axis2/C works perfectly with HTTP/1.1. | |
| HTTP/2 is recommended for JSON based production deployments handling high traffic | |
| or large payloads where performance improvements are valuable. SOAP and XML | |
| are not supported in HTTP/2 due to high effort and few benefits. | |
| 4. Using Axis2/C with CGI | |
| ========================= | |
| 4.1 Deploying in Apache2 | |
| ------------------------- | |
| If you haven't already done so you need to configure and set up a cgi-bin/ | |
| directory that holds your CGI scripts, where we will put Axis2/C cgi | |
| executable axis2.cgi. | |
| (Note: most Apache web servers already have a cgi-bin dir set up, usually | |
| /usr/lib/cgi-bin/.) | |
| Add the following to your Apache2 configuration (httpd.conf) file: | |
| ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ | |
| OR you can use: | |
| <Directory /usr/local/apache/cgi-bin/> | |
| Options +ExecCGI | |
| </Directory> | |
| AddHandler cgi-script .cgi | |
| (It's recommended to restrict all CGI scripts to a single ScriptAlias | |
| directory for security reasons.) | |
| Now set up configuration parameters via environment variables for the CGI | |
| deployment using the SetEnv directive. You need to have mod_env enabled. | |
| Add the following to your apache2 configuration file (httpd.conf): | |
| SetEnv AXIS2C_HOME /usr/local/axis2c/ | |
| If you have chosen another alias for your cgi-bin you can also set up an | |
| AXIS2C_URL_PREFIX environment variable (not needed if using /cgi-bin/). | |
| Example: | |
| SetEnv AXIS2C_URL_PREFIX /private/scripts/axis2.cgi/ | |
| Copy the Axis2/C cgi executable "axis2.cgi" from ${AXIS2C_HOME}/bin to | |
| your cgi-bin directory. | |
| Your Axis2 endpoints will look like this when deployed under CGI: | |
| http://domain-name.com/cgi-bin/axis2.cgi/services/<service name> | |
| For example, the echo service endpoint would be: | |
| http://domain-name.com/cgi-bin/axis2.cgi/services/echo | |
| 5. 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 in your system. | |
| You can get libxml2 from http://xmlsoft.org/downloads.html. | |
| 3. I have 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 run | |
| $ apt-get install libxml2-dev | |
| 2. If you are using a RedHat/Fedora based system run | |
| $ yum install libxml2-devel | |
| 3. If you install libxml2 from source you will not get this error | |
| 4. Is there any recommended packages, that I need to install in my system? | |
| 1. automake, autoconf, libtool, aclocal | |
| 2. libxml2 and libxml2-dev | |
| 3. pkg-config | |
| 5. I tried several methods, browse through axis-c-dev and axis-c-user mail | |
| archives but I was not able to solve my problem. | |
| Then you can ask from Axis2/C users or Axis2/C developers about it by | |
| sending your question to | |
| user = c-user@axis.apache.org | |
| developer = c-dev@axis.apache.org | |
| You can subscribe to | |
| c-user list by sending a request to | |
| <c-user-subscribe@axis.apache.org> with the subject "subscribe" | |
| c-dev list by sending request to | |
| <c-dev-subscribe@axis.apache.org> with the subject "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 ... |