Installation instructions
*************************


Installing on Ubuntu 10.10
==========================

Here are the instructions for installing **GCViewer Commandline** on Ubuntu 10.10.

*Note:* It should also be possible to run GC Viewer Command Line on any OS that runs Java 1.6.

Install Dependencies
--------------------

Java 1.6
^^^^^^^^

This application has been tested with **Sun's Java JDK**. It should also work with other flavours of Java.

First, see if you already have Sun Java installed:

.. sourcecode:: bat

    sudo update-java-alternatives -l

.. sourcecode:: bat

    java-6-openjdk 1061 /usr/lib/jvm/java-6-openjdk
    java-6-sun 63 /usr/lib/jvm/java-6-sun

In the text above, you can see that there are two flavours of Java installed:

* the openjdk flavour
* the Sun flavour


Otherwise, if you do not see the Sun flavour, then you can install **Sun's Java JDK**.

Installing Sun/Oracle's Java JDK
""""""""""""""""""""""""""""""""

For a guide on how to install Sun's Java on Ubuntu, see here:

`http://www.cyberciti.biz/faq/howto-ubuntu-linux-install-configure-jdk-jre/ <http://www.cyberciti.biz/faq/howto-ubuntu-linux-install-configure-jdk-jre/>`_

Set JAVA_HOME environment variable:
+++++++++++++++++++++++++++++++++++

You may need to add the JAVA_HOME environment variable to your ~/.bashrc file:

To edit the ~/.bashrc file:

.. sourcecode:: bat

    gedit ~/.bashrc

Add this line at the end of the file:

.. sourcecode:: bat

    export JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.06;"

Save your changes.

Close the text editor.

Finally, you can verify the install of Java:

.. sourcecode:: bat

    java -version

.. sourcecode:: bat

    java version "1.6.0_24"
    Java(TM) SE Runtime Environment (build 1.6.0_24-b07)
    Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02, mixed mode)

Maven
^^^^^

We use Maven to build the **GC Viewer** source code.

To install maven:

.. sourcecode:: bat

    apt-cache search maven

.. sourcecode:: bat

    maven-ant-helper - helper scripts for building Maven components with ant
    
    maven-repo-helper - Helper tools for including Maven metatada in Debian packages
    
    bnd - A tool to create and diagnose OSGi R4 bundles
    
    libantlr-maven-plugin-java - Maven ANTLR Plugin
    
    libclirr-maven-plugin-java - Clirr Maven Plugin
    ...
    ...

.. sourcecode:: bat

    sudo apt-get install maven2

.. sourcecode:: bat

    Reading package lists... Done
    Building dependency tree       
    Reading state information... Done
    The following extra packages will be installed:
    ant ant-optional antlr bsh bsh-gcj fop gcj-4.4-base gcj-4.4-jre-lib groovy
    ivy java-wrappers junit4 libantlr-java libasm2-java libasm3-java
    libavalon-framework-java libbackport-util-concurrent-java libbatik-java
    libbsf-java libclassworlds-java libcommons-beanutils-java
    libcommons-cli-java libcommons-codec-java libcommons-collections-java
    ...
    ...

To verify the installation, type this:

.. sourcecode:: bat

    mvn -version

.. sourcecode:: bat

    Apache Maven 2.2.1 (rdebian-4)
    Java version: 1.6.0_20
    Java home: /usr/lib/jvm/java-6-openjdk/jre
    Default locale: en_IE, platform encoding: UTF-8
    OS name: "linux" version: "2.6.35-22-generic" arch: "amd64" Family: "unix"


Compile the Source Code
-----------------------

Download the modified GC Viewer from :ref:`download`.

Unzip the ZIP file, to where you would like to have GCViewer installed.

Open a Terminal window.

Change directory to where you unzipped the zip file:

.. sourcecode:: bat

    cd /home/sean/sourcecode/thirdparty/gcviewer/
    gcviewer-1.29-src-modified__2011-03-05--18.55-
    reduced/gcviewer-1.29-src-modified

Make the build script be executable:

.. sourcecode:: bat

    chmod 755 run_build.sh

Run the build script: (this uses Maven to build the GC Viewer source code)

.. sourcecode:: bat

    ./run_build.sh

.. sourcecode:: bat

    [INFO] Scanning for projects...
    [INFO] ------------------------------------------------------------------------
    [INFO] Building GCViewer
    [INFO]    task-segment: [clean, install]
    [INFO] ------------------------------------------------------------------------
    ...
    ...

Maven will build the source code, and will output the compiled jar file to the ``./target`` directory.

Installation Complete
---------------------

You have completed the installation of GC Viewer Commandline.