devonfw guide

Structure

The directory layout of your devonfw-ide will look like this:

Listing 1. File structure of your devonfw-ide

/ projects (or C:\Projects, etc.)
└──/ my-project ($DEVON_IDE_HOME)
    ├──/ conf
    ├──/ log
    ├──/ scripts
    ├──/ settings
    ├──/ software
    ├──/ system
    ├──/ updates
    ├──/ workspaces
    ├── setup
    ├── setup.bat
    └── devon-ide-doc.pdf

The elements of the above structure are described in the individual sections. As they are hyperlinks you can simply click on them to get more details.

conf

This folder contains configurations for your IDE:

Listing 2. File structure of the conf folder

/ conf
├──/ .m2
│  ├──/ repository
│  │  ├──/ ant
│  │  ├──/ ...
│  │  └──/ zw
│  ├── settings-security.xml
│  └── settings.xml
├──/ .sonar
├──/ ...
└── variables

The .m2 folder is used for configurations of maven. It contains the local repository folder used as cache for artifacts downloaded and installed by maven (see also maven repositories). Further, there are two configuration files for maven:

settings.xml initialized from a template from your devonfw-ide devonfw-guide_ide.wiki_conf.asciidoc_settings. You may customize this to your needs (configuring HTTP proxies, credentials, or other user-specific settings). Secrets can be specified as $[«variable.name»] and will be prompted, encrypted and replaced automatically during the setup (unless in batch mode). Please note that this process is skipped in batch mode and also if you use the default settings URL (for simplicity of testing). To make use of this feature simply fork or copy the settings to your own git repo. In case your credentials have changed or you made a typo, you can simply redo this step by first moving your ${DEVON_IDE_HOME}/conf/.m2/settings.xml file to a temporary folder and then calling devon mvn setup.
settings-security.xml is auto-generated for you by devonfw-ide with a random password. This should make it easier for devonfw-ide users to use password encryption and never add passwords in plain text for better security.

Finally,there is a file variables for the user-specific configuration of devonfw-ide.

log

The log directory is used to store log files e.g. for the IDE configurator. You may look here for debug information if something goes wrong.

scripts

This directory is the heart of the devonfw-ide and contains the required scripts.

Listing 3. File structure of the conf folder

/scripts
├──/ command
│  ├── aws
│  ├── az
│  ├── build
│  ├── docker
│  ├── dotnet
│  ├── eclipse
│  ├── gcloud
│  ├── gcviewer
│  ├── gh
│  ├── graalvm
│  ├── gradle
│  ├── helm
│  ├── help
│  ├── ide
│  ├── intellij
│  ├── ionic
│  ├── jasypt
│  ├── java
│  ├── jenkins
│  ├── kotlinc
│  ├── kotlinc-native
│  ├── kubectl
│  ├── lazydocker
│  ├── mvn
│  ├── ng
│  ├── node
│  ├── npm
│  ├── oc
│  ├── project
│  ├── python
│  ├── pip
│  ├── quarkus
│  ├── release
│  ├── rewrite
│  ├── sonar
│  ├── terraform
│  ├── vscode
│  └── yarn
├── devon
├── devon.bat
├── environment-project
├── environment-project.bat
├── functions
└── devon.properties

The command folder contains the commandlets. The devon script is the key command line interface for devonfw-ide. There is also devon.bat that can be used in cmd or PowerShell. As the devon CLI can be used as a global command on your computer from any directory and gets installed centrally, it aims to be stable, minimal, and lightweight. The key logic to set up the environment variables is therefore in a separate script environment-project and its Windows variant environment-project.bat inside this scripts folder. The file functions contains a collection of reusable bash functions. These are sourced and used by the commandlets. Finally the devon.properties file contains defaults for the general configuration of devonfw-ide.

settings

The devonfw-ide requires settings with configuration templates for the arbitrary tools.

To get an initial set of these settings we provide the default ide-settings as an initial package. These are also released so you can download the latest stable or any history version at maven central.

To test devonfw-ide or for very small projects you can also use these the latest default settings (just hit return when setup is asking for the Settings URL). However, for collaborative projects we strongly encourage you to distribute and maintain the settings via a dedicated and project specific git repository. This gives you the freedom to control and manage the tools with their versions and configurations during the project lifecycle. Therefore simply follow the admin usage guide.

Structure

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

Listing 4. File structure of settings

/settings
├──/ devon
│  ├──/ conf
│  │  ├──/ .m2
│  │  │  └── settings.xml
│  │  ├──/ npm
│  │  │  └── .npmrc
│  │  └── devon.properties
├──/ eclipse
│  ├──/ workspace
│  │  ├──/ setup
│  │  └──/ update
│  ├── lifecycle-mapping-metadata.xml
│  └── project.dictionary
├──/ ...
├──/ sonarqube
│  └──/ profiles
│     ├── Devon-C#.xml
│     ├── ...
│     └── Devon-XML.xml
├──/ vscode
│  └──/ workspace
│     ├──/ setup
│     └──/ update
└── devon.properties

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.

Configuration Philosophy

Different tools and configuration files require a different handling:

Where suitable, we directly use these configurations from your settings (e.g. for eclipse/lifecycle-mapping-metadata.xml, or eclipse/project.dictionary).
The devon folder in settings contains templates for configuration files. There are copied to the devonfw-ide installation during setup (if no such file already exists). In this way the settings repository can provide reasonable defaults but allows the user to take over control and customize to his personal needs (e.g. .m2/settings.xml).
Other configurations need to be imported manually. To avoid manual steps and simplify use we try to automate as much as possible. This currently applies to sonarqube profiles but will be automated with sonar-devon4j-plugin in the future.
For tools with complex configuration structures like eclipse, intellij, or vscode we provide a smart mechanism via our configurator.

Customize Settings

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.

software

The software folder contains the third party tools for your IDE such as maven, npm, java, etc. With respect to the licensing terms you may create a custom archive containing a devonfw-ide together with the required software. However, to be platform independent and allow lightweight updates, the devonfw-ide is capable to download and install the software automatically for you.

Repository

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:

${DEVON_SOFTWARE_REPOSITORY}/«tool»/«version»/«tool»-«version»[-«os»].tgz

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

Shared

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 absolute directory on your disc (e.g. /projects/software or C:\projects\software).

Caution

DEVON_SOFTWARE_PATH must be an absolte path that is an existing directory. On windows it has to be on the same drive as your IDE installations. If you use this power-feature you are taking responsibility for side-effects and should not expect support. You might also use this hint and maintain it manually without enabling the following feature.

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:

DEVON_SOFTWARE_PATH=

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

Custom

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:

It needs to have the form «tool»:«version»[:all][:«repository-url»]
The first entry must have the «repository-url» included which is used as default
Further entries will inherit this default if omitted
This URL is used in the same way as described above for a software repository.
The DEVON_SOFTWARE_REPOSITORY variable is ignored by this feature.
The optional infix :all is used to indicate that the tool is platform independent. Otherwise, an OS specific infix is appended to the URL file to download for your platform (windows, linux, or mac).

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

DEVON_IDE_CUSTOM_TOOLS=(jboss-eap:7.1.4.GA:all:https://host.tld/projects/my-project firefox:70.0.1)

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.

system

The system folder contains documentation and solutions for operation system specific integration. Please have a look to get the maximum out of devonfw-ide and become a very efficient power user.

updates

The updates folder is used for temporary data. This includes:

extracted archives for installation and updates
backups of old content on updates to prevent data loss

If all works fine you may clean this folder to save some kilo- or mega-bytes. Otherwise, you can ignore it unless you are looking for a backup after a failed or unplanned upgrade.

workspaces

The workspaces folder contains folders for your active work. There is a workspace folder main dedicated for your primary work. You may do all your work inside the main workspace. Also, you are free to create any number of additional workspace folders named as you like (e.g. test, release, testing, my-sub-project, etc.). Using multiple workspaces is especially relevant for Eclipse as each workspace has its own Eclipse runtime instance and configuration.

Within the workspace folder (e.g. workspaces/main) you are again free to create sub-folders for (sub-)projects according to your needs. We assume that in most cases you clone git repositories here. The following structure shows an example layout for devonfw:

Listing 5. File structure of workspaces

/ workspaces
├──/ main
│  ├──/ .metadata
│  ├──/ ide
│  ├──/ devon4j
│  └──/ my-thai-star
└──/ stable
   ├──/ .metadata
   ├──/ ide
   └──/ devon4j

In the main workspace you may find the cloned forks for regular work (in the example e.g. devon4j) as a base to create pull-requests while in the stable workspace there is a clone of devon4j from the official devon4j. However, this is just an example. Some people like to create separate workspaces for development and maintenance branches with git. Other people just switch between those via git checkout.

Project import

The devonfw-ide supports to automatically check out and import required projects into your IDE during setup. To configure this you put a .properties file for each desired project into the projects sub-folder in your settings. Each .properties file describes one "project" which you would like to check out and (potentially) import:

path=myproject
workingsets=Set1,Set2
workspace=example
git_url=http://github.com/someorg/someproject
git_branch=develop
build_path=.
build_cmd=mvn -DskipTests=true -Darchetype.test.skip=true clean install
eclipse=import
active=true

.Variables of project import

Variable Value Meaning

Variable	Value	Meaning
`path`	e.g. `myproject`, will clone into `${WORKSPACE_PATH}/myproject`	(required) Path into which the projects is cloned. This path is relative to the workspace.
`working sets`	e.g. `ws1,ws2`	(optional) This will create working sets (in eclipse). Each module (eclipse project) of this project will be part of all these working sets. Working sets will be automatically created if necessary.
`workspace`	`main`	Workspace to use for checkout and import. Default is `main`.
`git_url`	e.g. `http://github.com/someorg/someproject`	(required) Git URL to use for cloning the project.
`git_branch`	e.g. `develop`	(optional) Git branch to checkout. Git default branch is default.
`build_path`	e.g. `.` (default)	(optional) The directory inside `path` where to trigger an initial build after clone or pull (if `build_cmd` is set). For a regular project use `.` to build top-level project.
`build_cmd`	e.g. `mvn -D skip Tests=true -Darchetype.test.skip=true clean install`	(optional) The devonfw command to invoke to build the project after clone or pull. If omitted no build is triggered.
`eclipse`	e.g. `import`	(optional) Desired action for eclipse IDE. If you put `import` here all modules (eclipse projects) in the current project will be imported into eclipse. If you leave this out or put any other value for this parameter, no change in eclipse is done.
`active`	`true`	(optional) If set to `false` the project is skipped during the setup.

path

e.g. myproject, will clone into ${WORKSPACE_PATH}/myproject

(required) Path into which the projects is cloned. This path is relative to the workspace.

working sets

e.g. ws1,ws2

(optional) This will create working sets (in eclipse). Each module (eclipse project) of this project will be part of all these working sets. Working sets will be automatically created if necessary.

workspace

main

Workspace to use for checkout and import. Default is main.

git_url

e.g. http://github.com/someorg/someproject

(required) Git URL to use for cloning the project.

git_branch

e.g. develop

(optional) Git branch to checkout. Git default branch is default.

build_path

e.g. . (default)

(optional) The directory inside path where to trigger an initial build after clone or pull (if build_cmd is set). For a regular project use . to build top-level project.

build_cmd

e.g. mvn -D skip Tests=true -Darchetype.test.skip=true clean install

(optional) The devonfw command to invoke to build the project after clone or pull. If omitted no build is triggered.

eclipse

e.g. import

(optional) Desired action for eclipse IDE. If you put import here all modules (eclipse projects) in the current project will be imported into eclipse. If you leave this out or put any other value for this parameter, no change in eclipse is done.

active

true

(optional) If set to false the project is skipped during the setup.

Please note that the .properties file is parsed via shell and not via java. So be careful with "advanced" features .properties files normally support.