Eclipse Cookbook

This cookbook is intended to be used for installing and configuring the Eclipse Integrated Development Environment (IDE) on Windows 10. I used Eclipse as part of my content management system because it allowed me to integrate a Git plugin (which in turn allowed me to version-control my content), and it allowed me to use the ReST editor plugin.

Key concepts

Before I go into the details, I thought it best to explain a few Eclipse concepts first.

Workbench

The term Workbench refers to the desktop development environment. The Workbench aims to achieve seamless tool integration and controlled openess by providing a common paradigm for the creation, management, and navigation of workspace resources. Each Workbench window contains one or more Perspectives. Perspectives contain Views and Editors, and control what appears in certain menus and tool bars. More than one Workbench window can exist on the desktop at any given time.

Workspace

A Workspace is a conceptual construct. It’s a container for a multiple Eclipse projects.

Note

You must separate your Git repo from your Workspace (no overlap). Both are constructs for organizing project files, and conceptually, both exist in an abstraction layer on top of the file system. It’s important to understand the difference here because you’ll run into trouble later if you don’t keep the two paradigms separate.

Requirement: install the JDK first

Eclipse was written in Java, is hosted in a Java Virtual Machine, and was primarily designed for Java software development. As such, a fundamental requirement for running it is a Java Develoment Kit (JDK) deployment. The JDK is a superset of the Java Runtime Environment (JRE) - the bits you need in order to run Java applications.

  1. Get the latest version of the JDK by visiting: Oracle Java SE Downloads. There are several versions to choose from. Which one should you get? I recommend Java Platform, Standard Edition.
  2. On the Java SE Downloads page, in the section Java Platform, Standard Edition, click JDK Downloads. You land on the Java SE Development Kit 8 Downloads page.
  3. Accept the license agreement (click the “Accept License Agreement radio button), and then click the download link for the latest version of the Windows x64 release. When the Run/Save toast appears, click Run.
  4. Accept all defaults except the “install to” location; for that, see the next subsection.

Where to install

I’m going to follow the Linux Filesystem Hierarchy Standard and create an /opt directory on the root of my C: drive; and then I’ll install all of the open source software beneath it. The hope is to create a [somewhat] portable installation.

  1. The default location was C:\Program Files\Java\jdk1.8.0_60\, but I changed it to C:\opt\Java\jdk1.8.0_60\). I.e., in the fully-qualified path name, simply replace “Program Files” with “opt”.

Note

I was going to truncate the version number from the end of the path name, but I changed my mind: I thought there might be a good reason why Oracle included these details. I kept the version number for these docs because I felt it wasn’t that important that I genericize the docs by using jdkx.x.x_xx.

  1. Half-way through the JDK installation, the JRE installation begins, and the installer presents you with the option to change the install location from C:\Program Files\Java\jre1.80_66 to a different folder. Again, simply replace “Program Files” with “opt”.

In the case of the JRE, you can’t simply select Program Files and type opt overtop of it. You’re forced to navigate a path selection dialog down to “C:\opt\Java”, and create a new folder (“\jre1.8.0_66” in my case).

Note

Interestingly, the installer actually installed three copies of the java runtime.

C:\opt\Java\jdk1.8.0_66\bin\java.exe (java runtime for private use by the IDE). * Choose this one for your JAVA_HOME in order to get the tools.jar to work!

C:\opt\Java\jdk1.8.0_66\jre\bin\java.exe (java runtime for private use) * I used to point JAVA_HOME here, but Ant doesn’t work if you do!

C:\opt\Java\jre1.8.0_66\bin\java.exe (java runtime for public use). Use this one for %JAVA_HOME%.

Note

I also found java.exe in another location:

“C:\ProgramData\Oracle\Java\javapath”

… and this line was also added to the beginning of my path statement. I don’t know how this got there!?

Setup system environment variables

The use of System Environment Variables makes installations portable. To add new System environment variables:

  1. Right-click the Start button.

  2. Click Control Panel.

  3. Click System and Security.

  4. Click System.

  5. Click Advanced System Settings.

  6. In the System Properties dialog that appears, click Advanced > Environment Variables.

  7. Add the following two new System environment variables:

    POSIX_HOME = C:\opt\

    JAVA_HOME = %POSIX_HOME%\Java\jdk1.8.0_66\

Note

In order to get Ant to work properly, you have to set JAVA_HOME to point to the java.exe in the JDK - so Ant can find the file tools.jar.

Add the path to the Java executable to the path system environment variable

Adding the location of application execuatbles to the Path statement makes them portable in that it gives you the flexability of running pathed executables from any directory.

  1. Add the following string the end of the Path statement (i.e., to the Path System environment variable).

    ;%JAVA_HOME%\bin\

Note

The \bin directory contains the executable file java.exe.

Install eclipse

  1. Get the latest version of Eclipse by visiting: Eclipse Downloads <http://www.eclipse.org/downloads/>_.

  2. From the Eclipse Downloads landing page, click Eclipse IDE for Java Developers > Windows 64 Bit.

    When the Run/Save toast appears, click Save.

    When you click Run, the Eclipse Installer by Oomph runs.

  3. Accept the installer default installation directory:

    C:\java-neon

  4. Set the option “Run this program as an administrator” on the Eclipse executable (i.e., on the file “C:\opt\eclipse\eclipse.exe”).

  5. Pin the executable to the Taskbar. You can do this by Ctrl + clicking & dragging from File Explorer to the Taskbar.

    You’re done. Go ahead and launch Eclipse.

Configure eclipse on first launch

The first time you run Eclipse, you’re presented with a dialog that allows you to select a Workspace.

Workspace

Accept the default location for your Workspace.

%USERPROFILE%\workspace

Check “Use this as the default and don not ask again”.

Note

If you’re reinstalling Eclipse, you mustn’t reuse the same default location for your workspace - this will corrupt your Eclipse installation. I learned this the hard way because I’d been using C:\Users\Chris\workspace, and I wanted to use that directory again; so I made a copy of it and saved it (into E:\Safe\workspace), and then cleaned C:\Users\Chris\workspace.

Check for updates

Before you start installing addins to Eclipse, make sure you’re working with the latest version (build) of Eclipse.

  1. To update Eclipse, click Help > Check for Updates

    Check the Status Bar for the update task’s progress.

Set preferences

In Eclipse, click Window > Preferences, and then systematically go through the items in the hierarchical menu in the left pane - and check each item’s configuration.

General

Appearance

Enable: Enable Animations

Compare/Patch/ > Text Compare

Enable: Initially show ancestry pane

Error Reporting

Enter your name and e-mail address

Workspace

Enable: Save automatically beforfe build

Enable: Show workspace path in window title

Text file encoding: Other > UTF-8

Ant

Editor

Enable: Mark occurrences of the selected element in the current buildfile

Install/Update

Automatic Updates

Enable: Configure Eclipse so it automatically updates each time you start it.

Java

Editor

Folding

Enable: Comments, Inner types, and Members

Hovers

Enable: Combined Hover

Typing

Enable: Automatically insert at correct position > Semicolons > Braces

Team

Enable: Shwo the file author in compare editors

Git

History

Enable: E-mail addresses in Author/Committer columns

Update errors

If the update process fails, throwing errors like this:

No repository found containing: osgi.bundle,org.eclipse.aether.api,1.0.1.v20141111 No repository found containing: osgi.bundle,org.eclipse.aether.connector.basic,1.0.1.v20141111 No repository found containing: osgi.bundle,org.eclipse.aether.impl,1.0.1.v20141111

Then you need to refresh the list of “Available Software Sites.”

To do so, select them all in Preferences > Install/Update > Available Software Sites, and then click Remove.

Any easy way to add them back is to Import the file named bookmarks.xml with the following content:

bookmarks.xml

<?xml version=”1.0” encoding=”UTF-8”?> <bookmarks>

<site url=”https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”Android Developer Tools (ADT)”/> <site url=”http://download.eclipse.org/recommenders/updates/stable/” selected=”true” name=”Code Recommenders Stable Update Site”/> <site url=”http://download.eclipse.org/releases/luna/” selected=”true” name=”Eclipse Luna”/> <site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen”/> <site url=”http://pydev.sf.net/updates/” selected=”true” name=”PyDev Update Site”/> <site url=”http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/> <site url=”http://jautodoc.sourceforge.net/update/” selected=”true” name=”update site: http://jautodoc.sourceforge.net/update/”/>

</bookmarks>

Add common libraries

When I was experimenting with Java projects, I continually ran into instances where projects depended on external libraries (JSON, IO, etc.). After downloading a few of them, I simply downloaded several of them - so I’d always have then on hand.

Visit: http://commons.apache.org/

http://projects.apache.org/indexes/quick.html

http://mirrors.sonic.net/apache/

ftp://mirror.reverse.net/pub/apache/

Customize eclipse with addins

You can enhance Eclipse’s standard functionality by adding addins.

Help > Install New Sortware

Work with: –All Available Sites–

Peruse the list that appears - and pick out the plugins you want.

Get for sure

This plugin adds so many useful features to Eclipse, that I bought a license for myyself. It gives you a ton of editors (e.g., HTML), and each one runs against the associated DTD or schema - to ensure that your code is well formed.

  1. Get the latest version of the oXygen XML Editor for Eclipse by visiting: Download oXygen XML Editor <http://www.oxygenxml.com/download_oxygenxml_editor.html?os=Eclipse#eclipse_install_instructions>_.

    The download landing page is a bit confusing. Scroll up to the top of the page and simply click the Download button.

    Another web page appears, prompting you to fill in a form. Ignore it - the download begins automatically.

    Click Save instead of Open - in case there’s a problem with the download.

    The download takes about ten minutes.

  2. After downloading the corresponding archive, use 7-Zip to extract its content into the “dropins” subfolder of the Eclipse folder.

  3. Restart Eclipse.

    Eclipse discovers the new addin and configures it for you.

Update the oXygen XML editor plugin

Help > Install New Software…

Add the oXygen XML Editor software update endpoint URI: http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml

Paste this URI into the “Work with” field, and then click “Add”. The main window will show the work “Updating…”. When it is done, the list of updates, per Eclipse version displays. Check the box beside the latest version, and then click “Next”. The updates download and install, and then you must restart Eclipse for the changes to take effect.

Install PyDev from the Eclipse Marketplace.

After you install PyDev, you’ll be asked to reboot Eclipse.

Open the PyDev perspective to make sure that it installed properly.

When you reboot Eclipse, Eclipse might discover that PyDev has an incomplete configuration. If it does, it presents you with choices for configuring it (Auto, Manual, Quick Auto, etc.). Choose Quick Auto.

You need this so you can run Sphinx and rebuild the docs for the 3rdParty REST API docs. You need ReST Editor in order to configure a Build Configuration that will run Make.bat.

The ReST Editor is an Eclipse plugin, and it adds a pretty reStructuredText editor to the Eclipse IDE. This is useful for authoring documentation for Python project - where you use the Sphynx doc builder to automatically generate help builds.

Install it from the Eclipse MarketPlace.

The ReST Editor project is an open source project, and the code is hosted on the project site.

Note: The ADT plugin for Eclipse in no longer the official IDE for Android development; it’s now Android Studio, so you should install it at some point.

Follow the procedure on the “Installing the Eclipse Plugin” web site: http://developer.android.com/sdk/installing/installing-adt.html

Configuration

Target Location for the Android SDK: %POSIX_HOME%\android-sdks

Add new software

  • eclipse : the Eclipse update site, accessible via the URL : http://resteditor.sourceforge.net/eclipse.

Tryout

Modelling > Sphinx SDK (Incubation) Modelling > UML2 Extender SDK Programming Languages > Javascript Development Tools Programming Languages > PHP Development Tools (PDT)

Update eclipse

The Updater service in Eclipse is based on Equinox p2, the Equinox framework OSGi implementation.

The OSGi (Open Service Gateway initiative) specification describes a modular system and a service platform for the Java programming language that implements a complete and dynamic component model, something that does not exist in standalone Java/VM environments.

When you run Help > Check for Updates, the Updater checks for system and component (addin) updates according to a list of “Available Software Sites” - which are p2 repositories. p2 stand for “Provisioning”.

Preferences > Install/Update > Available Software Sites

In my experience, this mechanism is buggy. You have to manually tweak the list (by adding, deleting, and editing) the items in the list.

http://wiki.eclipse.org/Eclipse_Project_Update_Sites

Here’s a list of URLs that you can visit to find the latest Update URI for a particular component.

<?xml version=”1.0” encoding=”UTF-8”?> <bookmarks>

<site url=”https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”ADT Plugin”/> <site url=”http://download.eclipse.org/webtools/updates” selected=”true” name=”Eclipse Web Tools Platform Repository”/> <site url=”https://sourceforge.net/projects/eclipsejsonedit/files/update” selected=”true” name=”eclipse-json-editor”/> <site url=”http://e-p-i-c.sf.net/updates/” selected=”true” name=”EPIC - Perl Editor and IDE for Eclipse”/> <site url=”http://nextinterfaces.com/http4e/install/” selected=”true” name=”HTTP4e”/> <site url=”http://download.eclipse.org/mylyn/releases/luna” selected=”true” name=”Mylyn for Eclipse Luna”/> <site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen XML Editor Install”/> <site url=”http://pydev.org/updates/” selected=”true” name=”PyDev Update Site”/> <site url=”http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/> <site url=”http://download.eclipse.org/releases/luna/” selected=”true” name=”The Eclipse 4.4 (Luna) Updates”/> <site url=”http://download.eclipse.org/webtools/repository/luna” selected=”true” name=”The Eclipse Web Tools Platform (WTP) software repository”/> <site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse” selected=”true” name=”update site: http://www.oxygenxml.com/InstData/Editor/Eclipse”/>

</bookmarks>

Here’s what I did to update to Luna, and then to bring the rest of my installation in line (with the Luna bits).

Setup a git-hosted project in eclipse

If you’re used to using Visual Studio and Source Depot, then you’re in for a bit of a paradigm shift when you use Eclipse and git.

..Note:
The location of your Eclipse Workspace, and the location of your source code are mutually exclusive. I.e., you might think that the workspace should encompass your local git repo - but it doesn’t, and actually can’t. For example, I have all of my local repos on the C: drive (in C:\Users\Chris\src\), yet I have my default Workspace on my A: drive (in A:\Documents\Eclipse\Projects\).

Think of it like this: when a multi-media app manages your music collection, it doesn’t move all of your media files into it’s program directory. Instead, it builds a database the contains records for corresponding media files. Each record contains a pointer to the media file, along with all of the details contained in its ID3 tag.

You’re doing something similar when you build a an Eclipse Workspace. In the case of Eclipse though, the database is stored in a “Workspace;” a folder on your file system that contains a folder called “.metadata”.

Window > Preferences > Teams > Git

Default Repository Folder (Git_HOME): ${env_var:GITSOURCE}/

Eclipse reads these details straight from your user configuration file (%USERPROFILE%.gitconfig).

The only thing I had customized in this file was my merge tool: “C:\Program Files (x86)\Beyond Compare 4\BCompare.exe”

[user]
name = Chris Boorman email = cboorman@3rdParty.com
[diff]
tool = bc
[difftool “bc”]
path = C:\Program Files (x86)\Beyond Compare 4\BComp.exe
[merge]
tool = bc
[mergetool “bc”]
cmd = “C:\Program Files (x86)\Beyond Compare 4\BComp.exe” “$LOCAL” “$REMOTE” “$BASE” “$MERGED”
[push]
default = simple

To work on Git-hosted projects in Eclipse, you must import them into Eclipse using the “Git Project Import Wizard”. You can use “Import Existing Project”.

The procedure differs between projects hosted publically on Github, and projects hosted on 3rdParty’s private repo server.

3rdParty private server

Here’s how to get a local enlistment to the privately hosted 3rdParty REST API Git respository.

Before you begin, establish a VPN connection to 3rdParty.

  1. In Eclipse, open the Git perspective.

  2. In the “Git Repositories” pane, click “Clone a Git repository”.

    The “Clone Git Repository” appears.

  3. In the Connection “Protocol” drop-down list, select “git”.

  4. In the URI field, type the URI of Git repository, and then click “Next”.

    git@git.c11.3rdParty.com:python_rest_api.git

    You’re prompted to input your password.

  5. In the Information dialog, type your SSH Passphrase, and then click “OK”.

    The “Branch Selection” dialog appears.

  6. Select branches to clone from the remote repository. Remote tracking branches will be created to track updates for these braNCHES IN THE REMOTE REPOSITORY.

    Click “Deselect All”, and then check the following branches: develop, feature/api_doc, master, release/current; and then click “Next”.

    The “Local Destination” dialog appears.

  7. Set the “Initial branch” to feature/api_doc, and then click “Finish”.

  1. In Eclipse, in the Project Explorer, right-click the background, and select Import > Import > Git > Projects from Git > Existing Local Repository.

    The Select a Git Repository dialog appears. Note that the repository you want isn’t in the list! Don’t worry though…

  2. Click Add.

    The Add Git Repositories dialog appears. The new repository is already checked (and in my case - along with the Java repo).

  3. Click Finish, Next.

  4. Select Import as a General Project, and click Next.

    The new project folder appears selected: Working Directory - C:\Users|Chris\src\mobile_assets

  5. Accept the suggested project name (mobile_assets), and click Finish.

3rdParty on github

To work on a project hosted on GitHub:

  1. Navigate to that project repo on GitHub. E.g.,
  2. Click “Fork”. This creates a copy of it under your account.
  3. Navigate to your new forked project on GitHub, and click “Clone”. This creates a local copy of it on your hard drive.

In respect to your local

What eclipse does to your project

Eclipse adds /bin folder for compiled Java class files.

Cheatsheet

Code folding

Under the Source Menu.

Collapse Code: Ctrl + - Uncollapse Code: Ctrl + = Collapse Code (All): Ctrl + 9 Uncollapse Code (All): Ctrl + 0

Add to dictionary

Ctrl + Shift + Right Click

Show in breadcrumb

Only available in the Java Editor.

Ctrl + Shift + B

Working set

Imagine if the Project Explorer contained a filtered view of resources in your project. I.e., a subset of it. E.g., a view that ignores the Test directory, and everything in it; but includes parts of another project within the workspace. If you could save such a view, it would essentially be a Working Set.

Path Variables

These are just like Environment Variables, but they apply to Eclipse, the Current Workspace, and the Current Project. Here are some examples.

ECLIPSE_HOME: C:\Program Files\eclipse\ WORKSPACE_LOC: A:\Documents\Eclipse\Projects\Practice PROJECT_LOC: A:\Documents\Eclipse\Projects\Practice\TestSphinxWiz

Workspace

A folder that contains a subfolder called “.metadata”.

Counter to what you might expect, the workspace folder doesn’t physically contain project folders. It contains them by reference.

Java

Environment (path) variables

Eclipse uses path variables in build configuration scripts so you to create portable projects.

Environment variables are defined within a hierarchy, which defines each one’s scope of access.

  1. The operating system. These are the current user’s environment variables (UserDomain.UserName). For Example,

    USERNAME = Chris

  2. The Eclipse IDE and the Java Virtual Machine ( referred to as System Properties of the Java Platform). To maximize portability, never refer to an environment variable when the same value is available in a System Property. For example, if the operating system provides a user name, it will always be available in the system property user.name.

  3. The current Workspace in Eclipse.

  4. The current Project within the current workspace. These are the environment variables that the build configuration can access directly. For example,

    Path: /java_3rdParty

To see and create Path Variables for a particular java project:

  1. Right-click the java project in Project Explorer, and click Properties.
  2. Navigate to Resources > Linked Resources > Path Variables.

Use PROJECT_LOC as a starting point, and create

JAVADOC_LOC = ${PROJECT_LOC}\doc LIBRARIES_LOC = ${PROJECT_LOC}\libs SOURCE_LOC = ${PROJECT_LOC}\src

To use these in an Ant script, you have to define and assign equivalent local variables.

Windows path statement

%SystemRoot% %SystemRoot%system32 %SystemRoot%System32Wbem %SYSTEMROOT%System32WindowsPowerShellv1.0C:Androidsdkplatform-tools %JDK_HOME%bin %JAVA_HOME%bin %PYTHON_HOME% %PYTHON_HOME%Scripts C:Program Files (x86)Gitcmd C:Program Files (x86)Gitbin %MinGW_HOME%/bin %MERGEHOME%%ANT_HOME%bin X:JGSoftToolsHTML Tidy and XML Tidy C:Program FilesInteliCLS ClientC:Program Files (x86)InteliCLS ClientC:Program FilesIntelIntel(R) Management Engine ComponentsDAL C:Program FilesIntelIntel(R) Management Engine ComponentsIPT C:Program Files (x86)IntelIntel(R) Management Engine ComponentsDAL C:Program Files (x86)IntelIntel(R) Management Engine ComponentsIPT C:Program Files (x86)Windows Kits8.0Windows Performance ToolkitC:Program FilesMicrosoft SQL Server100ToolsBinnC:Program FilesMicrosoft SQL Server100DTSBinnC:Program Files (x86)Microsoft SQL Server100ToolsBinnC:Program Files (x86)ATI TechnologiesATI.ACECore-Static OXYGEN_HOME X:FCIV C:Program Files (x86)QuickTimeQTSystemC:Perl64bin C:Perl64sitebin

Eclipse environment variables

See: %DOCUMENTS_ARCHIVE_HOME%\Work\System_Information_Environment_Variables.xlsm

${PROJECT_LOC}

I’d like to writed an ANT script to build Javadocs, that includes a reference to the android library - so my resulting docs will contains hotlinks to Android API Javadocs.

I.e., to C:optandroid-sdksplatformsandroid-20android.jar

or using the Eclipse system variable:

${com.android.ide.eclipse.adt.sdk}platformsandroid-20android.jar

I got this information from Eclipse Help > Properties > Fourth tab (copied contents to clipboard, then pasted into EditPad Pro - and then searched it for android).

/instance/com.android.ide.eclipse.adt/com.android.ide.eclipse.adt.sdk=C:\opt\android-sdks

The javadoc export wizard

Javadoc command: C:\Program Files\Java\jdk1.7.0_13\bin\javadoc.exe Javadoc destination directory: C:\Users\Chris\src\java_3rdParty\doc

Javadoc command: C:\Program Files\Java\jdk1.7.0_13\bin\javadoc.exe
%JDK_HOME%\bin\javadoc.exe ${JDK_HOME}\bin\javadoc.exe ${/instance/org.eclipse.jdt.ui/command}

Javadoc destination directory: ${PROJECT_LOC}\doc

Overview

C:\Users\Chris\src\java_3rdParty\overview.html (\overview.html). (${PROJECT_LOC}\overview.html).

VM options

Extra javadoc options

-noqualifier java.lang:java.io

JRE source compatibility

1.7

Ant script

Save the settings of this Javadoc export as an Ant script:

C:\Users\Chris\src\java_3rdParty\javadoc.xml (\javadoc.xml) (${PROJECT_LOC}\javadoc.xml).

Update Javadoc Location

Do you want to update the Javadoc location for ‘java_3rdParty’ with the chosen destination folder ‘C:\Users\Chris\src\java_3rdParty\doc’?

-> Yes to all, this

java_3rdParty Project Properties > Javadoc Location = “file:////%USERPROFILE%//src//java_3rdParty//doc//”

Apache commons

When developing Java applications, you’ll often need to reference/import class libraries from the Apache Commons organization.

E.g., commons-io

Home Page: http://commons.apache.org/

How To

Prerequesites: Install PyDev and ReST Editor.

In the Eclipse menu, click Run > Run Configurations. The Run Configurations dialog appears.

Double-click the Launch Configuration Type “Sphinx (via make file)”. Then fill-in the dialog, click “Apply”, and then Click “Run”.

Project Configuration Type: Sphinx (via make file).

Name: Build Docs

Working Directory: ${workspace_loc:/python_rest_api/doc/user/v1}

Sphinx Output: html

Troubleshooting

What to do when you open a file for editing, and it seems to open - but you can’t find it anywhere

Reset the perspective.

Windows > Reset the Perspective…