devonfw guide

To update your IDE (if instructed by your admin), you only need to run the following command:

Please note that windows is using file-locking what can have ugly side-effects. To be safe, you should have your IDE tools shut down before invoking the above update command. E.g. if a tool needs to be updated, the old installation folder will be moved to a backup and the new version is installed on top. If there are windows file locks in place this can fail and mess up things. You can still delete the according installation from your software folder and rerun devon ide update if you ran into this error.

If you are working on different branches in parallel you typically want to use multiple workspaces.

You can have multiple instances of eclipse running for each workspace in parallel. To distinguish these instances you will find the workspace name in the title of eclipse.

In order to roll out the perfectly configured devonfw-ide to your project initially or when new members join, you only have to provide the Settings URL to the developers of your team.

After you changed and tested your settings git repository (main branch), you only need to announce this to your developers (e.g. via email or some communication tool) so that they will can devon ide update and automatically get up-to-date with the latest changes (see update).

In case you want to go to a new version of devonfw-ide itself, developers have to call devon ide update scripts.

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:

The variables are defined as follows:

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.

Eclipse already comes with a buid-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 buisness term) to your local dictionary.

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 comitting changes to the settings please consult the admin usage.

Run devon ide setup to initially setup your devonfw-ide. It is recommended to run the setup script in the top-level directory ($DEVON_IDE_HOME). However, in case you want to skip some system specific integrations, you may also run this command directly instead. The setup only needs to be called once after a new devonfw-ide instance has been created. It will follow this process:

Run devon ide update to update your devonfw-ide. This will check for updates and install them automatically. The optinal extra argument («package») behaves as follows:

In order to update to a specific version of scripts an explicit version can be specified after the additional to argument:

The above example will update to the exact version 3.1.99 no matter if this is an upgrade or a downgrade of your current installed version. If you just use devon ide update scripts then the latest available version will be installed. In larger teams it is recommended to communicate exact version updates to avoid that a new release can interfere and break anything. Therefore, some pilot user will test a new version for the entire team and, only after a successful test, they will communicate to the team to update to that exact version by providing the complete command as in the above example.

We hope you love devonfw-ide. However, if you don’t and want to get rid of it entirely and completely remove all integrations, you can use this command:

This will remove devonfw-ide from all central places of your OS (user home directory such as scripts, .devon, .bashrc, as well as windows registry, etc.). However, it will not remove your current installations (or shared software folder). So after running this uninstall, simply remove your DEVON_IDE_HOME directory of all devonfw-ide installations and potential shared software folder. You may also want to clean up your ~/Downloads directory from files downloaded by devonfw-ide. We do not automate this as deleting a directory is a very simple manual step and we do not want to take responsibility for severe data loss if your workspaces contained valuable work.

Examples for create a new devon4j application:

Will create an app with package com.example.domain.myapp, groupId com.example.domain, artifactId myapp, version 1.0.0-SNAPSHOT, and h2 database.

Will create an app with package com.example.domain.myapp, groupId com.example.domain, artifactId myapp, version 0.0.1-alpha1, and h2 database.

Will create an app with package com.example.domain.myapp, groupId com.example.group, artifactId myapp, version 1.0.0-SNAPSHOT, and h2 database.

Will create an app with package com.example.domain.myapp, groupId com.example.group, artifactId demo-app, version 1.0.0-SNAPSHOT, and h2 database.

Will create an app with package com.example.domain.myapp, groupId com.example.group, artifactId demo-app, version 1.0.0-SNAPSHOT, and SAP hana database.

Will create an app with package com.example.domain.myapp, groupId com.example.group, artifactId myapp, version 0.0.1, oracle database, and with a batch module.

Example for migrating a devon4j application:

Will migrate current devon4j application to the latest version available.

This release commandlet utilizes the build commandlet to support mutliple build-tools such as maven, gradle, or npm. Each of those commandlets should respect the variable «TOOL»_RELEASE_OPTS to customize the parameters for the release build.

So e.g. if a pom.xml is detected, maven will be used. In this example the variable MVN_RELEASE_OPTS is used that defaults to clean deploy -Dchangelist= -Pdeploy. If you provide a specific argument this will be passed additionally. So if you invoke the command devon release -P myProfile, the above step invoke deployment on build-system would technically call this:

Please also note that it is very tricky to determine and modify the version of a project in a fully generic way. Even though we try our best to support different scenarios, we can not ensure this is working for edge-cases. Therefore, we strongly encourage to follow best practices such as ci-friendly maven. Further, sticking to the defaults and follow the devonfw standard to name the profile for custom goals in deployment simply deploy is recommended.

To be productive with VS Code you need plugins (called extensions in VS Code). Of course devonfw-ide can automate this for your: In your settings git repository create a folder vscode/plugins (click 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 devonfw-extension-pack.properties:

The variables are defined as following:

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. Such plugins should be shipped with your settings as described above with plugin_active=false allowing you to easily install it manually. Surely, you can easily add plugins via the UI of VS code. However, be aware that some plugins may collect sensitive data or could introduce other vulnerabilities. So consider the governance of your project and talk to your technical lead before installing additional plugins that are not pre-defined in your settings.

As 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.

The settings folder (see SETTINGS_PATH) has to follow this file structure:

As you can see, the settings folder contains sub-folders for tools of the IDE. So the devon folder contains devon.properties files for the configuration of your environment. Further, for the IDEs such as eclipse or vscode, the according folders contain the templates to manage the workspace via our configurator.

Different tools and configuration files require a different handling:

You can easily customize these settings for the requirements of your project. We suggest that one team member is responsible to ensure that everything stays consistent and works.

You may also create new sub-folders in settings and put individual items according to your needs. E.g. you could add scripts for greasemonkey or tampermonkey, as well as scripts for your database or whatever may be useful and worth to share in your team. However, to share and maintain knowledge we recommend to use a wiki.

By default, software is downloaded via the internet from public download URLs of the according tools. However, some projects may need specific tools or tool versions that are not publicly available. In such case, they can create their own software repository (e.g. in a VPN) and configure the base URL of it via DEVON_SOFTWARE_REPOSITORY variable. Then, devonfw-ide will download all software from this repository only instead of the default public download URLs. This repository (URL) should be accessible within your network via HTTPS (or HTTP) and without any authentication. The repository needs to have the following structure:

So for every tool «tool» (java, maven, vscode, eclipse, etc.) you need to provide a folder in your repository. Within this folder for every supported version «version» you need a subfolder. This subfolder needs to contain the tool in that version for every operating system «os» (windows, linux, or mac - omitted if platform independent, e.g. for maven).

By default, each installation of devonfw-ide has its own physical installations of the required tools in the desired versions stored in its local software folder. While this is great for isolation of devonfw-ide installations and to prevent side-effects, it can cause a huge waste of disc resources in case you are having many installations of devonfw-ide. If you are a power-user of devonfw-ide with more then ten or even up to hundreds of installations on your machine, you might love to share installations of a software tool in a particular version between multiple devonfw-ide installations.

In order to do so, you only need to configure the variable DEVON_SOFTWARE_PATH in your ~/devon.properties pointing to an existing directory on your disc (e.g. /projects/software or C:\projects\software). Then devonfw-ide will install required software into ${DEVON_SOFTWARE_PATH}/${software_name}/${software_version} as needed and create a symbolic link to it in ${DEVON_IDE_HOME}/software/${software_name}.

As a benefit, another devonfw-ide installation will using the same software with the same version can re-use the existing installation and only needs to create the symbolic link. No more waste of having many identical JDK installations on your disc.

As a drawback, you need to be aware that specific tools may be "manipulated" after installation. The most common case is that a tool allows to install plugins or extensions such as all IDEs do. Such "manipulations" will cause side-effects between the different devonfw-ide installations sharing the same version of that tool. While this can also be a benefit it may also cause trouble. If you have a sensitive project that should not be affected by such side-effects, you may again override the DEVON_SOFTWARE_PATH variable to the empty value in your ${DEVON_IDE_HOME}/conf/devon.properties of that sensitive installation:

This will disable this feature particularly for that specific sensitive devonfw-ide installation but let you use it for all other ones.

In some cases, a project might need a (proprietary) tool(s) that (are) not supported by devonfw-ide. A very simple solution is to get a release of devonfw-ide and add the tool(s) to the software folder and then distribute this modified release to your team. However, this has several drawbacks as you then have a fork of devonfw-ide all will loose your tool(s) when updating to a new release.

As a solution for this need, devonfw-ide let’s you configure custom tools via the DEVON_IDE_CUSTOM_TOOLS variable. It can be defined in devon.properties of your settings git repository as an array of the custom tools you need to add. Each entry applies:

As an example, we define it in ${DEVON_IDE_HOME}/settings/devon.properties:

This will download and extract the following content to your software folder:

Please note that if you are not using windows, the -windows suffix will be -mac or -linux.