Skip to content

Latest commit

 

History

History
119 lines (92 loc) · 9.86 KB

eclipse.asciidoc

File metadata and controls

119 lines (92 loc) · 9.86 KB

eclipse

The eclipse commandlet allows to install, configure, and launch the Eclipse IDE. To launch eclipse for your current workspace and devonfw-ide installation simply run: devon eclipse

You may also supply additional arguments as devon eclipse «args». These are explained by the following table:

Table 1. Usage of devon eclipse
Argument(s) Meaning

--all

if provided as first arg then to command will be invoked for each workspace

setup

setup Eclipse (install or update)

add-plugin «id» [«url»] [«key»]

install an additional plugin. If only «id» is given, it has to be the key of a preconfigured plugin properties file. If also «url» is given it has to be the plugin update site and «id» the plugin ID(s). If an optional third argument is given, it will be the name of the plugin properties file to create in settings (for sharing or simpler uninstall).

remove-plugin «id»

remove the specified plugin. Typically the key of a preconfigured plugin properties file should be given as «id«. However, also the qualified plugin ID can be specified instead.

run

launch Eclipse (default if no argument is given)

start

same as run

ws-up[date]

update workspace

ws-re[verse]

reverse merge changes from workspace into settings

ws-reverse-add

reverse merge adding new properties

create-script

create launch script for this IDE, your current workspace and your OS

mirror «id» [«url»]

mirror the content of an update-site

There are variables that can be used for Eclipse. These are explained by the following table:

Table 2. Variables of devonfw-ide for Eclipse
Variable Meaning

ECLIPSE_VERSION

The version of the tool Eclipse to install and use.

ECLIPSE_EDITION

The edition of the tool Eclipse to install and use. The edition of the tool Eclipse to install and use. By default the jave edition will be used. Further editions will come up soon.

*EXTRA_JAVA_VERSION

You can set this to a different (newer) version of Java used to launch your IDE (other than JAVA_VERSION that is used to build your project)

plugins

To be productive with Eclipse you need plugins. Of course devonfw-ide can automate this for your: In your settings git repository create a folder eclipse/plugins (click on this link to see more examples and see which plugins come by default). Here you can create a properties file for each plugin. This is an example tmterminal.properties:

plugin_url=http://download.eclipse.org/tm/terminal/marketplace
plugin_mirror_url=https://my-server.com/terminal-2022-09-13
plugin_id=org.eclipse.tm.terminal.feature.feature.group,org.eclipse.tm.terminal.view.feature.feature.group,org.eclipse.tm.terminal.control.feature.feature.group,org.eclipse.tm.terminal.connector.ssh.feature.feature.group,org.eclipse.tm.terminal.connector.telnet.feature.feature.group
plugin_active=true

The variables are defined as follows:

  • plugin_url defines the URL of the Eclipse update site of the plugin

  • plugin_mirror_url defines the URL of the Eclipse mirrored update site of the plugin. See Mirroring Eclipse Update Site

  • plugin_id defines the feature group ID(s) to install. To install multiple features/plugins provide a coma-separated list of IDs. If you want to customize devonfw-ide with new plugins you can first install them manually and then go to About Eclipse > Installation Details then you can filter for your newly installed plugin and find the values in the Id column. Copy & paste them from here to make up your own custom config.

  • plugin_active is an optional parameter. If it is true (default) the plugin will be installed automatically during the project setup for all developers in your team. Otherwise, developers can still install the plugin manually via devon eclipse add-plugin «plugin-name» from the config file settings/eclipse/plugins/«plugin-name».properties. See the settings/eclipse/plugins folder for possible values of «plugin-name».

In general you should try to stick with the configuration pre-defined by your project. But some plugins may be considered as personal flavor and are typically not predefined by the project config. This e.g. applies for devstyle that allows a real dark mode for eclipse and tunes the theming and layout of Eclipse in general. Such plugins should be shipped with your settings as described above with plugin_active=false allowing you to easily install it manually.

As the maintainer of the settings for your project you should avoid to ship too many plugins that may waste resources but are not used by every developer. By configuring additional plugins with plugin_active=false you can give your developers the freedom to install some additional plugins easily.

All plugins are installed separately in ${DEVON_IDE_HOME}/plugins/eclipse.

legacy plugin config

For downward compatibility we still support the deprecated legacy configuration if the folder settings/eclipse/plugins does not exist: The project configuration typically defines the plugins that will be installed via ECLIPSE_PLUGINS variable. Otherwise defaults from this eclipse commandlet will apply. Be aware that this comes at your own risk and sometimes plugins can conflict and break your IDE.

Here is an example how a project can configure the plugins in its devon.properties inside the settings:

ECLIPSE_PLUGINS=("AnyEditTools.feature.group" "https://raw.githubusercontent.com/iloveeclipse/plugins/latest/" "com.ess.regexutil.feature.group" "http://regex-util.sourceforge.net/update/")

For the above listed plugins you can also use the short form:

ECLIPSE_PLUGINS=("anyedit" "" "regexutil" "")

Of course you may also mix plugin IDs with fully qualified plugins.

mirroring update sites

A common problem with eclipse plugins is that they are provided decentralized as so-called update sites via URLs. The maintainer of that URL is in full control of the availability and the content behind that URL. If the service gets broken, obviously the plugin can not be downloaded. Even worse, if existing content gets updated, the result is not reproducible anymore.

While the plugin artifact itself is versioned, the request to install a plugin can not specify a version but always downloads the "latest" version from the update site. If at all some kind of versioning for stability is in place it happens via the URL itself so for different major versions different URLs are provided. A possible solution is to mirror the update site locally and then make it available on your own webserver. This way you always have access to the plugin version you need as a developer without being dependent on the plugin provider. Below is the process to mirror a plugin update-site.

To mirror with only one paramter, you just need the «plugin-id» of an existing plugin in ${DEVON_IDE_HOME}/settings/eclipse/plugins (e.g. checkstyle). Open any CLI in ${DEVON_IDE_HOME} and run the following command.

devon eclipse mirror «plugin-id» [«url»]

This command will automatically mirror the content of an update site to a specific directory named by «plugin-id» together with the current date in ${DEVON_DOWNLOAD_DIR}/update-sites/ (e.g. checkstyle-2022-09-14). Afterwards, the folder can be uploaded to your own webserver and the URL can be put manually in «plugin_mirror_url» in the «plugin-id».properties file. This only works if a valid plugin_url is already set in the properties for the given plugin_id (see plugins). If you want to mirror an update site independently of «plugin-id».properties, you can enter an update site URL for the optional «url» parameter (e.g. https://checkstyle.org/eclipse-cs-update-site).

dictionary

Eclipse already comes with a build-in spellchecker. This is very helpful when writing comments. The default settings of devonfw-ide ship with a project specific dictionary file and according configurations to enable spellchecking and configuring this dictionary. When typing JavaDoc, inline comments or other texts the spellchecker will underline unknown words in red. If your cursor is located at such a word you can hit [Ctrl][1] to get a context menu with additional options. There you can either choose similar correct words to correct a typo or you may even add the word (maybe a new business term) to your local dictionary.

"Eclipse spellchecker”

In the latter case, you should commit the changes to your settings so that it will be available to your entire team. For further details about committing changes to the settings please consult the admin usage.

non-english dictionary

In case your project has to write documentation or text in languages other than English, you might want to prefill your project dictionary for that language. Here we collect a list of such dictionaries that you can download and merge into your project dictionary: