View source

{{TopNavigation|chapter=Tools}}

= Installing Tom =

== Requirements ==

{{tom}} is a {{java}} application written with JDK 1.5. {{tom}} is platform independent and runs on various systems. It has been used successfully on many platforms, including GNU/Linux distributions (Debian, Gentoo, Mandrake, Ubuntu), MacOS X,  FreeBSD, NetBSD, Windows XP, Windows Vista and Windows 7.

The only requirement to run and compile {{tom}} programs is to have a recent {{java}} Development Kit installed (version 1.5 or newer):

* {{java}} is available for download at [http://java.sun.com/javase/downloads/index.jsp java.sun.com]. If you do not know which package to choose, select [https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/ViewProductDetail-Start?ProductRef=jdk-6u13-oth-JPR@CDS-CDS_Developer Java SE Development Kit (JDK)]
* {{Tom}} can also be successfully used with the [http://openjdk.java.net/ OpenJDK] instead of the Sun-Oracle JDK

== Windows (simple install) ==

For a painless process, run the <tt>[https://gforge.inria.fr/frs/download.php/29258/tom-2.9_setup.exe tom-2.9_setup.exe]</tt> kit provided ([http://gforge.inria.fr/frs/?group_id=78&release_id=6495 downloads]). This will automatically update the environment as needed.

== Windows (manual install) ==

If for any reason you prefer to install {{tom}} manually, here is the procedure to follow:

We assume that Tom is installed in <code>C:\tom</code> (any other directory may be chosen). The following steps are needed for setting up the user variables of your environment:

* set<code> JAVA_HOME</code> to where Java JDK is installed (for instance: <code>C:\Program Files\Java\jdk1.6.0_13</code>)
* set <code>TOM_HOME</code> to <code>C:\tom</code>
* set <code>CLASSPATH</code> to <code>.;%TOM_HOME%\lib\tom-runtime-full.jar</code>
* set <code>PATH</code> to <code>%Path%;%TOM_HOME%\bin;%JAVA_HOME%\bin</code>

For a detailed description of setting environment variables in Windows, please refer to Windows documentation. For Windows XP, some information can be found [http://support.microsoft.com/default.aspx?scid=kb;en-us;310519&sd=tech here]
<br />

== Windows (with Cygwin) ==

We assume that Tom is installed in <code>c:\tom</code>. Please issue the following for setting up Tom:

   export TOM_HOME=/cygdrive/c/tom
   export PATH=${PATH}:${TOM_HOME}/bin
   export CLASSPATH=${TOM_HOME}/lib/tom-runtime-full.jar:${CLASSPATH}

{{note |  we recommend to add current directory <code>.</code> in your <code>CLASSPATH</code>. }}

== Unix ==

To install Tom, choose a directory (<code>${HOME}/tom</code> for instance) and copy the distribution files there. This directory will be called <code>TOM_HOME</code> in the following.

The following sets up the environment, for Bourne shell (sh) and C shell (csh) families:

 (sh)
   export TOM_HOME=${HOME}/tom
   export PATH=${TOM_HOME}/bin:${PATH}
   export CLASSPATH=${TOM_HOME}/lib/tom-runtime-full.jar:${CLASSPATH}

 (csh)
   setenv TOM_HOME ${HOME}/tom
   set path=( ${TOM_HOME}/bin $path )
   setenv CLASSPATH ${TOM_HOME}/lib/tom-runtime-full.jar:${CLASSPATH}

{{note |  we recommend to add current directory <code>.</code> in your <code>CLASSPATH</code>. }}

= Getting some examples =

Many examples have been written to test or illustrate some particular behaviors. This collection of examples is available: [https://gforge.inria.fr/frs/download.php/29257/tom-examples-2.9.zip tom-examples-2.9.zip] (see also [http://gforge.inria.fr/frs/?group_id=78&release_id=6495 downloads]).

Unzip the archive and use the tool Ant to compile the examples:
* Ant is available for download at [http://ant.apache.org ant.apache.org].

{{note | for Debian users, the <code>ant</code> package does not include the ant-optional java package, Debian (and Debian-based distributions like Ubuntu) users also need to install the <code>ant-optional</code> Debian package. }}

= Using Eclipse IDE =

The Eclipse platform (tested with versions 3.4 and 3.5) can be used to edit, compile, and run with {{tom}} program.
Eclipse is available for download at [http://www.eclipse.org www.eclipse.org].

== Installation ==
{{tom}} has to be installed using one of the previously described methods:
* simple Windows install: run <tt>tom-2.9_setup.exe</tt>
* manual install (Windows or Unix)

== Use Ant to compile an example ==
* import the examples as a project (create a Java projet and use the <tt>File->Import->General->Archive File</tt>)
* <tt>Window->Open Perspective->Other->Java (default)</tt>
* expand <tt>examples/addressbook</tt>
* <tt>Window->Show View->Other->Ant</tt>
* move the <tt>build.xml</tt> file to the Ant view
* click on the <tt>build</tt> target

== To run an example ==
* in the package explorer: <tt>right-click->refresh</tt> (or press <tt>F5</tt>) 
* open the "Run Dialog" box (<tt>Run->Run Configurations</tt>)
* select <tt>Java Application</tt>
* enter <tt>addressbook.AddressBookGom</tt> as <tt>Main class</tt>
* in the "Classpath" tab, select "User Entries"
** click <tt>Add External JARs</tt>, and select the JAR <tt><TOM_HOME>/lib/tom-runtime-full</tt>
** click on the <tt>Advanced</tt> button,  add <tt>examples/build</tt> using <tt>Add Folder</tt>

== Configure the editor ==
* use <tt>Windows->Preferences->General->Editors->File Associations</tt> to associate a <tt>Java Editor</tt> to <tt>*.t</tt> files

= Eclipse Plugin =

In parallel to {{tom}}, we also develop an Eclipse Plugin (for Eclipse 3.4 only) that integrates an editor and a compiler for {{tom}}.

The plugin is available directly from the Eclipse platform via the update link:
* <tt>Help->Software Updates</tt> or <tt>Help->Install New Software</tt>
* select <tt>Available Software</tt>, <tt>Add Site</tt>
* enter: <pre>http://tom.loria.fr/eclipse-update/stable</pre>
* select <tt>Tom plugin</tt> and click <tt>Install</tt>

{{note | if the plugin doesn't appear in list, uncheck "Group items by category"}}

To use the plugin:
* create a Tom projet (<tt>New->Project->Tom->Tom Project</tt>)
* in <tt>src</tt>, create a Tom file (<tt>New->Other->Tom->Tom File</tt>)

For more information, we invite the reader to use the integrated help (<tt>Help->Help Contents->Tom Online Help</tt>)

{{warning |  the  {{tom}} Eclipse Plugin is less stable than the main distribution. It is perfect for developping small projects, for teaching, etc. But we do not recommend to use it for large developments}}

= Contents =

The binary distribution of Tom consists of one of  the following directory layout:

  tom
   +--- bin (BSD Licence)
   |
   +--- lib 
   |     +--- tom-runtime-full (BSD Licence)
   |     |
   |     +--- tom-compiler-full (GPL Licence)                                                                                  
   |     
   +--- share (BSD Licence)
         +--- contrib
         |
         +--- man
         |
         +--- tom 
               +--- adt
               +--- c
               +--- caml
               +--- java


or (version with separate jars):

   tom
   +--- bin (BSD Licence)
   |
   +--- lib 
   |     +--- compiletime (not developed by the Tom project)
   |     |     +--- ant-antlr          // ant task for antlr
   |     |     +--- ant-contrib        // ant task for running regress tests
   |     |     +--- ant-junit          
   |     |     +--- ant-launcher
   |     |     +--- ant                // to compile the project
   |     |     +--- antlr3             // ant plugin for v3
   |     |     +--- junit              // to test the system
   |     |
   |     +--- runtime (BSD Licence)
   |     |     +--- shared-objects     // Factory of shared objects
   |     |     +--- jjtraveler         // Visitable interface
   |     |     +--- aterm              // ATerm library
   |     |     +--- tom-library        // support for strategies, bytecode, viewer, and xml 
   |     |     +--- emf                // support for Eclipse Modelling Framework
   |     |     +--- Bytecode           // ADT for ASM Bytecode library
   |     |     +--- TNode              // ADT for XML
   |     |
   |     +--- tom (GPL Licence)
   |     |     +--- tom                // Tom compiler
   |     |     +--- gom                // Gom compiler
   |     |     +--- GomADT             // ADT for Gom 
   |     |     +--- TomSignature       // ADT for Tom
   |     |     +--- plugin-platform    // plugin platform
   |     |     +--- PlatformAlert      // platform error messages
   |     |     +--- PlatformOption     // platform options
   |     |
   |     +--- tools (not needed by the runtime, unless you use bytecode, term viewer, or xml supports)
   |     |     +--- antlr-2.7.7        // to compile the Tom parser
   |     |     +--- antlr-3.2          // to compile the Gom parser
   |     |     +--- asm-3.0            // to manipulate bytecode
   |     |     +--- grappa1_2          // to visualize terms
   |     |     +--- xercesImpl         // for XML
   |     |     +--- xml-apis           // for XML
   |     |     +--- args4j-2.0.10      // for command line parsing
   |     |     +--- commons-lang-2.4
   |     
   +--- share (BSD Licence)
         +--- contrib
         |
         +--- man
         |
         +--- tom 
               +--- adt
               +--- c
               +--- caml
               +--- java




{{Navigation|chapter=Tools}}
[[Category:Documentation]]