Obtain Eclipse

Note that these instructions are written for installation of version 3.2.0, but may be generalizable to other versions of the IDE.

There are several alternatives available to obtain a copy of Eclipse for installation:

• download a current stable build of Eclipse from the Eclipse web site; note that the installation file is large (over 120 MB)
• note that a colleague may have a copy on CD already

Install Eclipse

• Unzip (or copy/unjar/check-out) the software (e.g., the downloaded file eclipse-SDK-3.2-win32.zip) into an appropriate location on your hard disk.
• These instructions are written assuming that you are running eclipse from C:\eclipse; if you are using a different path, adjust accordingly.
• Once the unzipped (copied/unjarred/checked-out) files are located on your filesystem, get started using Eclipse:
  • Run Eclipse by running C:\eclipse\eclipse.exe
  • The first time you run Eclipse, the workspace subdirectory will be created (C:\eclipse\workspace). This is where your projects (including the files you check out of CVS repositories) will live on your file system.
  • Many prefer to locate the Eclipse workspace at a location on the filesystem outside the Eclipse application tree, and to start Eclipse by referring to the workspace via a parameter. Here's how:
    • Exit Eclipse.
    • Create (or move existing) workspace subdirectory to the desired location, (e.g., C:\workspace).
    • Create a shortcut on your desktop with the following target (modified if you're using different directories):
      C:\eclipse\eclipse.exe -data C:\workspace -jvmargs -Xms640M -Xmx640
    • When you start Eclipse from the shortcut, it will use the new workspace directory.
    • Note that by using CVS (or an equivalent version control system) appropriately, a corrupted workspace can be easily rebuilt, by checking out appropriate projects.
  • It is advisable to pass JVM arguments to Eclipse at startup to reserve a larger memory space for the IDE than the default; the following arguments reserve 640 MB of memory: -jvmargs -Xms640M -Xmx640. Thus, to specify JVM arguments and a workspace (as above), the shortcut target would be the following (with modifications if you're using different directories):
    C:\eclipse\eclipse.exe -data C:\workspace -jvmargs -Xms640M -Xmx640

Familiarize yourself with the IDE

Read the Eclipse Welcome page, following links if you want more in-depth information.

The material/tutorials in the Help system are strongly recommended! Starting at Help:Contents, go through the Workbench User Guide and the Java Development User Guide. The investment will pay off handsomely in the enormous efficiency benefits that Eclipse offers a Java developer.

Set up CVS repositories

These instructions are written for Streek developers using the CVS server on canvas.berkeley.edu, but may be useful for those connecting to other repositories.

• If you haven't done so already in the course of going through the tutorials, identify the CVS repository (or repositories) you'll be using. The example in these instructions shows how to set up access to the respository canvas.berkeley.edu:/usr/local/cvsrep/org/ist, from which a Streek developer will be able to check out critical files (e.g., the ist-jxde tree)
• Set up CVS preferences for connecting to the repository using SSH, by navigating to Window:Preferences and performing the following steps:
  • Open the Preferences tree to view the pane for Team:CVS:Ext Connection Method
    • The CVS RSH command setting should be ssh2.exe where it is installed on your file system (e.g., C:\Program Files\SSH Communications Security\SSH Secure Shell\ssh2.exe)
    • The Parameters setting should be: {host} -l {user} [note: the parameter following the hyphen is a lower-case ell ("L")]
    • The CVS SERVER setting should be: cvs
    • If you skipped exchanging SSH public keys with canvas.berkeley.edu, do so now!
• Go to Eclipse's CVS Perspective (Window:Open Perspective:CVS Repository Exploring)
• Right-click to set up a New:Repository Location
• Fill in the blanks:
  • Host: canvas.berkeley.edu
  • Repository path: /usr/local/cvsrep/org/ist
  • User: yourUserIdHere
  • Password: leave this field blank ... no need to supply password if you exchanged public keys with CVS host
  • Connection type: ext
  • Use Default Port: selected
  • Valildate Connection On Finish: checked
• Click the Finish button; if the dialog was filled in properly, you'll see a new repository location in the CVS Perspective
• Other repositories that may be of interest to Streek developers include:
  • /usr/local/cvsrep/org/sis
  • /usr/local/cvsrep/proj/streek
  • /usr/local/cvsrep/third-party/misc
  • /usr/local/cvsrep/third-party/apache
  • /usr/local/cvsrep/third-party/jboss
  • /usr/local/cvsrep2/berkeley/streek

Configure CVS file mappings

As delivered, Eclipse's CVS client is ignorant of the nature (ASCII or Binary) of certain types of files that you may wish to check into the repository. It is important that you identify file types correctly rather than check in files of unknown types.

Navigate to Windows : Preferences : Team : File Content to view the known file mappings. It is a good idea to add at least the following in addition to the defaults:

• *.bat (ASCII Text)
• *.csh (ASCII Text)
• *.css (ASCI Text)
• *.dtd (ASCII Text)
• *.ehtml (ASCII Text)
• *.ent (ASCII Text)
• *.jsp (ASCII Text)
• *.ksh (ASCII Text)
• *.macrodef (ASCII Text)
• *.sh (ASCII Text)
• *.sql (ASCII Text)
• *.tld (ASCII Text)
• *.xhtml (ASCII Text)
• *.xmap (ASCII Text)
• *.xmi (ASCII Text)
• *.xsd (ASCII Text)

Check out projects from CVS

Minimally, Streek developers should check out the ist-jxde project (instructions given below). The maven-repo-j5 project is needed by developers building with released versions of streek jar files, and/or those building applications that compile/run on Java 5. Those who still require local builds of Streek from source should check that project out. The current application server used in Streek projects is another basic dependency (as of 07.19.2006, the current app server is jboss-4.0.3, in the canvas repository usr/local/cvsrep/third-party/jboss; those still maintaining apps that run on Java 1.4 will more likely be using jboss-3.2.5). Other check-outs and repositories may be appropriate depending on the project(s) in which each developer will participate.

Note that if you wish to specify a project's type (e.g., for a Java Project - one with Java code in the source tree, such as Streek), and are downloading it into the local workspace for the first time, you should use the CVS check-out option: Check out as project configured using the New Project Wizard.

Example: to check out the ist-jxde tree from the repository usr/local/cvsrep/org/ist:

• Go to Eclipse's CVS Perspective (Window:Open Perspective:CVS Repository Exploring)
• Open the HEAD tree in the org/ist repository.
• Right click ist-jxde and select the option: Check out as project in the workspace
• Call the project ist-jxde if asked for a project name.
• Watch the files fly by...

Additional configuration steps

Additional configuration steps include setting critical environment variables; adding to the Ant runtime classpath; and installing useful plugins.

• Local information on how environment variables are set in Windows can be found here). Environment variables necessary for building projects in Eclipse are listed below:
  • JAVA_HOME should be set to the root directory of your Java installation, e.g., C:\jdk1.5.0_06
  • CVSHOME should be set to your Eclipse workspace, e.g., C:\workspace
  • IST_JXDE_HOME should be set to the place you store files checked out from the ist-jxde project in CVS, e.g., C:\workspace\ist-jxde
  • MAVEN_HOME should be set to the place you store files checked out from the maven repository project in CVS, e.g., C:\workspace\maven-repo-j5
  • FORREST_HOME, JBOSS_HOME, and TOMCAT_HOME should be set once Forrest is installed on your system (it's best to check the Forrest software out from CVS repository third-party/apache rather than downloading it from the project site, as described here), and once Jboss-Tomcat is checked out from the CVS third-party/jboss repository, respectively.
• Check in Window:Preferences: Java:Installed JREs to be sure that the correct JRE(s) - the one or ones in which you'll be developing - are installed. Add additional JREs as necessary, and select the one you'll use most regularly (especially for new projects) as the default.
• Refer to Recommended Eclipse Plugins to identify, download, and install the plug-ins you'll need for Streek development.
• Ant tweaks for Eclipse 3.2.0:
  • Navigate to the Ant Runtime preferences (Window:Preferences: Ant:Runtime)
  • Choose the Classpath pane
  • You need to add these JAR files to the Global Entries of Ant's Runtime Classpath from the indicated directory (mostly IST_JXDE_HOME/lib - see previous step - you probably just downloaded the ist-jxde files into your Eclipse workspace). Note that you use the Add JARs button for additions from within your workspace; and the Add External JARs button otherwise.
    • xercesImpl.jar from your IST_JXDE_HOME/lib directory
    • xml-apis.jar from your IST_JXDE_HOME/lib directory
    • ant-contrib-0.6.jar from your IST_JXDE_HOME/ant/lib directory
    • junit-3.8.1.jar from your MAVEN_HOME/junit/jars directory
    • xml-commons-resolver-1.1.jar from your FORREST_HOME/../../lib/core/ directory (cf. Building Forrest within Eclipse for more info)
• Set file encoding to UTF-8:
  • Navigate to the Workbench Editors preferences (Workbench:Editors)
  • Change the text file encoding to UTF-8
• Navigate to the main Workbench preferences page, and clear the checkbox "Build automatically."
• Refer to Configuring Oxygen... once Oxygen and Forrest are installed to configure validation based on the Forrest DTDs referred from its catalog files.