Installing Hyades

In order to install and use the profiling and logging features of the Hyades project, follow these steps:  

1. Go to http://www.eclipse.org/hyades and click on the 'Download Page' link



2. This page displays the Hyades builds that are available for download. There are three different type of builds (Latest Releases, Stable Builds, Weekly Development Builds). To see the difference between these builds, click on the 'builds' link available at the top of the page. We're going to download the latest release so click on build name 1.3.0



3. This page includes the Hyades products available for download as well as the links to the products/plug-ins required by Hyades. First we'll download all the requirements before downloading Hyades Runtime. Download and install Eclipse 2.1.0 or later by following the 'Eclipse' link listed under the Requirements section.
   Alternatively, you can directly access the Eclipse download page from: http://download.eclipse.org/downloads/index.php
   
   Hint: When unzipping any of the files mentioned in this document, use the -a (e.g. auto-convert any text files) option (or similar for your unzip utility) to convert end of line characters in all text files to their native format.



4. Download EMF 1.1.0 or later by following the 'Eclipse Modeling Framework (EMF)' link. Alternatively, you can directly access the EMF download page from: http://download.eclipse.org/tools/emf/scripts/downloads.php 
   Unzip the zip file into the Eclipse home directory that was created when you installed Eclipse in the previous step (the contents of the plug-in directory from the zip file should be extracted into the plug-in directory for the eclipse installation directory.)



5. Download GEF 2.1.0 or later by following the 'Graphical Editing Framework (GEF)' link. Alternatively, you can directly access the GEF download page from: http://download.eclipse.org/tools/gef/downloads/. 
   Unzip the zip file into the eclipse directory in the same way that the zip file for EMF was extracted (the contents of the plug-in directory from the zip file should be extracted into the plug-in directory for the eclipse installation directory.)



6. Download XSD 1.1.1 or later by following the 'XSD Runtime' link. Alternatively, you can directly access the XSD download page from: http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/xsd-home/downloads/dl.html. 
   Unzip the zip file into the eclipse directory in the same way that the zip file for EMF was extracted (the contents of the plug-in directory from the zip file should be extracted into the plug-in directory for the eclipse installation directory.)



7. Now you're Eclipse platform is ready for the Hyades products. Download the Hyades driver (Labeled as 'Hyades Runtime').
   Unzip the zip file into the eclipse directory in the same way that the zip file for EMF was extracted (the contents of the plug-in directory from the zip file should be extracted into the plug-in directory for the eclipse installation directory.)
   
   Note: You will need a 1.3 level Java runtime or Java development kit (JDK) installed on your machine in order to run Hyades. Also note that the 'Hyades Data Collection Engine' is required in order to be able to profile Java applications locally/remotely. You will also need this engine if you wish to import log files remotely (but not locally). The rest of this document will discuss how to download and start this engine.



8. To download the Hyades Data Collection Engine, click on one of the links labelled 'Hyades Data Collection Engine for <platform>'. Where <platform> is the desired platform. Installing this engine on a machine allows Java applications to be profiled and log files to be imported from that machine.



9. Extract the downloaded zip file into a directory of your choice (e.g.  c:\raserver). To setup and run the collection engine on Windows and NON-Windows platforms follow the steps below.



10.   Setting up and running the collection engine on Windows:
    
    
    1. In the command prompt, switch to the bin directory of the engine (e.g. c:\raserver\bin). Run the script file SetConfig.bat. You will need the Java Runtime Environment (JRE) included as part of your path in order to run this file. This batch file will prompt for the location of the (JRE) that the engine should use (e.g., c:\jdk1.4.1\bin). It also prompts for the hosts that should be given permission to access the server.  If you are intending to only use your own machine for profiling Java application or importing log files, then the default (LOCAL) will be sufficient.  The output of this script file will be a file called serviceconfig.xml placed under the config directory of the engine's location (e.g. c:\raserver\config). You may edit this file manually. The rules are documented in the DTD file serviceconfig.dtd, in the 'dtd' directory of the engine's location.
    
    
    2. Add the bin directory to the system's PATH environment variable (e.g. c:\raserver\bin). NOTE: Do NOT encase the environment variable's value in double quotes
    
    
    3. To run the server as an Application:
       Set the RASERVER_HOME environment variable to point to the home directory of the Collection Engine (e.g. c:\raserver). The server will use this environment variable to locate the configuration file. NOTE: Do NOT encase the environment variable's value in double quotes Start the server by running the RAServer.exe from the 'bin' directory. Stop the server by terminating the RAServer.exe process (e.g. closing the command shell).
    
    
    4. To run the Server as a Windows Service: Remove and/or uninstall all existing installations of the Hyades Data Collection Engine. Run the 'manageservice.exe' from the 'bin' directory. This creates the Windows service. The syntax is:
       manageservice add "<service name>" "<home directory of Collection Engine>"
       For example:
       manageService add "Hyades Data Collector" "C:\raserver"
       You can now start and stop the server using the Windows' Services panel or with the Windows' 'net' command. To uninstall the server Windows service, run the 'manageservice.exe' from the 'bin' directory to delete the Windows' service. For example:
       manageservice remove "Hyades Data Collector"
       NOTE: If you are prompted with an error message similar to the one below while attempting to start the engine, then chances are you have not specified the correct path of the engine.




11.   Setting up and running the collection engine in a NON-Window platform:
    
    Note: Please consult the "getting_started.txt" file, included with the download, if you intend to run the engine for an iSeries or zSeries platform.
    
    
    
    1. Include the 'lib' directory of the engine's location in the environment variable used for locating libraries. You will need to export the variable after updating its value:
       (AIX):
             LIBPATH=$RASERVER_HOME/lib:$LIBPATH
      export LIBPATH
       (HP-UX):
             SHLIB_PATH=$RASERVER_HOME/lib:$SHLIB_PATH
      export SHLIB_PATH
       (Linux X86/390 or Solaris):
      LD_LIBRARY_PATH=$RASERVER_HOME/lib:$LD_LIBRARY_PATH
      export LD_LIBRARY_PATH
    
    
    2. Add the <home directory of Engine>/bin directory to the system's PATH environment variable.
    
    
    3. Set the RASERVER_HOME environment variable to point to <home directory of Engine>. The server will use this environment variable to locate the configuration file.
    
    
    4. Ensure that the files in the <home directory of Engine>/bin and <home directory of Engine>/lib directory are executable.
    
    
    5. Generate the configuration file that provides the rules for which applications that can be executed with the server. This can be accomplished by running the <home directory of Engine>/bin/SetConfig.sh script. Run this script from a command shell in the <home directory of Engine>/bin directory. This step will require that a Java Virtual Machine (JVM) be present in the system's PATH. Follow the prompts and the output will be the <home directory of Engine>/config/serviceconfig.xml file. This is a sample of the configuration file that will be used by the server when it is started. You may edit this file manually using the rules documented in the <home directory of Engine>/dtd/serviceconfig.dtd file. To load any changes, restart the server.
    
    
    6. Ensure that the <home directory of Engine>/bin/RAServer file is executable.
    
    
    7. Start the server by running <home directory of Engine>/bin/RAServer.
    
    
    8. Stop the server by terminating the RAServer process. For example:
       kill -s INT <Engine's PID>
       NOTE: This step may require root authority. NOTE: On some Linux installations, each thread within a process has a unique PID. Terminate the lowest PID to terminate all PID(s).