/**************************************************************************** * Copyright (c) 2005, 2006 Intel Corporation. * 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.15 2006/06/06 22:51:03 rsmith Exp $ ****************************************************************************/ Contributors: Vishnu K. Naikawadi, Intel (Description of the directory structure and steps on how to run the AgentController, SampleClient and TimeCollector) Randy D. Smith, Intel (Upgraded for TPTP 4.0 technology preview) Karla Callaghan, Intel (Further refinements for technology preview 4.0) Randy D. Smith, Intel (Updated for TPTP 4.1 new agent controller technology.) Randy D. Smith, Intel (Updated for TPTP 4.2 new tech AC w/BC [agent controller with backward compatibility]; new build structure; real 64-bit ports to Windows 2003.) New Technology Agent Controller (AC) in TPTP 4.2 1. Introduction --------------- This release includes the agent controller, several service agents (e.g., process controller and file transfer agent), client libraries for accessing the services of the agent controller and its agents, and a sample client/agent application illustrating the use of the client and agent libraries. The SDK package includes several additional sample applications. This readme.txt file serves to chronicle the dependencies, environments, and procedures necessary to compile the new technology Agent Controller (AC) on Windows and Linux platforms and run the primary Sample Client as a means of testing an AC installation. Note that there are platform-specific procedures required for building this software. This version of the release contains compatibility layers to make it useable in place of the agent controller found in TPTP 4.1 (henceforth referred to as the "RAC" to distinguish it from the new technology AC). The SSL/authentication support and dynamic discovery of other agent controller support are new to this version. Note that these AC/BC functionalities are only operative for the Windows packages for IA32, IPF, and EM64T in 4.2. This agent controller should be installed in its own directory (not the same directory as a RAC install) to prevent overwriting the RAC's serviceconfig.xml file. See the TPTP web site for documentation of details on what's in the new serviceconfig.xml file. The RAC and the new AC cannot be run simultaneously unless care is taken in assigning different port numbers and pipe names for each using each's serviceconfig.xml file. 2. Installing a Package ----------------------- To install the runtime or SDK package, simply create a directory and unzip the contents of the file downloaded from the TPTP web site. Add the path of the resulting bin directory to the PATH environment variable. On Linux, add the lib directory path to the LD_LIBRARY_PATH environment variable as well. NOTE: For all that follows, is this directory where the new technology AC was unzipped. 3. Running the New Technology AC and SampleClient ------------------------------------------------- One of the samples (SampleClient) is built and included in the runtime package to allow easy testing of the success of your install. Step A. Generate Configuration Files -------------------------------- 1. Run /bin/SetConfig.{bat|sh} (Windows|Linux) (FROM THE /bin DIRECTORY!) 2. Edit agents/org.eclipse.tptp.TimeCollector/agent.xml if on Linux a. For Linux, make the value for the "Application executable" tag be "TimeCollector" (drop the '.\' prefix and '.exe' suffix) b. Do not remove the ConfigFile line from this file on any platform! Even though the file referenced does not exist, the line must be here or else the AC will not function properly. Step B. Start the New Technology Agent Controller ------------------------------------------------- 1. Open a command prompt window 2. Go to /bin directory 3. Enter the following at the command prompt: ACServer NOTE: On many Linux systems, you will need to precede the name with "./" in order for the executable to be found. Alternatively on Linux, the /bin/ACStart.sh command may be used to start the agent controller. NOTE: For ease of use in a backward compatibility environment, the AC may also be started up under the name "RAServer". NOTE: For Windows systems, the ACServer can be started as a Windows service. NOTE: For Windows Server 2003 systems, you will need to be Administator to start the ACServer. This will start the new technology Agent Controller (AC) at its configured port number. The AC reads the /config/serviceconfig.xml file to determine the location of the Process Controller agent (used to launch processes) and the location of other agent configuration files. See the TPTP web site for more detailed documentation. The AC starts the ProcessController agent then waits, listening for connection requests from clients and agents. Step C. Execute the Sample Client --------------------------------- 1. Open another command prompt window 2. Go to /bin directory 3. Enter the following at the command prompt: SampleClient NOTE: On many Linux systems, you will need to precede the name with "./" in order for the executable to be found. This will start the SampleClient application, which: (a) connects to the Agent Controller at the designated port number, (b) gets the "org.eclipse.tptp.TimeCollector" agentID (causing the AC to launch the TimeCollector executable if it is not running already), (c) establishes a data channel with the agent (through the AC) (d) sends 5 "Hello" messages to the agent (e) sends a start message to tell the collector to start collecting (f) sends a stop message to tell the collector to stop collecting (g) and waits for the user to press a key to indicate completion; (h) Meanwhile, after step (b), and in parallel with the remaining steps, the TimeCollector agent initializes itself and waits for a request from the client. Upon receiving the start message (step e) it starts its "collection" activity, which is to simply collect a timestamp and then send data to the client until it receives a stop message. (i) Each message sent over the data channel to the client is displayed (usually around 8 messages)on the client's console window (j) Pressing return will cause the client to terminate the agent and exit. Actual output for the SampleClient and the TimeCollector is shown at the bottom of this file. Step D. Troubleshooting with a Debug Log ---------------------------------------- If things don't appear to be working properly, include a log file of debug info when asking for help. The Agent Controller and agents print their debug messages to a common log file. Edit the file /config/serviceconfig.xml, changing the Logging level from INFORMATION to DEBUG. The output will go into the file /config/servicelog.log (by default; this too is configurable in the serviceconfig.xml file). 4. Available Packages --------------------- Both runtime and SDK packages are available. The SDK packages include the libraries, header files, API documentation and sample code for those writing new agents or clients. These APIs are for the new AC and are not supported by the older technology. 5. Building the New Technology Agent Controller and its Components from Source ------------------------------------------------------------------------------ The agent controller code is located in the dev.eclipse.org/cvsroot/tptp/platform/org.eclipse.tptp.platform.agentcontroller TPTP CVS module, with the new technology component being found in the src-native-new subdirectory. (With the 4.2 release, there are dependencies on source code found in the src-native subdirectory as well, though these are abstracted out into usage of the RAC's SDK package via an environment variable setting.) The build directory contains the top level make files which will build all of the component parts. tptp_ac.dsw Windows-IA32 workspace file for agent controller. Specifying the BuildMost project results in a complete build. BuildAll.mak64 Windows-{IPF|EM64T} NMAKE makefile for agent controller. tptp_samples.dsw Windows-IA32 workspace file for sample programs. Specifying the BuildAllSamples project results in a complete build of all included sample programs. BuildAllSamples.mak64 Windows-{IPF|EM64T} NMAKE makefile for sample programs. tptp_javaagent.dsw Windows-IA32 workspace file for Java base agent. Specifying the BuildAll project results in a complete build of the native library required for executing an agent written in the Java programming language. build_tptp_ac.script Linux-IA32 build script for agent controller. Executing this file will do a complete build, after some preliminary adaptations to the file are made; see below. build_tptp_ac.script64 Linux-{IPF|EM64T} build script for agent controller. Executing this file will do a complete build, after some preliminary adaptations to the file are made; see below. build_tptp_samples.script Linux build script for sample programs. Executing this file after successfully building with build_tptp_ac.script[64], and after similar adaptations are made, will build all the included sample programs. A. Dependencies 1) Compilers: - Windows-IA32: Microsoft Visual C++ v6.0 - Windows-IPF: Microsoft Windows Server 2003 SP1 Platform SDK - Windows-EM64T: Microsoft Windows Server 2003 R2 Platform SDK - Linux-{IA32|EM64T|IPF}: GNU gcc 2) Software: - Apache Xerces-C++ XML parser (http://xml.apache.org/xerces-c) v2.6.0 - Java, J2SE v1.4.2 or above (http://java.sun.com/j2se/index.jsp) B. Windows Build Instructions 1) Build/install the Xerces-C++ XML Parser v2.6, following the instructions on the http://xml.apache.org/xerces-c website. Set the environment variable XERCESC_HOME to point to the directory containing the Xerces include and lib directories. NOTE For EM64T and IPF Platforms: The standard 2.6 xerces from the apache web site will not compile without the following makefile modifications: (a) Remove "/machine:IX86" from the "XercesLib -Win64 {Debug|Release}" configurations LINK32_FLAGS specifications. (b) Add bufferoverflowU.lib to those same LINK32_FLAGS specifications. (c) [EM64T only:] Change /machine:IA64 to /machine:AMD64 for those same LINK32_FLAGS specifications. 2) Download the current RAC SDK from the download site at http://www.eclipse.org/tptp/home/downloads/downloads.php (i.e., tptpdc.win_.sdk-.zip) and unzip that package into a directory, then set the environment variable RAC_SDK_HOME to point to that directory. 3) Download the current CBE SDK from the from the download site at http://www.eclipse.org/tptp/home/downloads/downloads.php (i.e., cbe.win_.sdk-.zip) and unzip that package into a directory, then set the environment variable CBE_SDK_HOME to point to that directory. 4) Install Java - J2SE 1.4.0 or above and follow the install intructions on http://java.sun.com/j2se/index.jsp website. Set the environment variable JAVA_HOME to point to the directory containing the Java include and lib directories. 5) For Windows-IA32, open the agent controller MSVC++ workspace file, tptp_ac.dsw, located in the build directory. Under Project, Set Active Project to "BuildMost" and then under Build, select "Build". NOTE: Prior to running the resulting executables from within MSVC++, go to Project => Settings... and set the Working directory to point to the AC's bin directory. When running from a command line, execute the binaries from within the bin directory. For Windows-IPF and EM64T, open the appropriate Platform SDK command prompt windows (All Programs => Microsoft Platform SDK for Windows Server 2003 => Open Build Environment Windows => Windows Server 2003 64-bit Build Environment => Set Win Svr 2003 {IA64 for IPF | x64 for EM64T} Build Env), change directory to your installation build directory, and invoke "NMAKE BuildAll.mak64". 6) To build the C++ samples on Windows-IA32, open the MSVC++ workspace tptp_samples.dsw. Under Project, Set Active Project to "BuildAllSamples" and then under Build, select "Build". For Windows-IPF and EM64T, see step 2, replacing the makefile with BuildAllSamples.mak64. NOTE: The samples builds will fail if the AC build is incomplete. NOTE: The Agent Controller must be running prior to executing any of these samples in order for them to succeed. 7) To build the Java Base Agent, open the MSVC++ workspace tptp_javaagent.dsw. Set the JAVA_HOME environment variable to point to the directory where java is installed. Under Project, Set Active Project to "javaBaseAgent" and then under Build, select "Build". See the org.eclipse.tptp.platform.new.agentcontroller feature plugin for details on executing the java agent sample. C. Linux Build Instructions 1) Build/install the Xerces-C++ XML Parser v2.6, following the instructions on the http://xml.apache.org/xerces-c website. Set the environment variable XERCESC_HOME to point to the directory containing the Xerces include and lib directories. 2) Download the current RAC SDK from the download site at http://www.eclipse.org/tptp/home/downloads/downloads.php (i.e., tptpdc.linux_.sdk-.zip) and unzip that package into a directory, then set the environment variable RAC_SDK_HOME to point to that directory. 3) Download the current CBE SDK from the from the download site at http://www.eclipse.org/tptp/home/downloads/downloads.php (i.e., cbe.linux_.sdk-.zip) and unzip that package into a directory, then set the environment variable CBE_SDK_HOME to point to that directory. 4) Install Java - J2SE 1.4.0 or above and follow the install intructions on http://java.sun.com/j2se/index.jsp website. Set the environment variable JAVA_HOME to point to the directory containing the Java include and lib directories. 5) Add the AC's lib directory and $XERCESC_HOME/lib to the LD_LIBRARY_PATH environment variable. 6) Run the following build script files located in the build directory. You may need to run dos2unix if they were checked out in DOS format and add execute permissions (chmod a+x) on these files before executing them: build_tptp_ac.script[64] (add the 64 extension for IPF and EM64T) build_tptp_samples.script NOTE: By default the build scripts are set up to compile the files optimized. If instead you want a "DEBUG build", edit the files, comment out the OPTIMIZABLE line, and uncomment out the DEBUGABLE line so that it takes effect. NOTE: Execute the resulting binaries from within the bin directory. NOTE: See the org.eclipse.tptp.platform.new.agentcontroller feature plugin for details on executing the Java agent sample. 6. Expected Console Output for SampleClient ------------------------------------------- ------------------- SampleClient Console Output -------------------------------- Connected to the Agent Controller on "localhost" at port number ##### The Time Collector Agent ID: ### Established a data channel with the agent. Sending 5 Hello messages over data channel to TimeCollector ... Start the TimeCollector ... Incoming data: Hello from Time Collector Agent - Count 0 Incoming data: Hello from Time Collector Agent - Count 1 Incoming data: Hello from Time Collector Agent - Count 2 Incoming data: Hello from Time Collector Agent - Count 3 Incoming data: Hello from Time Collector Agent - Count 4 Stop the TimeCollector ... Incoming data: Hello from Time Collector Agent - Count 5 Incoming data: Hello from Time Collector Agent - Count 6 Incoming data: Hello from Time Collector Agent - Count 7 Incoming data: Hello from Time Collector Agent - Count 8 Incoming data: Hello from Time Collector Agent - Count 9 Incoming data: Hello from Time Collector Agent - Count 10 All finished Press any key to exit... --------------- SampleClient Console Output END --------------------------------