5. Usage

5.1. Roles

This section explains you how to use the devonfw-ide per role. Everybody should read and follow the usage for developer. In case you want to administrate devonfw-ide settings for your project, you should also read the usage for the admin.

5.1.1. Developer

As a developer you are supported to setup your IDE within minutes. You only need the settings URL from your Architect.

Update

To update your IDE (if instructed by your Architect), all you need to do is run the following command:

devon ide update
Working with multiple workspaces

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

  1. Go to the workspaces folder in your ${DEVON_IDE_HOME} and create a new folder with the name of your choice (e.g. release2.1).

  2. Check out (git clone …​) the according projects and branch into that workspace folder.

  3. Open a shell in that new workspace folder (cd to it) and according to your IDE run e.g. eclipse, vscode, or intellij to create your workspace and launch the IDE. You can also add the parameter create-script to the IDE commandlet in order to create a launch-script for your IDE.

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.

5.1.2. Admin

As IDE admin for the project you can configure the devonfw-ide to your needs.

Project specific settings

For your project you should create a git-repository for the settings. You can customize many aspects this way.

Distribute

To redistribute the IDE you can decide to use the official vanilla releases of the devonfw-ide scripts. However, you may also add the cloned settings, a custom devon.properties file, or predefine software (be aware of multi-platform-support).

Distribute Changes

When you have done changes in a larger project (big team), please first test the changes yourself, then pick a pilot user of the team, and only after that works well for a couple of days inform the entire team to update.

5.2. Configuration

The devonfw-ide aims to be highly configurable and flexible. The configuration of the devon command and environment variables takes place via devon.properties files. The following list shows these configuration files in the order they are loaded so files can override variables from files above in the list:

  1. build in defaults (for JAVA_VERSION, ECLIPSE_PLUGINS, etc.)

  2. ~/devon.properties - user specific global defaults (on windows in %USERPROFILE%/devon.properties)

  3. scripts/devon.properties - defaults provided by devonfw-ide. Never directly modify this file!

  4. devon.properties - vendor variables for custom distributions of devonfw-ide-scripts, may e.g. tweak SETTINGS_PATH or predefine SETTINGS_URL.

  5. settings/devon.properties (${SETTINGS_PATH}/devon.properties) - project specific configurations from settings.

  6. workspaces/${WORKSPACE}/devon.properties - optional workspace specific configurations (especially helpful in projects using docker).

  7. conf/devon.properties - user specific configurations (e.g. M2_REPO=~/.m2/repository). During setup this file is created by copying a template from ${SETTINGS_PATH}/devon/conf/devon.properties.

  8. settings/projects/*.properties- properties to configure project checkout and import

5.2.1. devon.properties

The devon.properties files allow to define environment variables in a simple and OS independent way:

  • # comments begin with a hash sign (#) and are ignored

  • variable_name=variable_value with space etc.

  • variable_name=${predefined_variable}/folder_name

    variable values can refer to other variables that are already defined what will be resolved to their value. You have to used ${…​} syntax to make it work on all platforms (never use %…​%, $…​, or $(…​) syntax in devon.properties files).

  • export exported_variable=this value will be exported in bash, in windows CMD the export prefix is ignored

  • variable_name=

    this will unset the specified variable

  • variable_name=~/some/path/and.file

    tilde is resolved to your personal home directory on any OS including windows.

  • array_variable=(value1 value2 value3)

    This will only work properly in bash worlds but as no arrays are used in CMD world of devonfw-ide it does not hurt on windows.

  • Please never surround values with quotes (var="value")

  • This format is similar to Java *.properties but does not support advanced features as unicode literals, multi-lined values, etc.

In order to know what to configure have a look at the available variables.

Please only tweak configurations that you need to change and take according responsibility. Flexibility comes with some price. Of course you can break everything if you do the wrong things.

Further, you can configure maven via conf/settings.xml. To configure your IDE such as eclipse or vscode you can tweak the settings.

5.3. Variables

The devonfw-ide defines a set of standard variables to your environment for configuration via variables[.bat] files. These environment variables are described by the following table. Those variables printed bold are also exported in your shell (except for windows CMD that does not have such concept). Variables with the value - are not set by default but may be set via configuration to override defaults. Please note that we are trying to minimize any potential side-effect from devonfw-ide to the outside world by reducing the number of variables and only exporting those that are required.

Table 1. Variables of devonfw-ide
Variable Value Meaning

DEVON_IDE_HOME

e.g. /projects/my-project

The top level directory of your devonfw-ide structure.

PATH

$PATH:$DEVON_IDE_HOME/software/java:…​

You system path is adjusted by devon command.

DEVON_HOME_DIR

~

The platform independent home directory of the current user. In some edge-cases (e.g. in cygwin) this differs from ~ to ensure a central home directory for the user on a single machine in any context or environment.

DEVON_IDE_TOOLS

java mvn eclipse vscode node npm ng ionic

List of tools that should be installed and upgraded by default for your current IDE.

DEVON_IDE_CUSTOM_TOOLS

-

List of custom tools that should be installed additionally. See software for further details.

DEVON_OLD_PATH

…​

A "backup" of PATH before it was extended by devon to allow recovering it. Internal variable that should never be set or tweaked.

WORKSPACE

main

The workspace you are currently in. Defaults to main if you are not inside a workspace. Never touch this variable in any varibales file.

WORKSPACE_PATH

$DEVON_IDE_HOME/workspaces/$WORKSPACE

Absolute path to current workspace. Never touch this variable in any varibales file.

JAVA_HOME

$DEVON_IDE_HOME/software/java

Path to JDK

SETTINGS_PATH

$DEVON_IDE_HOME/settings

Path to your settings. To keep oasp4j-ide legacy behaviour set this to $DEVON_IDE_HOME/workspaces/main/development/settings.

M2_REPO

$DEVON_IDE_HOME/conf/.m2/repository

Path to your local maven repository. For projects without high security demands, you may change this to the maven default ~/.m2/repository and share your repository amongst multiple projects.

MAVEN_HOME

$DEVON_IDE_HOME/software/maven

Path to Maven

MAVEN_OPTS

-Xmx512m -Duser.home=$DEVON_IDE_HOME/conf

Maven options

DEVON_SOFTWARE_REPOSITORY

-

Project specific or custom software-repository.

DEVON_SOFTWARE_PATH

-

Globally shared user-specific local software installation location.

ECLIPSE_VMARGS

-Xms128M -Xmx768M -XX:MaxPermSize=256M

JVM options for Eclipse

deprecated: ECLIPSE_PLUGINS

-

Array with "feature groups" and "update site URLs" to customize required eclipse plugins. Deprecated - see Eclipse plugins.

«TOOL»_VERSION

-

The version of the tool «TOOL» to install and use (e.g. ECLIPSE_VERSION or MAVEN_VERSION).

«TOOL»_BUILD_OPTS

e.g.clean install

The arguments provided to the build-tool «TOOL» in order to run a build.

«TOOL»_RELEASE_OPTS

e.g.clean deploy -Dchangelist= -Pdeploy

The arguments provided to the build-tool «TOOL» in order to perform a release build.

5.4. Devon CLI

The devonfw-ide is shipped with a central command devon. The setup will automatically register this command so it is available in any shell on your system. This page describes the Command Line Interface (CLI) of this command.

5.4.1. Devon

Without any arguments the devon command will determine your DEVON_IDE_HOME and setup your environment variables automatically. In case you are not inside of a devonfw-ide folder the command will echo a message and do nothing.

[/]$ devon
You are not inside a devon IDE installation: /
[/]$ cd /projects/my-project/workspaces/test/my-git-repo
[my-git-repo]$ devon
devonfw-ide has environment variables have been set for /projects/my-project in workspace main
[my-git-repo]$ echo $DEVON_IDE_HOME
/projects/devon
[my-git-repo]$ echo $JAVA_HOME
/projects/my-project/software/java

5.4.2. Commandlets

The devon command supports a pluggable set of commandlets. Such commandlet is provided as first argument to the devon command and my take additional arguments:

devon «commandlet» [«arg»]*

Technically a commandlet is a bash script located in $DEVON_IDE_HOME/scripts/command. So if you want to integrate another tool with devonfw-ide we are awaiting your pull-request.

The following commandlets are currently available:

5.4.3. build

The build commandlet is an abstraction of build systems like maven, gradle, yarn, npm, etc. It will auto-detect your build-system (via existence of files like pom.xml, package.json, etc.). According to this detection it will simply delegate to the according commandlet of the specific build system. If that build-system is not yet available it will be downloaded and installed automatically.

So devon build allows users to build any project without bothering about the build-system. Further specific build options can be configured per projects what allows devon build to be a universal part of every definition of done. Before pushing your changes simply always run the following command to verify the build:

devon build

You may also supply additional arguments as devon build «args». This will simply delegate these arguments to the detected build command (e.g. call mvn «args»).

5.4.4. 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 2. 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»]

install an additional plugin

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

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 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_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 following:

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

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

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" "http://andrei.gmxhome.de/eclipse/" "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.

5.4.5. gradle

The gradle commandlet allows to install, configure, and launch gradle. It is similar to gradle-wrapper. So calling devon gradle «args» is more or less the same as calling gradle «args» but with the benefit that the version of gradle preferred by your project is used (and will be installed if not yet available).

The arguments (devon gradle «args») are explained by the following table:

Table 3. Usage of devon gradle
Argument(s) Meaning

setup

setup gradle (install and verify), configurable via GRADLE_VERSION

«args»

run gradle with the given arguments («args»)

5.4.6. help

The help commandlet provides help for the CLI.

Table 4. Usage of devon help
Argument(s) Meaning

Print general help

«command»

Print help for the commandlet «command».

Please note that devon help «command» will do the same as devon «command» help.

5.4.7. ide

The ide commandlet manages your devonfw-ide. You need to supply additional arguments as devon ide «args». These are explained by the following table:

Table 5. Usage of devon ide
Argument(s) Meaning

setup [«SETTINGS_URL»]

setup devonfw-ide (cloning the settings from the given URL)

update [«package»]

update devonfw-ide

update scripts [to «version»]

update devonfw-ide

uninstall

uninstall devonfw-ide (if you want remote it entirely from your system)

setup

Run devon ide setup to initially setup your devonfw-ide. It is recommended to run the setup script in the toplevel 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 do the following things:

  • install the devon command on your system (if not already installed).

  • clone the settings (you may provide a git URL directly as argument or you will be prompted for it).

  • install all required software from DEVON_IDE_TOOLS variable (if not already installed).

  • configure all these tools

  • create IDE launch scripts

  • perform OS specific system integration such as WindowsExplorer integration (only done from setup script and not from devon ide setup)

update

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 following:

  • scripts: check if a new version of devonfw-ide-scripts is available. If so it will be downloaded and installed. As Windows is using file-locks, it is tricky to update a script while it is executed. Therefore, we update the scripts folder as an async background task and have to abort further processing at this point on windows as a workaround.

  • settings: update the settings (git pull).

  • software: update the software (e.g. if versions have changed via scripts or settings update).

  • projects: update the projects (checkout and import repositories into workspace/IDEs).

  • all: do all the above sequentially.

  • none: settings and software is updated by default if no extra argument is given. This is the regular usage for project developers. Only perform an update of scripts when you are requested to do so by your technical lead. Especially bigger projects need to test updates before rolling them out to the entire team. If developers would always update to the latest release of the scripts which is released globally, some project functionality might break causing problems and extra efforts in the teams.

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

devon ide update scripts to 3.1.99

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 successful test will communicate to the team to update to that exact version by providing the complete command as in the above example.

uninstall

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:

devon ide uninstall

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

5.4.8. intellij

The intellij commandlet allows to install, configure, and launch IntelliJ. To launch IntelliJ for your current workspace and devonfw-ide installation simply run: devon intellij

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

Table 6. Usage of devon intellij
Argument(s) Meaning

--all

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

setup

setup IntelliJ (install or update)

run

launch IntelliJ (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

5.4.9. ionic

The ionic commandlet allows to install, configure, and launch ionic (ionic-cli). Calling devon ionic «args» is more or less the same as calling ionic «args» but with some advanced features and ensuring that ionic is properly set up for your project.

The arguments (devon ionic «args») are explained by the following table:

Table 7. Usage of devon ionic
Argument(s) Meaning

setup

setup yarn (install and verify), configurable via YARN_VERSION

create

Create a new devon4ng ionic project.

cicd «args»

generate cicd files for the currect devon4ng project

«args»

run ionic with the given arguments («args»)

5.4.10. java

The java commandlet allows to install and setup Java. Also it supports devon4j. The arguments (devon java «args») are explained by the following table:

Table 8. Usage of devon java
Argument(s) Meaning

setup

setup OpenJDK (install or update and verify), configurable via JAVA_VERSION (e.g. 8u242b08 or 11.0.6_10)

create «args»

create a new Java project based on devon4j application template. If a single argument is provided, this is the package name and is automatically split into groupId and artifactId. Use -DdbType=«db» to choose the database (hana, oracle, mssql, postgresql, mariadb, mysql, h2, hsqldb). Any option starting with dash is passed as is."

migrate [from «version»] [single]

migrate a devon4j project to the latest version. If for some reasons the current devonfw version (e.g. oasp4j:2.6.0) can not be auto-detected you may provide it manually after the 'from' argument. Also the 'single' option allows to migrate only to the next available version."

cicd «args»

generate cicd files for the currect devon4java project

create

Examples for create a new devon4j application:

devon java create com.example.domain.myapp

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

devon java create -Dversion=0.0.1-alpha1 com.example.domain.myapp

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

devon java create com.example.domain.myapp com.example.group

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

devon java create com.example.domain.myapp com.example.group demo-app

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.

devon java create com.example.domain.myapp -DartifactId=demo-app -DdbType=hana

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.

devon java create com.example.domain.myapp -DdbType=oracle -Dversion=0.0.1 com.example.group -Dbatch=batch

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.

migrate

Example for migrating a devon4j application:

devon java migrate

Will migrate current devon4j application to the latest version available.

5.4.11. jenkins

The jenkins commandlet allows to install, configure, and launch Jenkins.

Table 9. Usage of devon jenkins
Argument(s) Meaning

setup

Setup Jenkins (install and verify)

start

Start your local Jenkins server

stop

Stop your local Jenkins server

add

Add current project as CI job to your local Jenkins

5.4.12. mvn

The mvn commandlet allows to install, configure, and launch maven. It is similar to maven-wrapper and mdub. So calling devon mvn «args» is more or less the same as calling mvn «args» but with the benefit that the version of maven preferred by your project is used (and will be installed if not yet available).

The arguments (devon mvn «args») are explained by the following table:

Table 10. Usage of devon mvn
Argument(s) Meaning

run default build, configurable via MVN_BUILD_OPTS

setup

setup Maven (install and verify), configurable via MAVEN_VERSION

get-version

Print the version of your current project. Will consolidate the version for multi-module projects ignoring dev[-SNAPSHOT] versions and fail on mixed versions.

set-version «nv» [«cv»]

Set the version of your current project to «nv» (assuming your current version is «cv»).

check-top-level-project

Check if you are running on a top-level project or fail if in a module or no maven project at all.

release

Start a clean deploy release build, configurable via MVN_RELEASE_OPTS

«args»

run maven with the given arguments («args»)

5.4.13. ng

The ng commandlet allows to install, configure, and launch ng (angular-cli). Calling devon ng «args» is more or less the same as calling ng «args» but with some advanced features and ensuring that ng is properly set up for your project.

The arguments (devon ng «args») are explained by the following table:

Table 11. Usage of devon ng
Argument(s) Meaning

setup

setup yarn (install and verify), configurable via YARN_VERSION

create

Create a new devon4ng project.

cicd «args»

generate cicd files for the currect devon4ng project

«args»

run ng with the given arguments («args»)

5.4.14. node

The node commandlet allows to install and setup node.js. The arguments (devon node «args») are explained by the following table:

Table 12. Usage of devon node
Argument(s) Meaning

setup

setup node.js (install and verify), configurable via NODE_VERSION

create «name» [«args»]

create a new devon4node application (same as devon4node new)

generate «s» [«args»]

generate devon4node components using the schematic «s» (same as devon4node generate)

db «c» [«args»]

execute a TypeORM command «c» (same as devon4node db)

cicd «args»

generate cicd files for the currect devon4node project

«args»

call NodeJS with the specified arguments

5.4.15. npm

The npm commandlet allows to install, configure, and launch npm. Calling devon npm «args» is more or less the same as calling npm «args» but with the benefit that the version of npm preferred by your project is used (and will be installed if not yet available).

The arguments (devon npm «args») are explained by the following table:

Table 13. Usage of devon npm
Argument(s) Meaning

run default build, configurable via NPM_BUILD_OPTS

setup

setup NPM (install and verify), configurable via NPM_VERSION

get-version

print the version of your current project

set-version «nv» [«cv»]

set the version of your current project to «nv» (assuming your current version is «cv»)

check-top-level-project

check if you are running on a top-level project or fail if in a module or no NPM project at all

release

Start a clean deploy release build, configurable via NPM_RELEASE_OPTS

«args»

run NPM with the given arguments («args»)

5.4.16. release

Create a release in a standardized way including the following steps:

  • verify the current project (no local changes, etc.)

  • determine «version» (if currently «version»-SNAPSHOT) and print out release information.

  • ask user for confirmation

  • bump release to «version» in build configuration (e.g. pom.xml files)

  • commit the change

  • create annotated tag for your release as release/«version»

  • invoke deployment on build-system

  • set next version as («version»+1)-SNAPSHOT in build configuration (e.g. pom.xml files)

  • commit the change

  • push your changes

Table 14. Usage of devon java
Argument(s) Meaning

…​

any optional argument will directly be passed to the actual command to build the deployment

Build-Tools

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:

mvn clean deploy -Dchangelist= -Pdeploy -P myProfile

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. Furhter, sticking to the defaults and follow the devonfw standard to name the profile for custom goals in deployment simply deploy is recommended.

5.4.17. sonar

The sonar commandlet allows to install, configure, and launch SonarQube.

Table 15. Usage of devon sonar
Argument(s) Meaning

setup

Setup SonarQube (install and verify)

start

Start your local SonarQube server

stop

Stop your local SonarQube server

analyze

Analyze current project with SonarQube

5.4.18. vscode

The vscode commandlet allows to install, configure, and launch Visual Studio Code. To launch VSCode for your current workspace and devonfw-ide installation simply run: devon vscode

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

Table 16. Usage of devon vscode
Argument(s) Meaning

--all

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

setup

setup VSCode (install or update)

run

launch VSCode (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

5.4.19. yarn

The yarn commandlet allows to install, configure, and launch npm. Calling devon yarn «args» is more or less the same as calling yarn «args» but with the benefit that the version of npm preferred by your project is used (and will be installed if not yet available).

The arguments (devon yarn «args») are explained by the following table:

Table 17. Usage of devon yarn
Argument(s) Meaning

run default build, configurable via YARN_BUILD_OPTS

setup

setup yarn (install and verify), configurable via YARN_VERSION

get-version

print the version of your current project

set-version «nv» [«cv»]

set the version of your current project to «nv» (assuming your current version is «cv»)

check-top-level-project

check if you are running on a top-level project or fail if in a module or no NPM project at all

release

start a clean deploy release build, configurable via YARN_RELEASE_OPTS

«args»

run yarn with the given arguments («args»)

5.5. 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 them to get more details.

5.5.1. 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 settings. You may customize this to your needs (configuring HTTP proxies, credentials, or other user-specific settings).

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

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

5.5.3. 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
│  ├── build
│  ├── eclipse
│  ├── gradle
│  ├── help
│  ├── ide
│  ├── intellij
│  ├── ionic
│  ├── java
│  ├── jenkins
│  ├── mvn
│  ├── ng
│  ├── node
│  ├── npm
│  ├── project
│  ├── release
│  ├── sonar
│  ├── 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. For windows there is also devon.bat to be used in CMD or PowerShell. As the devon CLI can be used as global command on your computer from any directory and gets installed centrally it aims to be stable, minimal, and lightweight. The key logic to setup 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.

5.5.4. settings

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

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

To test devonfw-ide or for small projects you can also use these the latest default settings. However, for collaborative projects we strongly encourage you to distribute and maintain the settings via a dedicated and project specific git repository (or any other version-control-system). This gives you the freedom to control and manage the tools with their versions and configurations during the project lifecycle. Therefore a technical lead creates a settings git repository for the project. He creates a "fork" devonfw-ide-settings by adding it as "upstream" origin and pulls from there finally pushing it to the project settings git. This also allows to later merge changes from the official devonfw-ide-settings back into the project specific settings "fork".

Structure

The settings folder (see SETTINGS_PATH) has to following 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). 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 usage 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 things 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.

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

Caution
If you use this power-feature you are taking responsibility for side-effects and should not expect support. Also if you are using Windows please read Symlinks in Windows and make your mind if you really want to do so. You might also use this hint and maintain it manually without enabling the following feature.

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:

DEVON_SOFTWARE_PATH=

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

Custom

In some cases a project might need a (proprietary) tool(s) that is 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 offers you to configure cutom 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 the the file URL to download for your platform (windows, linux, or mac).

As an example we define the following 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 to your software folder:

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

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

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

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

5.5.9. Project import

The devonfw-ide supports to automatically checkout 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 like to checkout 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
Table 18. Variables of project import
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.

workingsets

e.g. ws1,ws2

(optional) This will create workingssets (in eclipse). Each module (eclipse project) of this project will be part of all these workingsets. Workingsets 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. build or mvn -DskipTests=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 not that the .properties file is parsed via shell and not via java. So be careful with "advanced" features .properties files normally support.

Last updated 2020-06-06 05:20:49 UTC