Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
   
http://www.apache.org/licenses/LICENSE-2.0
     
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Using ant to build TuscanySCA Native

This guide shows how to build TuscanySCA Native with apache ant. 
Traditionally TuscanySCA was compiled with automake, but we decided
it would be easier to maintain and more flexible if we switched to 
ant. Above all, using ant will standardize the build system across 
all platforms, obviating the need to support both automake and 
microsoft VC projects.The ant build process is still in its beta 
and will be formalized for Release M4. Currently the only item 
remaining is to finish writing ant build files for the rest of the 
samples.


Required Software to build TuscanySCA Native with ant
=====================================================

Java:
        Most Linux, Mac, and Windows systems come with Java
        Java 1.4.2 or later

Ant:
        Ant comes installed with almost all Linux distributions
        version 1.6 or later
        Download: http://ant.apache.org/

antcontrib:
        version 1.0b3 or later
        Download: http://ant-contrib.sourceforge.net/

antcontrib cpptasks.jar
        version 1.0b4 or later
        Download: http://ant-contrib.sourceforge.net/
        Information: http://ant-contrib.sourceforge.net/cc.html


Installation Instructions
=========================

Linux/Mac
---------

Make sure JAVA_HOME is set before starting.

Install ant according to http://ant.apache.org/manual/index.html.

Set the ANT_HOME variable to the directory where you install ant.
export ANT_HOME="/home/your/ant"

Add $ANT_HOME/bin to your path.
export PATH="${PATH}:${ANT_HOME}/bin"

The optional ant tasks included in antcontrib and cpptasks are needed to
compile Tuscany Native with ant. Additional ant tasks (antcontrib and cpptasks)
should be installed in $ANT_HOME/lib
So place the antcontrib and cpptasks jars there.

If you dont have write access to $ANT_HOME/lib, do the following:
- create ${user.home}/.ant/lib
- place the jars here

Typically its a good idea to avoid adding optional ant tasks to your classpath,
this can be problematic.

Since the antcontrib compiler adaptor for microsoft msvc 8 has several bugs, we've
written our own. Even though this compiler is for Windows, it is referenced in the
ant build scripts and thus needs to be added to the classpath even for Linux/Mac.
Add the TuscanyMSVC8DevStudioCCompiler jar to your classpath.
export CLASSPATH="${CLASSPATH}:/TuscanySourceDir/antscripts/TuscanyMSVC8DevStudioCCompiler.jar"

Windows
-------

Make sure JAVA_HOME is set before starting.

Install ant according to http://ant.apache.org/manual/index.html.

Set the ANT_HOME variable to the directory where you install ant.
set ANT_HOME=c:\ant

Add %ANT_HOME%\bin to your path.
set PATH=%PATH%;%ANT_HOME%\bin

The optional ant tasks included in antcontrib and cpptasks are needed to
compile Tuscany Native with ant. Additional ant tasks (antcontrib and cpptasks)
should be installed in %ANT_HOME%\lib
So place the antcontrib and cpptasks jars there.

If you dont have write access to %ANT_HOME%\lib, do the following:
- create %user.home%\.ant\lib
- place the jars here

Typically its a good idea to avoid adding optional ant tasks to your classpath,
this can be problematic.

Since the antcontrib compiler adaptor for microsoft msvc 8 has several bugs, we've
written our own, namely TuscanyMSVC8DevStudioCCompiler. The Tuscany MSVC8 adaptor 
just makes sure that the correct parameters are passed to the compiler.
Add the TuscanyMSVC8DevStudioCCompiler jar to your classpath.
set CLASSPATH=%CLASSPATH%:c:\TuscanySourceDir\antscripts\TuscanyMSVC8DevStudioCCompiler.jar

USAGE
=====

From the TuscanySCA Native root source directory, the entire application can be 
compiled, linked, and installed by simply executing ant with no targets. This will
execute the default "all" target.

# ant

The ant build system will scan your environment variables and ant configuration file
and try to autoconfigure everything needed to build.  The environment variables can be 
overridden by the ant configuration file: antscripts/platform.properties.  The only 
configuration that is mandatory to build TuscanySCA Native is the location of an SDO 
implementation, typically TuscanySDO Native.

To configure the location of TuscanySDO Native, do one of the following:
export TUSCANY_SDOCPP=/tuscany/sdo/native/deploy/dir
  -- OR --
edit antscripts/platform.properties
platform.tuscanySDO.install.dir=/tuscany/sdo/native/deploy/dir

The platform.properties configuration always overrides environment variables.
See the CONFIGURATION section below for more information.

To compile in debug mode, add the following define to the ant command line or
edit the platform.properties file as seen in the CONFIGURATION section below.

# ant -Ddebug=true

The TuscanySCA Native ant build process is hierarchical. Currently there are 
build scripts in the following locations, which can all be invoked from the 
root TuscanySCA directory:
  TUSCANY_SCA_SRC_ROOT/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/core/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/cpp/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/php/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/cpp/tools/scagen/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/python/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/rest/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/ruby/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/sca/build.xml
  TUSCANY_SCA_SRC_ROOT/runtime/extensions/wsbuild.xml
  TUSCANY_SCA_SRC_ROOT/tools/TuscanyDriver/build.xml
  TUSCANY_SCA_SRC_ROOT/tools/TuscanyDriver/build.xml
  TUSCANY_SCA_SRC_ROOT/samples/CppBigBank/build.xml (the rest of the samples are coming soon)

For a listing of public targets for any build.xml file, execute the following: 
(display shown for the root src directory)

# ant -p
Buildfile: build.xml

Main targets:

 all      build and install all TuscanyScaNative source code
 build    Build all TuscanyScaNative source code
 clean    Clean all TuscanyScaNative compiled source code
 install  Install TuscanyScaNative libraries and headers
Default target: all

Public targets are those that have descriptions and are usually the only ones needed for
compiling, installing and cleaning. For more avanced use, the private targets can be seen 
by looking at the actual build.xml file.


CONFIGURATION
==============

The following explains how to configure the TuscanySCA Native ant build system.
The build system is configured either by environment variables and/or by the
antscripts/platform.properties file. Some options can only be configured via the
platform.properties file. If an option can be configured in both places, the option
specified in the platform.properties file overrides the environment variable.

The TuscanySCA Native ant build system is capable of automatically configuring 
everything except the location of the Tuscany SDO Native location. All other
configuration options can be determined. (except of course the location of the 
optional 3rd-party packages: axis2c, python, php, ruby, and rest) 

From anywhere there is a TuscanySCA Native build.xml file, the current system
configuration can be displayed by executing the display.system ant target as 
follows:

# ant display.system
Buildfile: build.xml

check.ws:

check.python:

check.php:

check.ruby:

check.rest:

display.system:
     [echo]
     [echo] TuscanySCA paths
     [echo]   tuscanySCA.install.dir=      /nfs/homes/bjohnson/tuscany_svn_head/sca/deploy
     [echo]   tuscanySCA.root.dir=         /amd/homes/bjohnson/tuscany_svn_head/sca
     [echo]   tuscanySCA.root.src.dir=     /amd/homes/bjohnson/tuscany_svn_head/sca/runtime
     [echo]   tuscanySCA.install.dir=      /nfs/homes/bjohnson/tuscany_svn_head/sca/deploy
     [echo]   tuscanySCA.library.version=  '.0.0.0'
     [echo]   tuscanySDO.install.dir=      /nfs/homes/bjohnson/tuscany_svn_head/sdo/deploy
     [echo]
     [echo] TuscanySCA compiler configuration
     [echo]   compiler.name=               'g++'
     [echo]   debug.compile=               'false'
     [echo]   lib.ext=                     '.so'
     [echo]   dll.ext=                     ''
     [echo]   lib.prefix=                  'lib'
     [echo]   object.ext=                  '.o'
     [echo]   exe.ext=                     ''
     [echo]   script.ext=                  '.sh'
     [echo]   external.definitions.file=   ''
     [echo]   sdo.impl.library.name=       'tuscany_sdo'
     [echo]
     [echo] TuscanySCA ws extension enabled
     [echo]   axis2c.home.dir=          /nfs/homes/bjohnson/3rdparty/axis2c-src-0.96/deploy
     [echo]
     [echo] TuscanySCA php extension enabled
     [echo]   php.lib.dir=              /nfs/homes/bjohnson/3rdparty/php-5.1.6/deploy/lib
     [echo]   php.include.dir=          /nfs/homes/bjohnson/3rdparty/php-5.1.6/deploy/include/php
     [echo]   php.sca.sdo.lib.dir=      /nfs/homes/bjohnson/3rdparty/sdo-1.0.3/lib
     [echo]   php.sca.sdo.include.dir=  /nfs/homes/bjohnson/3rdparty/sdo-1.0.3
     [echo]
     [echo] TuscanySCA python extension enabled
     [echo]   python.lib.dir=           /nfs/homes/bjohnson/3rdparty/Python-2.5.1/deploy/lib
     [echo]   python.include.dir=       /nfs/homes/bjohnson/3rdparty/Python-2.5.1/deploy/include/python2.5
     [echo]   python.version=           python2.5
     [echo]
     [echo] TuscanySCA rest extension enabled
     [echo]   rest.curl.lib.dir=        /usr/lib
     [echo]   rest.curl.include.dir=    /usr/include/curl
     [echo]   rest.httpd.include.dir=   /nfs/homes/bjohnson/3rdparty/httpd-2.0.59/deploy/include
     [echo]   rest.apr.include.dir=     /usr/include/apr-0
     [echo]
     [echo] TuscanySCA ruby extension enabled
     [echo]   ruby.lib.dir=             /nfs/homes/bjohnson/3rdparty/ruby-1.8.6/deploy/lib
     [echo]   ruby.include.dir=         /nfs/homes/bjohnson/3rdparty/ruby-1.8.6/deploy/include
     [echo]

BUILD SUCCESSFUL
Total time: 0 seconds


Compilation configuration
-------------------------

The compilation options can all be determined by the ant build system by
examining the platform.  The values can only be overriden by editing the 
platform.properties file. Following is a list of the options and their 
default values:

platform.lib.ext=        (Defaults to ".so" for Unix and ".lib" for Windows)
platform.dll.ext=        (Defaults to "" for Unix and ".dll" for Windows. Not used for Unix)
platform.exe.ext=        (Defaults to "" for Unix and ".exe" for Windows)
platform.object.ext=     (Defaults to ".o" for Unix and ".obj" for Windows)
platform.script.ext=     (Defaults to ".sh" for Unix and ".bat" for Windows)
platform.compiler.name=  (Defaults to "g++" for Unix and "msvc8" for Windows)
platform.debug.compile=  (Defaults to "false" for both Unix and Windows)

To configure ant to use a compiler other than g++ or msvc, or to add your own
ant tasks/definitions, specify a path for the platform.external.definitions.file
and platform.compiler.name in the platform.properties configuration file. This 
is especially useful for compiling on other platforms like AIX or Solaris.

Tuscany SCA and SDO paths
-------------------------

Both the Tuscany SCA and SDO installation directories can be configured as follows:
  export TUSCANY_SCACPP=/tuscany/sca/native/install/dir
  export TUSCANY_SDOCPP=/tuscany/sdo/native/install/dir
  -- OR --
  edit antscripts/platform.properties
  platform.tuscanySCA.install.dir=/tuscany/sca/native/install/dir
  platform.tuscanySDO.install.dir=/tuscany/sdo/native/install/dir

The Tuscany SCA installation directory defaults to:
  TUSCANY_SCA_SRC_ROOT/deploy

Extension configuration
-----------------------

AXIS2C:
If not specified, then the values are left empty and the cpp and ws extensions will not be compiled.

  export AXIS2C_HOME=/axis2c/home/dir
   -- OR --
  edit antscripts/platform.properties
  platform.axis2c.home.dir=/axis2c/home/dir

PYTHON:
If not specified, then the values are left empty and the python extension will not be compiled.

  export PYTHON_LIB=/python/library/directory
  export PYTHON_INCLUDE=/python/include/directory
  export PYTHON_VERSION=python_library_name_with_version
    -- OR --
  edit antscripts/platform.properties
  platform.python.include.dir=/python/library/directory
  platform.python.lib.dir=/python/include/directory
  platform.python.version=python_library_name_with_version

PHP:
If not specified, then the values are left empty and the php extension will not be compiled.

  export PHP_LIB=/php/library/directory
  export PHP_INCLUDE=/php/include/directory
  export PHP_SCA_SDO_LIB=/php/sdo/library/directory
  export PHP_SCA_SDO_INCLUDE=/php/sdo/include/directory
  -- OR --
  edit antscripts/platform.properties
  platform.php.include.dir=/php/library/directory
  platform.php.lib.dir=/php/include/directory
  platform.php.sca.sdo.lib.dir=/php/sdo/library/directory
  platform.php.sca.sdo.include.dir=/php/sdo/include/directory

RUBY:
If not specified, then the values are left empty and the ruby extension will not be compiled.
  export RUBY_LIB=/ruby/library/directory
  export RUBY_INCLUDE=/ruby/include/directory
    -- OR --
  edit antscripts/platform.properties
  platform.ruby.lib.dir=/ruby/library/directory
  platform.ruby.include.dir=/ruby/include/directory

REST:
If not specified, then the values are left empty and the rest extension will not be compiled.
  export CURL_LIB=/curl/library/directory
  export CURL_INCLUDE=/curl/include/directory
  export HTTPD_INCLUDE=/httpd/apache/include/directory
  export APR_INCLUDE=/apr/include/directory
    -- OR --
  edit antscripts/platform.properties
  platform.rest.curl.lib.dir=/curl/library/directory
  platform.rest.curl.include.dir=/curl/include/directory
  platform.rest.httpd.include.dir=/httpd/apache/include/directory
  platform.rest.apr.include.dir=/apr/include/directory