Copyright (c) 2005 IBM Corporation and others.
All rights reserved.   This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html
$Id: README.txt,v 1.6 2005/06/10 03:06:12 paules Exp $
		
Contributors:
IBM - Initial API and implementation
	
Author(s): Samson Wai
           Paul E. Slauenwhite
Version:   June 9, 2005
Since:     February 4, 2005


1. Introduction

This README file chronicles the necessary dependencies, environments and procedures to compile the TPTP 4.0 Agent 
Controller (AC) on Windows and Linux platforms. 

Since the TPTP 4.0 AC is written in both C and C++ and leverages the Java Native Interface (JNI) for JVM creation, 
Java class creation and method invocation, platform-specific procedures are required for building the AC.

The TPTP 4.0 AC code is located in the dev.eclipse.org\home\tptp\platform\org.eclipse.tptp.platform.agentcontroller
TPTP CVS module.


2. Notation

<extract directory> = The local absolute path to the org.eclipse.tptp.platform.agentcontroller module as 
                      extracted from CVS (dev.eclipse.org\home\tptp\platform\org.eclipse.tptp.platform.agentcontroller).  
                      For example, C:\org.eclipse.tptp.platform.agentcontroller on Windows.

<component>         = The individual components of the AC, as cited in section 4. 

<UNIX>              = The supported UNIX platforms of the AC, as cited in section 5. 

<xerces>            = The local absolute path to the directory containing the Apache Xerces-C++ XML parser v2.4.0
                      dependency, as cited in section 5.  For example, C:\Apache_Xerces-c2_4_0-windows_nt-msvc_60 on 
                      Windows.

<java>              = The local absolute path to the directory containing the J2SE v1.4.0 or above
                      dependency, as cited in section 5.  For example, C:\jdk140 on Windows.

<cbe>               = The local absolute path to the directory containing the platform-specific TPTP Common Base Event 
                      Native Logging SDK v4.0.0 or above dependency, as cited in section 5.  For example, 
                      C:\tptp\tptpdc\win_ia32 on Windows.

<ac>                = The local absolute path to the directory containing the platform-specific current TPTP Agent 
                      Controller dependency required for debugging, as cited in section 5.  For example, 
                      C:\tptp\tptpdc\win_ia32 on Windows.

<working>           = The local absolute path to a working or build directory.  For example, C:\AC_Build on 
                      Windows.

<build ID>          = Unique ID for a build.  For example, the current date and time (e.g. 20050607_1300).

<pid>               = The process ID of the AC process.


3. CVS Module Structure

-Includes/Makes: <extract directory>\src-native\collection
-Agents:         <extract directory>\src-native\collection\collectors
-AC Components:  <extract directory>\src-native\collection\framework
-Packaging:      <extract directory>\src-native\collection\packaging (platform independent)
                 <extract directory>\src-native\collection\packaging_md (platform dependent)
-Headers:        <extract directory>\src-native\collection\sys_includes
                
                
4. AC Components:

-HCLauncher:     Launch mechanism for execution framework
-InstService:    Service installer for the Windows platform
-RABindings:     Agent side bindings containing APIs for communicating with the AC
-RACommon:       Common functions used by all subcomponents
-RADataTransfer: Writes messages into byte streams
-RAServer:       Startup and main message handling logic
-RAServerConfig: Configuration file parser
-RAServerTypes:  Definitions of AC data structures
-RASharedMemory: APIs for accessing shared memory
-RASocket:       Writes byte array to sockets
-WinBuild:       AC Microsoft Visual C++ v6.0 project and desktop files


5. AC Supported Platforms:

-Windows/IA32
-Linux/IA32
-AIX/PPC32
-HP-UX/PA_RISC
-Solaris/SPARC


6. Dependencies

a) Compilers:

-Windows/IA32:  Microsoft Visual C++ v6.0
-Linux/IA32:    GNU gcc v2.96
-AIX/PPC32:     IBM VisualAge C++ Professional for AIX, Version v5.0
-HP-UX/PA_RISC: HP aC++ A.03.25
-Solaris/SPARC: Sun WorkShop Compilers C 6 update 1

b) Software:

-Apache Xerces-C++ XML parser v2.4.0 (http://xml.apache.org/xerces-c)
-J2SE v1.4.0 or above (http://java.sun.com/j2se/index.jsp)
-GNU Make v3.79 (Linux/Unix only)
-TPTP Common Base Event Native Logging SDK v4.0.0 or above (http://eclipse.org/tptp > Latest Downloads) or build the 
 org.eclipse.hyades.logging.core\src.native\CommonBaseEvent project.
-A Current TPTP Agent Controller install (http://eclipse.org/tptp > Latest Downloads) required for debugging.

c) Make Files:

-Windows/IA32:  <extract directory>\src-native\collection\makefile.win_ia32
                <extract directory>\src-native\collection\framework\WinBuild\<component>.mak
-Linux/IA32:    <extract directory>\src-native\collection\makefile
                <extract directory>\src-native\collection\<component>.mak
-AIX/PPC32:     <extract directory>\src-native\collection\makefile
                <extract directory>\src-native\collection\<component>.mak
-HP-UX/PA_RISC: <extract directory>\src-native\collection\makefile
                <extract directory>\src-native\collection\<component>.mak
-Solaris/SPARC: <extract directory>\src-native\collection\makefile
                <extract directory>\src-native\collection\<component>.mak

d) Build Resources:

-Microsoft Visual C++ v6.0 workspace: <extract directory>\src-native\collection\framework\WinBuild\WinBuild.dsw
-UNIX includes:                       <extract directory>\src-native\collection\include.<UNIX>


7. Steps:

a) Windows/IA32:
	1)  Start Microsoft Visual C++ v6.0.
	2)  Add the following files to the INCLUDE path (Tools > Options... > Directories > Show directories for: 
	    > Include files):
	    -<xerces>\include
	    -<cbe>\include
	    -<java>\include
	    -<java>\include\win32
	3)  Add the following files to the LIB path (Tools > Options... > Directories > Show directories for: 
	    > Lib files):
	    -<xerces>\lib
	    -<cbe>\lib
	4)  Open the AC Microsoft Visual C++ v6.0 workspace (File > Open... > 
	    <extract directory>\src-native\collection\framework\WinBuild\WinBuild.dsw).
	5)  Set the RAServer project as the active project (Build > Set Active Configuration... > 
	    RAServer - Win32 Release or RAServer - Win32 Debug).
	6)  Copy the contents of the <ac> directory to the <extract directory>\src-native\collection\framework\WinBuild 
	    directory.
	7)  Build the AC (Build > Build RAServer.exe).
	8)  Confirm that executable files (e.g. *.exe and *.dll) have been created in the 
	    <extract directory>\src-native\collection\framework\WinBuild\bin directory.
	9)  Confirm that intermediate files (e.g. *.obj, *.lib, etc.) have been created in the 
	    <extract directory>\src-native\collection\framework\WinBuild\Release or Debug directory.
	10) Follow the instructions in the <extract directory>\src-native\collection\framework\WinBuild\getting_started.html 
	    file, but so not start the AC. 
	11) Run the AC (Build > Execute RAServer.exe). 
	12) When debugging the AC, set a breakpoint on the source code (Edit > Breakpoints...), build the AC 
	    (Build > Build RAServer.exe) and run the AC in debug mode (Build > Start Debug > Go). 
	13) When debugging the agent code, add the DebugBreak() Win32 API function call in the source 
	    code as a breakpoint, build the agent code and run the agent code.   
	
b) Linux/IA32:
	1)  Create the following directories:
	    -<working>
	    -<working>/<build ID>
	    -<working>/<build ID>/cbe
	    -<working>/<build ID>/cbe/cImpl
	    -<working>/<build ID>/collection
	    -<working>/depends
	2)  From the <working>/depends directory, create the following symbolic links:
	    -ln –s <java> java
	    -ln –s <xerces> xercesc
	3)  Copy the contents of the <extract directory>/src-native/collection directory to the 
	    <working>/<build ID>/collection directory.  When unzipping, ensure the '-aa' flag is used to 
	    force ASCII conversion.
    4)  Copy the contents of the <cbe> directory to the <working>/<build ID>/cbe directory.  When unzipping,
	    ensure the '-aa' flag is used to force ASCII conversion.
    5)  Rename the <working>/<build ID>/cbe/lib directory to <working>/<build ID>/cbe/packaging directory.
    6)  Rename the <working>/<build ID>/cbe/include directory to <working>/<build ID>/cbe/cImpl directory.
    7)  Copy the contents of the <ac> directory to the <working>/<build ID>/collection/packaging directory.
	8)  From the <working>/<build ID>/collection directory, build the AC (i.e. make).
	9)  Confirm that executable files and shared libraries have been created in the 
	    <working>/<build ID>/collection/packaging/bin and <working>/<build ID>/collection/packaging/lib directories.
	10)  Follow the instructions in the <working>/<build ID>/collection/packaging/getting_started.html file. 
	11) Run the AC (<working>/<build ID>/collection/packaging/bin/RAStart.sh). 
	12) When debugging the AC, add the -g compiler option to the CFLAGS variable in the 
	    <working>/<build ID>/collection/include.linux_ia32 file, build the AC (i.e. make) from the 
	    <working>/<build ID>/collection directory, run the AC (<working>/<build ID>/collection/packaging/bin/RAStart.sh),
	    get the PID of the AC process (ps –ae | grep RAServer) and use the GNU Project debugger (gdb) to attach to the 
	    AC process (gdb ./RAServer <pid>).
	13) When debugging the agent code, add the -g compiler option to the CFLAGS variable when compiling the 
	    agent code, build the agent code, run the agent code, get the PID of the agent process and use the 
	    GNU Project debugger (gdb) to attach to the agent process.