Home » Documentation » Package

Installation Guide

Submitted by siteadmin on Wed, 2006-10-18 10:04.

Description

This page describes the system requirements needed to install MBT, and, it describes how to install the toolkit from the distribution files.

If you have not yet downloaded the latest distribution files, you will need to do so before continuing the installation process.

See also: Downloads, Installation Guide, Build Guide, Programmers Guide, Toolkit API.

System Requirements

This toolkit is meant to run on a wide range of personal computer systems. While we have tested the software on low-end notebooks through high-end desktop workstations, some of the more advanced features of this software place more demands the requirements of the system. The basic recommendations are as follows:

    Operating system

    We have run MBT applications under Windows, Linux, and Mac OS X. We expect that it should run under Solaris, HPUX, AIX, and IRIX since the vendors of those platforms have made implementations of Java and Java3D available.

    Java

    We have built and run MBT application using versions of Java from 1.2.1 through 1.5 and beyond. While some vendors supply and even pre-install a Java environment with their operating systems, other vendors choose not to do so. In this case, you may have to download and install the Java package yourself. In the "Installation" section of this document, we will help you with this process.

    3D Rendering Library for Java

      JOGL

      The GlStructureViewer (the 3D viewer module that was developed for MBT 2.0) uses the OpenGL binding for Java called JOGL. This is an open-source toolkit which is available from the JOGL API Project web site. If you do not have JOGL installed, we will help you with the process of installing it in the "Installation" section of this document.

      Java3D

      The StructureViewer (the 3D viewer module that was developed prior to MBT 2.0) uses the a scene-graph Java API called Java3D. This is an open-source toolkit which is available from the Java3D API Project web site. If you do not have Java3D installed, we will help you with the process of installing it in the "Installation" section of this document.

    A video card that supports accelerated 3D graphics.

    Rendering high-quality 3D graphics is compute-intensive. Any of the current generation of consumer graphics cards that use the nVidia or ATI chip-sets should do quite nicely. They support hardware-accelerated transform and lighting engines (in addition to very high polygon rendering and pixel fill rates) that make interactive 3D graphics quite responsive. While many people assume that rendering 3D graphics from Java would be slow, the lion's share of the heavy lifting involved in rendering is really done outside of Java. And, MBT's 3D StructureViewer module will take advantage of your native video driver and its hardware-accelerated 3D graphics capabilities.

    Only the 3D StructureViewer component of this toolkit needs a 3D graphics environment to run. All other software components will run quite happily with no 3D graphics capabilities. If you're application does not use that component, then your application will also not require end-users or host systems to have 3D capable systems.

    An internet connection.

    While an internet connection is not required, without it you will not be able to take advantage of the RcsbStructureLoader component's ability to provide "live" PDB site access to the tens-of-thousands of deposited structures by simply providing a PDB ID code to the toolkit's structure loading interface.

    Without an internet connection, you'll still be able to load data sets from local files.

    Available system memory (RAM) of 100MB or more.

    In our testing of MBT code, the JVM plus the toolkit combined often require less than 64MB of free memory to completely load and display 3D representations of the "average" protein data bank structure. Some larger entities (some viruses, ribosomes, and large biological units) require more memory. Also, if you're going to load and view multiple structures at the same time, you'll need more than the minimal 64MB of memory (which is the default JVM heap size).

    When loading large or many structures, you may have to make more memory available to the JVM. Most "java" commands will accept the "-Xmx###mb" and "-Xms###mb" command line options. This enables you to set the maximum and initial JVM heap sizes to the desired number of megabytes.

Installation

    MBT Software

    1. Create an "mbt" directory.

      2. If you have not done so already, its probably a good idea create a directory on your local system in which to place the downloaded mbt software components. Choose any location for the directory in which you want to work with the toolkit. Create and name the directory something meaningful ("mbt", for example).

    2. Place the distribution files into your "mbt" directory.

      3. If you have already downloaded any distribution files into another directory, go ahead and move them into your "mbt" directory now. You can place any or all of the release notes, source, docs, or binary jar files there. The distribution file names may include:

        mbt_VERS_rel.html
        mbt_VERS_docs.jar
        mbt_VERS_bin.jar
        mbt_VERS_src.jar

      where VERS is the version number of the distribution (eg: 1.0.0).

      Most developers will probably want at least the "src" and "docs" jar files. The contents of the "bin" archive can be generated by building (compiling) the contents of the "src" archive. And, the API documents can be generated by from the "src" archive using the javadoc tool (though, this will not include the Programmer's Guide).

    3. Extract the "src" and "docs" jar file contents.

      1. Open a command shell window.

        2. You'll need to run Java's "jar" command to extract the jar file contents. Under the Windows operating system, you'll run the "Command Prompt" application. Under Mac OS X, you'll launch the "Terminal" program. Under UNIX, you'll want to open an "xterm" or other terminal application window.

        Refer to your operating system's documentation for more details.

      2. Change directory to your "mbt" directory.

        3. In your command shell window, change directory ("cd") into your "mbt" directory.

        Refer to your operating system's documentation for more details.

      3. Extract the "docs" jar file contents.

        4. In your command shell window, run the command:

        jar xf mbt_VERS_docs.jar

        This will extract the following items:

          README
          index.html
          docs/ (directory)

      4. Extract the "src" jar file contents.

        5. In your command shell window, run the command:

        jar xf mbt_VERS_src.jar

        This will extract the following items:

          examples/ (directory)
          src/ (directory)

    JOGL and Java3D

    1. Make a libs directory in your top-level "mbt" directory.

    2. Download the binary distribution packages that correspond to your operating system and computer architecture from the project web sites into the "libs" directory.

    3. Extract the contents of the binary distributions into the "libs" directory.

    4. Arrange the extracted files within the "libs" directory so that all of the ".jar" files and shared library files (eg: .so .jnilib .dll etc) are in the top-level of the libs directory. This arrangement will match the classpath used in the default ant build.xml file that is supplied with the toolkit.

You should now be ready to compile the distribution! If you have successfully extracted the items from the distribution files, you're now ready to move on to the Build Guide.