Eclipse Usage

This articles focuses on Eclipse usage and configuration.

Terminology

• Something appearing on the right side of the editor as a color mark (for examples, errors or warnings) is called an annotation in Eclipse.

Eclipse Plugins

Eclipse Plugins and Features

Projects

Project Files

• .classpath at the root of the project is a file describing what source folders and external libraries should be on the Eclipse classpath. This is used for validation and errors while in the IDE (for example, some classes may not be recognized if they come from a third party library and are not added in Eclipse).
• The .project file is an important file which contain information about the project's builders, natures, and so on. Note that this file sometimes needs to be edited by hand. There is no GUI dialog for adding or removing a nature to the project, for example.

Editing Source Files

Two main features help:

• Content Assist (generally in the Java environment it will scan the bytecode of the given libraries to display a list of relevant methods).
• Word Completion is much more primitive, but also useful: it scans the buffers of the currently opened editors and will help you to complete your code based on previously entered data.

Search

• To remove some folders from the File Search:

Go to Project -> Properties -> Resource Filters.
Click Add.
Choose Filter type: Exclude all
Choose Applies to: Folders; check All children (recursive).
In the Attributes, choose Project relative path, Matches, target (for example).

Text Compare

• The text compare feature is used when editing a SVN conflict for example. On the left appears the *merged* file. So you can only commit changes from right to left (since the left file is the result file). If a change refuses to take place, you can switch to the two way compare (apparently when in three-way compare - with the ancestor), Eclipse refuses to make some modifications.

Builders & Run/Launch configurations

• If you define an Ant builder, set it to run under a different JRE. Else it will be extremely slow (don't know the reason yet).

• While a builder generally refers to a project globally, a launch (run) configuration refers to a selected resource. For example, a PHP file would be associated with a launch configuration that would deploy this file to a web server, and then open the internal browser to the right URL.

• Validation (that allows you to see your projects warnings / errors) is a builder.

• Cleaning (Project->Clean...) will remove all your built files. It will also clear errors / warnings if the validation builder is activated.

Validation

• If you use XML validation, be careful to exclude Ant files (which have their own validator) from the XML validation. Else you will get some warnings about missing schema / DTD.

Team & Version Control

• To access a CVS repository using public key authentication, change the default access method in Preferences->Team->CVS->Ext Connection Method to extssh.

Features

Line Wrapping

Line wrapping (soft-wrap as well as hard-wrap) seems to be one of Eclipse's current weakness. I hope the situation improves soon, because it is a pity that such a simple (but essential) feature is absent. In the meantime I have found the following solutions:

• Line wrapping by Eclipse works for certain types of files. For Java code, for example, you can go to Preferences->Java->Code Style->Formatter. Then click "Show..." and you will have access to line wrapping. But this is not present for C++ code via the CDT tools... It also does not work for PHP and plain text files.

• In Preferences->Java->Code Style->Formatter you may define a certain number of profiles. To make sure these profiles are actually used within your project, you should *disable* project specific settings on your project (via Properties->Code Style->Formatter). That feature can be useful, but then in order to apply changes you have to edit directly your project properties, not the global profiles.

• Soft wrapping can be done via a very useful plugin. See this page for details.

Configuration

Appearance customization

• Eclipse uses views and perspectives. Perspectives are in fact a set of views; many plugins come with their own views and perspectives. You can define your own perspective; however developing views is harder (you probably need to code).

• Font customization is available in Preferences->General->Appearance. However some text seems to be set on a system-level, for example the font on the navigator view. This can be accomplished directly by modifying GTK properties since Eclipse uses GTK. On KDE, I installed the GTK-QT engine so that GTK programs use the Qt styles.

• On newer Eclipse version (using GTK 3), such as Eclipse-4.7, and recent versions of KDE, the fonts are really, really small especially inside views. You can fix that problem by adding a CSS file with the following content:

label, entry, treeview  {
   font-size: 24px;
}

It should be inside a directory like this: /usr/local/opt/eclipse/theme/gtk-3.0. And Eclipse should be launched like this:

XDG_CONFIG_HOME=/usr/local/opt/eclipse/theme /usr/local/opt/eclipse/eclipse

• By customizing perspectives, you can remove almost all buttons in the toolbars, and choose which one you want to be there. You can accomplish that by choosing Windows->Customize Perspective... However there are still some stuff I cannot remove or change.

• To toggle the breadcrumb (the bar at the top of the source editing window), there is a button on the toolbar.

• To remove the toolbar entirely in Eclipse 4.2 or later, choose Quick Access and type "toggle toolbar". There is no normal GUI menu to accomplish that.

• The space on the bottom should normally contain the "Background Activity tab". This is not evident as this tab is not resizable and blank most of the time. I don't know yet if it possible at all to remove the whole space at the bottom.

• Warning: if you go to Preferences -> General -> Appearance, and you change the theme to the system default, it will override any properties you may have defined for the fonts, etc.

• To get file icons for CVS or SVN (these are really useful), go to General -> Appearance -> Label Decorations.

Configuring custom keys

• All the custom keys configuration is in Preferences->General->Keys. You can define what custom key you want for almost all of Eclipse actions. Note that the best way to set a custom key is to first locate the command you want to bind to (in a pop menu or in a menu on the menu bar), then search for the action associated with the default current key. Once you know the command and the *group*, you can change it.

• Explanation: the "When" menu specifies when (under which conditions) the key sequence will be triggered. For example, if you want the key to always be triggered, choose "In Windows". The "Command" menu, with its category, actually defines the action that will take place. Note that if under current conditions the action cannot take place, it won't.

Warning: the Java and PHP plugins use the same category/menu named "Source". This can get confusing, in particular you should use the "Format" command in Java, and the "Format Document" command in PHP. "Format" when editing Ant build files is also under the Java source category!

• Note: if you want to set an action in all available environments/plugins, the best way is to enter that under "When in Windows" in the "When" category. This will make the action available everytime it is defined (implemented).

• Update: As of Eclipse-3.3, the previous information is no longer true. The custom key configuration has changed and is now much better and more intuitive. In Eclipse-3.4 it's even better and seems much less buggy.

• List of Eclipse custom keys

File Associations

• To associate a file type (by extension, like *.groovy, *.gsp), go to:

Preferences -> General -> Editors -> File Associations

• Another place to look is at:

Preferences -> General -> Content Types

File Encoding

• Always use UTF-8 in Eclipse. Set it as the default encoding.

• Be very wary with files not encoded in UTF-8; if you open and save them in Eclipse they will get scrambled! Be very wary or use another editor.

• Even if you set the general encoding to be UTF-8, Eclipse may (stupidly) still attempt to use ISO-8859-1 as the default for JSP/GSP files. Check that in the File Associations preferences panel.

Viewing Help

• You can select in Preferences->Help the browser you want to use (external or internal).

• Anyway the Eclipse help is rarely of use. Google searches or the IRC channel #eclipse on Freenode are much more useful.

Specific Language Environments

Java

• If you remove manually the contents of the output folder (where compiled class files are written), you may need to clean the project before building it again.

Groovy

• A Groovy project also expects to have the Java nature (at least that's the case for Grails project). Else things can go wrong.

Infrastructure

Eclipse and Gentoo

• As of March 2007 it seems better to download the binary version from the Eclipse web site rather than build Eclipse through Portage. In my case Eclipse seems stabler with the binary version. Update: the Gentoo version was not the culprit. Running the Gentoo ebuild is OK.

• Eclipse currently can not seem to handle large files (1 MB or more). This is a real problem and even seems to happen on other platforms than Linux x86_64.

• It seems imperative to add the following arguments when launching Eclipse:

-vmargs -Xms256m -Xmx512m -XX:PermSize=64m -XX:MaxPermSize=128m

Else Eclipse will be very slow and will keep crashing. Just configuring these settings seemed to make Eclipse run MUCH faster. Edit the file /usr/lib/eclipse-3.2/eclipse.ini to set these parameters.

Eclipse Preferences, Cache, and other information

• Preferences seem to be stored in the workspace/.metadata folder. For example, key shortcuts are stored there - do not delete this folder or you will lose all your custom keys!
• Some Eclipse cache is also stored there. For example, there is a cache per project at workspace/.metadata/.plugins/org.eclipse.core.resources/.projects/.
• Note that information from some external plugins (Subclipse for example) is stored in this org.eclipse.core.resources folder, so if you don't see information stored in the plugin folder, don't assume it is not stored elsewhere.

Reporting Eclipse bugs

• Since everything is stored in the workspace, the best is to zip your workspace and send it to the Eclipse developers. In this case try to copy the problematic projects INSIDE the workspace, instead of keeping them out.

Current problems

• I would like to be able to remove the space at the bottom of the screen.