To start developing devonfw-ide, you must first install it on your computer. Therefore simply follow the setup guide. It is important to notice that this installation gives you the latest published version of the devonfw-ide with which you can execute commands like eclipse or docker whose scripts are located inside the "${DEVON_IDE_HOME}$/scripts/command, but for commiting code we use a differing folder structure. This will be addressed under Contribution.
To begin, read through the Contribution Guidelines, which you should be sure to follow.
First steps regarding forks or cloning of repos and creating branches, as well as some git commands, can be found in the first contributions guideline.
To contribute code or documentation regarding the devonfw-ide at first you need to fork the devonfw-ide repository and then you can clone your fork into the folder workspaces/main in your devonfw-ide installation.
Open git-bash in the cloned fork at workspaces/main/ide and run the following command:
git remote add upstream https://github.com/devonfw/ide.git
git fetch upstreamWhenever you want to implement a new change first do the following things:
git checkout master
git pull upstream master
git push
git checkout -b feature/«issue-id»-«brief-feature-description»Now you can do the changes, improvements, and fixes.
Once they are tested and seem to work, you can commit them (git commit -m "#«issue-id»: «description»").
If some days have passed meanwhile you should merge changes that meanwhile happened on the offical ide repo:
git pull upstream masterOnce you are complete and everything is merged and comitted, you can push your local feature branch and make it a remote branch of your fork on github:
git push -u origin feature/«issue-id»-«brief-feature-description»Now you can go to https://github.com/devonfw/ide/pulls and create the pull-request (PR) from your new feature.
Therefore, please click on the right down arrow of the green button and choose Create draft pull request and then click on Draft pull request.
When the checks have completed you can check the Definition-of-Done (DoD).
Once, all checks of the DoD are addressed, you can go the the very bottom of the PR and click on Ready for review what will take the PR out of the draft mode.
FYI: If you forgot the upstream merge (git pull upstream/master) or the upstream changed again while your PR is still open, you will see This branch is out-of-date with the base branch at the bottom of your PR and can click on Update branch.
For further development and testing, it is recommended to symlink the modified scripts into your devonfw-ide installation. Alternatively, the scripts can be adapted in the installation folder and then committed to the project. For creating a contribution also check the Definition of Done (DoD).
To improve the code quality the ShellCheck is used for devonfw-ide. There is a GitHub action CI build PR for this. If this fails at the PR, you can find the error messages in the big logfile under Build project with Maven. For example, these look like this:
Running test #2: test-shellcheck
In scripts/functions line 659:
doUnzip ${1} ${target_dir}
^--^ SC2086: Double quote to prevent globbing and word splitting.
^-----------^ SC2086: Double quote to prevent globbing and word splitting.
Did you mean:
doUnzip "${1}" "${target_dir}"
For more information:
https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent globbing ...Further explanations for ShellCheck errors can be found in the ShellCheck Wiki.
Own code can also be tested with the Online ShellCheck.
ShellCheck can also be run on the local development environment. To do this, ShellCheck (win, mac) can be extracted to the program directory. For windows the path to the executable (C:\Program Files\shellcheck-stable) has to be added to the PATH environment variable (instruction). In the resource folder of the project (scripts/src/main/resources) the following command can now be executed in the git-bash:
shellcheck -x -e SC2181 setup scripts/devon scripts/environment-project scripts/functions scripts/command/*For Mac and Linux, ShellCheck is automatically called during the build process (mvn install).
Many programs have a download link that depends on the operating system.
For a new tool create a folder in ide-mirrors repository named like the tool and the commandlet with the following files:
-
urlscontains the download URL(s) that typically contain placeholders like${ext}for extension,${os}for operating-system,${arch}for CPU architecture, or${code}for commandlet specific things. The file can hold multiple URLs - one per line. This is used if multiple mirrors are available so the load gets distributed. Therefore devonfw-ide will shuffle the URLs into random order and then try them sequentially so if one URL does not work (e.g. mirror unavailable) it will try the next one. -
ext-mappingcontains the mapping from operating system (OS) to the according file extension filled into the${ext}placeholder of the download for that OS. -
os-mappingcontains the remapping from OS to the value filled into the${os}placeholder of the URL. So you can e.g. remapwindows=winormac=darwinin case the download URLs do not follow common practices. You can even omit this file to fall back to the default os-mappings. -
arch-mappingcontains the remapping from architecture to the value filled into the${arch}placeholder of the URL. So you can e.g. remapaarch64=arm64orx86_64=x64in case the download URLs do not follow common practices. Simply omit this file if not needed. -
versionsin very special cases, you can create separate configurations in sub-folders for specific versions or version-ranges. Here you can specify a folder-name followed by a less-sign (<) and a version number to specify that if the version to install is less than this given version, the configuration will be read from that specified folder. The lines are processed top-down where the first match applies. An example can be found here. -
versions-urlcontains the url where all available versions can be found. If possible, check if the tool is available via the GitHub API (https://api.github.com/repos/<organisation>/<repository>/git/refs/tags). If that’s not possible, provide a different url as well as theversions-url-opfor this url. -
versions-url-opcontains the command used to extract the versions from the response ofcurl $versions-urlin a suitable format. This file is always required if you didn’t use the GitHub API for theversions-url. In case you used the GitHub API, you only have to create this file if the standardized approach doesn’t work (e.g. versions have the wrong format, there are versions left that need to be removed, …).
The file available-versions doesn’t have to be created manually. Using the versions-url and versions-url-op, available-versions will be generated and updated automatically by a GitHub Actions workflow.
It is important that the line endings of all files are UNIX \n.
Note that all rules within a mapping are checked from top to bottom.
If the first rule matches, the other rules are ignored. Therefore, the *-rule should always be last.
With the os-mapping the *-rule should be used for the Linux distributions, since the OS type is not only linux, but varies strongly.
It is also possible to use variables in the mapping files (esp. in os-mapping that happens first before other variables get replaced).
For example, if the architecture in the download link only appears for Windows, {arch} can be used in the `os-mapping. For an example see here.
Use an existing commandlet like HELM as a reference. Create a file with the name of the tool and put it in the folder scripts/command. The first part of the script contains the autocompletion, which should return the available parameters. Functions like setup or run or other additional functions follow. Finally, it defines which function should be executed depending on the parameter.
Use the doInstall method for the installation, which downloads the tool based on the mirrors, unpacks it if necessary and puts it in the software folder in the devonfw-ide installation:
doInstall "-" "«installation-folder»" "«tool-name»" "«tool-version»"For standard installations omit "«installation-folder»" (use the empty string arg "") what will install to ${DEVON_IDE_HOME}/software/«tool-name».
Find the license for the new tool and add the tool to the table of Third party components of the LICENSE.
If the license itself does not exist, add it to the end of the file as a new section.
The ide-settings repository allows project-specific configurations of the IDE tools. For your own settings, fork the repository, adjust the configuration and specify the repository URL during installation. Important notes on configuration and especially configuration files can be found in the configuration. In the configuration files many variables can be defined.
The following sub-sections give you some tipps and tricks to boost your productivty when developing features for devonfw-ide.
With symbolic links you can use one file or folder that is located inside one directory in one or multiple other directories, without copying the whole file or folder into the other directories. The file is still only saved at the initial location, but can be accessed through the created links in a much more comfortable way. So you are actually just linked to the original file and therefore don’t have to worry about differing versions of the file in your directories. This is very helpful for testing our devonfw-ide, because e.g. the commandlets folder for testing is not the same as the commandlets folder for git-commits. Install link shell extension and follow the instructions for installation and usage first. Later on you can make symbolic links of files or folder from your "git folder" and add them into the folder in which the testing is supposed to take place:
So select the folder ${DEVON_IDE_HOME}/workspaces/ide/scripts/src/main/resources/scripts/command/ and choose Pick Link Source and then go to ${DEVON_IDE_HOME}/scripts/ delete the command folder and re-create it as symbolic link via Drop as… > Symbolic link.
Do the same also for functions, functions-core, commandlet-cli, environment-project, environment-project.bat, devon, devon.bat, autocomplete, and devon-autocomplete.
Now changes you make in the first mentioned file will directly be available in your testing environment through the created file-link in the testing environment.
Have a look at advanced-tooling-generic.asciidoc for some helpfull developer tools.
For beginners:
You probably know this black box on Windows (the Command Prompt) that accepts commands like 'dir' that shows the content of the directory you are currently in, or 'cd' with which you can change the directory you are currently in and many more commands that allow you to interact with your Windows Operating System in a more direct and eventually faster way. Now for users of a Linux Distribution there is something similar, but way more powerfull, usually called "Bourne Again Shell", or in short Bash. This Command Line Interface or "Shell" is what we use most often when implementing something new for our Command-Line-Tool with the name devonfw-ide. Have a look at Bash in 150 Seconds. For MacOS you often also use BASH. That’s why it is often enough to implement code for Mac or Linux (at least to some extend as you’ll see soon enough) to be able to use it on both Operating Systems.
Let’s get to the practical part of the Bash-usage.
If you are using Windows, make sure that you have git-bash installed, so you can execute the Bash commands mentioned in this intruduction. [Here you can find git for windows](https://git-scm.com/download/win). In some cases later on you may want or need to use WSL. Our project teams standard way is to install WSL via Rancher Desktop, which is easily installable with the devonfw-ide by using the command devon docker setup. If you don’t have the devonfw-ide yet, then you can follow [this guide](https://github.com/devonfw/ide/blob/master/documentation/setup.asciidoc)
The following video gives you some important and helpful basics, still you don’t need to know all of these commands directly by heart. Instead under the video you’ll find a list with the commands mentioned in the video to make a command return to your mind. Also directly play around with those commands while watching the video to learn faster.
When you used to program in some other languages, you for sure know how helpful a google search in combination with the results on stackexchange can be.
If not, then google your question regarding Bash as usual and mostly you’ll find a way to get together the code you want.
Sometimes it needs more patience to get an acceptable result or to find out that a command you already knew includes what you need, if you add the proper tag to its execution.
Take the commands and some of their tags mentioned in this rather brief tutorial as an example. Also definetely try to use the help function from time to time, e.g. type in ls --help and you’ll see how much more the command ls can offer.
On the other side, especialy at the beginning, it is better to get an overview of available tags by googling e.g.
ls tags Bash to get a way prettier overview plus examples regarding a commands tags like here for ls.
If you have some experience with the Bash or directly want to see more:
The meaning of a tag or a sign combination (like $*, $#, or $()) can be hard to guess and also less easy to find during a google-search, because google won’t directly search for signs.
Then a syntax cheatsheet like this or like that one can spare you some searching time.
If you don’t know what a positional parameter like $1 is in Bash, then have a look at this introduction and play around with the tools mentioned to get a better understanding of how they work.
It’s definitively worth knowing the basics about positional parameters if you want to make some more advanced Bash-scripts.
There are a few more topics that I want to mention to you as you may come across them regularly in Bash-scripting.
The first one concerns regular expressions, which you will find during various coding situations.
Therefore have a look at this rather short introdcution on regex if you are unfamiliar with the so called regex.
Another one is about if-statements and square brackets for testing expressions by comparing them in different ways.
Maybe you’ll find something new or helpful here.
Finally, to possibly increase your knowledge while scripting bash-files, try out this spellchecker that can give you many details on how to improve your code.
Directly regarding our project:
In case you want to get your hands dirty with code that is already in use and comes from our ide-project, then you can try out the functions written in our functions-file. There are also some basic exercises related to our project that are not official yet, but you can ask for if you want to try some of them out to learn and challenge yourself a bit.
Scroll down on this site to get an overview of the documentation sections for the devonfw-ide, e.g. Home, Features, Download & Setup or have a look at the documentation files folder.