path: root/das-cpp/trunk/README_ANT_INSTALL

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 TuscanyDAS Native

This guide shows how to build TuscanyDAS Native with apache 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 write an ant build file for the samples.


Required Software to build TuscanySDO 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 TuscanyDAS 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 TuscanyDAS Native is the location of libxml2 and TuscanySDO.

To configure the location of libxml2, do one of the following:
  export LIBXML2_LIB=/libxml2/lib/dir
  export LIBXML2_INCLUDE=/libxml2/include/dir
  -- OR --
  edit antscripts/platform.properties
  platform.libxml2.lib.dir=/libxml2/lib/dir
  platform.libxml2.include.dir=/libxml2/include/dir

To configure the location of TuscanySDO, do one of the following:
  export TUSCANY_SDOCPP=/tuscanySDOHome/
  -- OR --
  edit antscripts/platform.properties
  platform.tuscany.sdo.home.dir=/tuscanySDOHome/
  
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 TuscanySDO Native ant build process is hierarchical. Currently there are 
build scripts in the following locations, which can all be invoked from the 
root TuscanySDO directory:
  TUSCANY_DAS_SRC_ROOT/build.xml
  TUSCANY_DAS_SRC_ROOT/runtime/core/build.xml

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 TuscanyDASNative source code and documentation
 build    		Build all TuscanyDASNative source code and documentation
 clean    		Clean all TuscanyDASNative compiled source code
 samples  		Build and install all TuscanyDASNative samples
 install  		Install TuscanyDASNative libraries and headers
 test     		Build and run all tests
 distribution   	Create a source and bin distribution structure
 pack.distribution      Pack the bin and source distribution into .zip and .tar.gz files. Also generates the .asc and .md5 files
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.


GENERATING A PROJECT DISTRIBUTION
=================================

To create a src and bin distribution of Tuscany DAS subproject, there must be set some properties on platform.properties files:

Property                                 Required                  Example                                 Description
--------                                 --------                  -------                                 -----------

platform.public.key.path                  Yes                     "E:/gnupg/trustdb.gpg"                   The public key ring file path

platform.secret.key.path                  Yes                     "E:/gnupg/secring.gpg"                   The secret key ring file path  
         
platform.key.id                           Yes                     "148CAFB2"                               The key id used to sign the distribution files

platform.tuscanyDAS.distribution.dir      NO                      "C:\distribution\"                       The folder where the distribution files will be generated, default=tuscanyDAS.root.dir/distribution

platform.tuscanyDAS.release.file.name     NO                      "tuscany_das_native-1.0-incubator-M4-"   The beginning of src and bin packed distribution file name, default="tuscany_cpp_das".
													   TUSCANY_DASCPP_RELEASE_NAME env var may be used as an alternative

Also is required the bcpg-jdk<latest_version>-<latest_version>.jar and 
jce-jdk<latest_version>-<latest_version>.jar files defines on classpath. 
Both can be found at http://www.bouncycastle.org/latest_releases.html

Use the "distribution" target to generate the src and bin distribution 
file structure under platform.tuscanySDO.distribution.dir folder. Then 
use the "pack.distribution" target to pack the bin and src distribution 
folders as .zip and .tar.gz and generate their .asc and .md5 files. A 
password must be set on the command line when using pack.distribution 
target, this password is used to sign the packed distribution files with 
the secret key defined on platform.secret.key.path

Make sure an 1.6 JRE version is set in your JAVA_HOME when signing the
distribution.

Usage:
ant distribution
// do whatever you want on the generated distribution files
ant pack.distribution -Dpassword="123456"



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

The following explains how to configure the TuscanyDAS 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 TuscanyDAS Native ant build system is capable of automatically configuring 
everything except the location of the libxml2 and TuscanySDO libraries. All other configuration 
options can be determined.

From anywhere there is a TuscanyDAS 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.sdo:

display.system:
     [echo]
     [echo] TuscanyDAS paths
     [echo]   tuscanyDAS.root.dir=           /home/Adriano/Tuscany/cpp/das
     [echo]   tuscanyDAS.root.src.dir=       /home/Adriano/Tuscany/cpp/das/runtime
     [echo]   tuscanyDAS.install.dir=        /home/Adriano/Tuscany/cpp/das/deploy
     [echo]   tuscanyDAS.library.version=    ''
     [echo]   tuscanyDAS.release.file.name=  'tuscany_das_cpp-1.0-incubator-M4-'

     [echo]
     [echo] TuscanyDAS compiler configuration
     [echo]   compiler.name=               'msvc8'
     [echo]   debug.compile=               'false'
     [echo]   lib.ext=                     '.lib'
     [echo]   dll.ext=                     '.dll'
     [echo]   lib.prefix=                  ''
     [echo]   object.ext=                  '.obj'
     [echo]   exe.ext=                     '.exe'
     [echo]   script.ext=                  '.bat'
     [echo]   external.definitions.file=   ''
     [echo]
     [echo] sdo location
     [echo]   tuscany.sdo.home.dir=          /home/Adriano/Tuscany/cpp/sdo/deploy
     [echo]

BUILD SUCCESSFUL
Total time: 0 second

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 DAS installation path
-----------------------------

The Tuscany DAS installation directory can be configured as follows:
  export TUSCANY_DASCPP=/tuscany/das/native/install/dir
  -- OR --
  edit antscripts/platform.properties
  platform.tuscanyDAS.install.dir=/tuscany/das/native/install/dir

The Tuscany DAS installation directory defaults to:
  TUSCANY_DAS_SRC_ROOT/deploy

Tuscany SDO Configuration
-------------------------

TuscanySDO:
If not specified, then the the build will fail.

  export TUSCANY_SDOCPP=/tuscanySDOHome/
    -- OR --
  edit antscripts/platform.properties
  platform.libxml2.lib.dir=/libxml2/library/directory
  platform.libxml2.include.dir=/libxml2/include/directory


3rd Party configuration
-----------------------

LIBXML2:
If not specified, then the the build will fail.

  export LIBXML2_LIB=/libxml2/library/directory
  export LIBXML2_INCLUDE=/libxml2/include/directory
    -- OR --
  edit antscripts/platform.properties
  platform.tuscany.sdo.home.dir=/tuscanySDOHome/