5. Usage
5.1. Roles
This section is designed to explain devonfw-ide
depending on each 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 automated and fast while you can have a nice cup of coffee (after you provided settings-URL
and accepted the license).
You only need the settings URL from your devonfw-ide
admin.
Experienced developers can directly call setup «settings-URL»
.
Otherwise if you just call setup
(e.g. by double-clicking it), you can enter it when you are prompted for Settings URL
(using copy&paste to avoid typos).
Update
To update your IDE (if instructed by your admin), you only need to run the following command:
devon ide update
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.
Working with multiple workspaces
If you are working on different branches in parallel you typically want to use multiple workspaces.
-
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
). -
Check out (
git clone …
) the according projects and branch into that workspace folder. -
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 parametercreate-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
You can easily customize and configure devonfw-ide
for the requirements of your project.
In order to do so, you need to create your own project-specific settings git repository and provide the URL to all developers for the setup.
With tools such as gitlab, bitbucket or github every developer can easily propose changes and improvements.
However, we suggest that one team member is responsible to ensure that everything stays consistent and works.
We will call this person the devonfw-ide
admin of your project.
The following are the suggested step-by-step instructions how an ide-admin
should prepare devonfw-ide
for his new project:
-
Fork ide-settings to a git repository specific for your project (e.g. a new project in the
gitlab
of yourproduction-line
instance). In case you are using github, all you need to do is use theFork
button. In other cases simply create a new and empty git repository and clone this to your machine. Then add the default ide-settings as origin, fetch and pull from it:git remote add upstream https://github.com/devonfw/ide-settings.git git fetch upstream git pull upstream master git push
Now you should have a full fork as a copy of the
settings
git repo with all its history that is ready for upstream merges. -
Study the structure of this git repository to understand where to find which configuration.
-
Study the configuration and understand that general settings can be tweaked in the toplevel
devon.properties
file of your settings git repository. -
Configure the tools and their versions for your project:
DEVON_IDE_TOOLS=(java mvn eclipse) ECLIPSE_VERSION=2020-06 # use e.g. 8u242b08 for Java 8 #JAVA_VERSION=8u242b08 JAVA_VERSION=11.0.5_10 MAVEN_VERSION=3.6.2
This way you will take over control of the tools and their versions for every developer in your project team and ensure that things get reproducible.
-
In case you need a proprietary or unsupported tool, you can study how to include custom tools.
-
In case you have very restrictive policies about downloading tools from the internet, you can create and configure a software repository for your project or company.
-
Some of the tools (espcially the actual IDEs) allow extensions via plugins. You can customize them to your needs for eclipse, VS code, or intelliJ.
-
In your
settings
git repository you will find aprojects
folder. Here you will find configurations files for every git project relevant for your actual project. Feel free to create new projects for your needs and delete thedevonfw
specific default projects. The projects documentation will explain you how to do this. -
For every IDE you will also find an according folder in your
settings
git repository. Here are the individual configuration settings for that IDE. You can change them by directly editing the according configuration files directly with a text-editor in yoursettings
git repository. However, this is a really complex way and will take you a lot of time to find the right file and property to tweak for your actual need. Instead we suggest to study how to customize IDE specific settings. -
You may also create new sub-folders in your
settings
git repository 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 instead. -
You may want to customize the Eclipse spellchecker dictionary for your project and your language.
All described in the above steps (except the first one) can be used to manage and update the configuration during the project lifecycle. However, when you have done changes especially in a larger project, please consider the following best-practices to avoid that a large teams gets blocked by a non-functional IDE:
-
Commit your changes to a feature-branch.
-
First test the changes yourself.
-
If all works as expected, pick a pilot user of the team to test the changes from the feature branch (go to
settings
folder,git fetch
,git checkout -t origin/feature/«name»
,devon ide update
). -
Only after that works well for a couple of days, inform the entire team to update.
Announce changes to your team
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
.
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:
-
build in defaults (for
JAVA_VERSION
,ECLIPSE_PLUGINS
, etc.) -
~/devon.properties
- user specific global defaults (on windows in%USERPROFILE%/devon.properties
) -
scripts/devon.properties
- defaults provided bydevonfw-ide
. Never directly modify this file! -
devon.properties
- vendor variables for custom distributions ofdevonfw-ide-scripts
, may e.g. tweakSETTINGS_PATH
or predefineSETTINGS_URL
. -
settings/devon.properties
(${SETTINGS_PATH}/devon.properties
) - project specific configurations from settings. -
workspaces/${WORKSPACE}/devon.properties
- optional workspace specific configurations (especially helpful in projects using docker). -
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
. -
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, which will be resolved to their value. You have to used
${…}
syntax to make it work on all platforms (never use%…%
,$…
, or$(…)
syntax indevon.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 ofdevonfw-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. There is a price to pay for flexibility, which means you have to be careful what you do.
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.
Variable | Value | Meaning |
---|---|---|
|
e.g. |
The top level directory of your |
|
|
You system path is adjusted by |
|
|
The platform independent home directory of the current user. In some edge-cases (e.g. in cygwin) this differs from |
|
|
List of tools that should be installed and upgraded by default for your current IDE. |
|
|
List of custom tools that should be installed additionally. See software for further details. |
|
|
A "backup" of |
|
|
The workspace you are currently in. Defaults to |
|
|
Absolute path to current workspace. Never touch this variable in any |
|
|
Path to JDK |
|
|
Path to your settings. To keep |
|
|
Path to your local maven repository. For projects without high security demands, you may change this to the maven default |
|
|
Path to Maven |
|
|
Maven options |
|
|
Project specific or custom software-repository. |
|
|
Globally shared user-specific local software installation location. |
|
|
JVM options for Eclipse |
deprecated: |
|
Array with "feature groups" and "update site URLs" to customize required eclipse plugins. Deprecated - see Eclipse plugins. |
|
|
The version of the tool |
|
e.g. |
The arguments provided to the build-tool |
|
e.g. |
The arguments provided to the build-tool |
|
If value is not an empty string, the |
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 argument 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 may 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 project. This makes devon build
a universal part of every definition of done. Before pushing your changes, please 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:
Argument(s) | Meaning |
---|---|
|
if provided as first arg then to command will be invoked for each workspace |
|
setup Eclipse (install or update) |
|
install an additional plugin |
|
launch Eclipse (default if no argument is given) |
|
same as |
|
update workspace |
|
reverse merge changes from workspace into settings |
|
reverse merge adding new properties |
|
create launch script for this IDE, your current workspace and your OS |
There are variables that can be used for Eclipse. These are explained by the following table:
Variable | Default-Value | Meaning |
---|---|---|
|
|
The version of the tool Eclipse to install and use. |
|
|
The edition of the tool Eclipse to install and use. You can choose betwenn 'java' for standard edition or 'jee' for enterprise edition. |
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_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_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 customizedevonfw-ide
with new plugins you can first install them manually and then go toAbout Eclipse > Installation Details
then you can filter for your newly installed plugin and find the values in theId
column. Copy & paste them from here to make up your own custom config. -
plugin_active
is an optional parameter. If it istrue
(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 viadevon eclipse add-plugin «plugin-name»
from the config filesettings/eclipse/plugins/«plugin-name».properties
. See thesettings/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.
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.
dictionary
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.
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:
-
German: https://sourceforge.net/projects/germandict/ (has to be converted to UTF-8 e.g. with Notepad++ via
Encoding > Convert to UTF-8
)
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:
Argument(s) | Meaning |
---|---|
|
setup gradle (install and verify), configurable via |
|
run gradle with the given arguments ( |
5.4.6. help
The help
commandlet provides help for the CLI.
Argument(s) | Meaning |
---|---|
Print general help |
|
|
Print help for the commandlet |
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:
Argument(s) | Meaning |
---|---|
|
setup devonfw-ide (cloning the settings from the given URL) |
|
update devonfw-ide |
|
update devonfw-ide |
|
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 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:
-
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 fromdevon 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 follows:
-
scripts
: check if a new version ofdevonfw-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 thescripts
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 viascripts
orsettings
update). -
projects
: update the projects (checkout and import repositories into workspace/IDEs). -
all
: do all the above sequentially. -
none:
settings
andsoftware
are updated by default if no extra argument is given. This is the regular usage for project developers. Only perform an update ofscripts
when you are requested to do so by your technical lead. Bigger projects especially need to test updates before rolling them out to the entire team. If developers always updated the latest release of thescripts
which is released globally, some project functionality would 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 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.
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 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.
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:
Argument(s) | Meaning |
---|---|
|
if provided as first arg then to command will be invoked for each workspace |
|
setup IntelliJ (install or update) |
|
launch IntelliJ (default if no argument is given) |
|
same as |
|
update workspace |
|
reverse merge changes from workspace into settings |
|
reverse merge adding new properties |
|
create launch script for this IDE, your current workspace and your OS |
There are variables that can be used for IntelliJ. These are explained by the following table:
Variable | Default-Value | Meaning |
---|---|---|
|
|
The version of the tool IntelliJ to install and use. |
|
|
The edition of the tool IntelliJ to install and use. The value |
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:
Argument(s) | Meaning |
---|---|
|
setup yarn (install and verify), configurable via |
|
Create a new devon4ng ionic project. |
|
generate cicd files for the currect devon4ng project |
|
run ionic with the given arguments ( |
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:
Argument(s) | Meaning |
---|---|
|
setup OpenJDK (install or update and verify), configurable via |
|
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 |
|
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." |
|
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.
Argument(s) | Meaning |
---|---|
|
Setup Jenkins (install and verify) |
|
Start your local Jenkins server |
|
Stop your local Jenkins server |
|
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:
Argument(s) | Meaning |
---|---|
run default build, configurable via |
|
|
setup Maven (install and verify), configurable via |
|
Print the version of your current project. Will consolidate the version for multi-module projects ignoring |
|
Set the version of your current project to |
|
Check if no |
|
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 |
|
run maven with the given arguments ( |
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:
Argument(s) | Meaning |
---|---|
|
setup yarn (install and verify), configurable via |
|
Create a new devon4ng project. |
|
generate cicd files for the currect devon4ng project |
|
run ng with the given arguments ( |
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:
Argument(s) | Meaning |
---|---|
|
setup node.js (install and verify), configurable via |
|
create a new devon4node application |
|
generate devon4node components using the schematic «s» |
|
execute a TypeORM command «c» |
|
generate cicd files for the currect devon4node project |
|
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:
Argument(s) | Meaning |
---|---|
run default build, configurable via |
|
|
setup NPM (install and verify), configurable via |
|
print the version of your current project |
|
set the version of your current project to |
|
check if you are running on a top-level project or fail if in a module or no NPM project at all |
|
Start a clean deploy release build, configurable via |
|
run NPM with the given arguments ( |
5.4.16. release
Create a release in a standardized way including the following steps:
-
verify the current project (no local changes, etc.)
-
warn if
«version»-SNAPSHOT
dependencies are used -
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
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.
Further, 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.
Argument(s) | Meaning |
---|---|
|
Setup SonarQube (install and verify) |
|
Start your local SonarQube server |
|
Stop your local SonarQube server |
|
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:
Argument(s) | Meaning |
---|---|
|
if provided as first arg then to command will be invoked for each workspace |
|
setup VSCode (install or update) |
|
launch VSCode (default if no argument is given) |
|
same as |
|
update workspace |
|
reverse merge changes from workspace into settings |
|
reverse merge adding new properties |
|
create launch script for this IDE, your current workspace and your OS |
plugins
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:
plugin_id=devonfw.devonfw-extension-pack
plugin_active=true
The variables are defined as following:
-
plugin_id
defines the unique ID of the plugin to install. If you want to customizedevonfw-ide
with new plugins click onExtensions
at the bottom of the left navigation icon bar in VS code. Then use the search to find the plugin of your choice. If you click on it the plugin ID is displayed in grey beside the official title at the top of the plugin details page. Copy & paste the ID from here to make up your own custom config. -
plugin_active
is an optional parameter. If it istrue
(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 viadevon vscode add-plugin «plugin-name»
from the config filesettings/vscode/plugins/«plugin-name».properties
. See thesettings/vscode/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. 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.
cleaning plugins on update
If you want to striclty manage the plugins for VS code
in your project, you can create or edit the file settings/vscode/plugins
in your settings and add this variable:
clean_plugins_on_update=true
This will wipe all plugins when an update of VS code
is performed (e.g. via devon ide update
) and reinstall all configured plugins. While this gives you more control over the governance of the plugins and allows to remove a plugin later during project lifecycle. However, this will delete all manually installed plugins automatically without asking.
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:
Argument(s) | Meaning |
---|---|
run default build, configurable via |
|
|
setup yarn (install and verify), configurable via |
|
print the version of your current project |
|
set the version of your current project to |
|
check if you are running on a top-level project or fail if in a module or no NPM project at all |
|
start a clean deploy release build, configurable via |
|
run yarn with the given arguments ( |
5.5. Structure
The directory layout of your devonfw-ide
will look like this:
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.
5.5.1. conf
This folder contains configurations for your IDE:
/ 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 fordevonfw-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.
/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
.
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
.
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 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:
/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. foreclipse/lifecycle-mapping-metadata.xml
, oreclipse/project.dictionary
). -
The
devon
folder insettings
contains templates for configuration files. There are copied to thedevonfw-ide
installation during setup (if no such file already exists). In this way thesettings
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.
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 (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
, ormac
).
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
.
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:
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 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
Variable | Value | Meaning |
---|---|---|
|
e.g. |
(required) Path into which the projects is cloned. This path is relative to the workspace. |
|
e.g. |
(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 to use for checkout and import. Default is |
|
(required) Git URL to use for cloning the project. |
|
|
e.g. |
(optional) Git branch to checkout. Git default branch is default. |
|
e.g. |
(optional) The directory inside |
|
e.g. |
(optional) The devonfw command to invoke to build the project after clone or pull. If omitted no build is triggered. |
|
e.g. |
(optional) Desired action for eclipse IDE. If you put |
|
|
(optional) If set to |
Please note that the .properties
file is parsed via shell and not via java. So be careful with "advanced" features .properties
files normally support.