#1917: add scripts for gui shortcut launcher windows, linux, macos by quando632 · Pull Request #2037 · devonfw/IDEasy

quando632 · 2026-06-17T09:29:40Z

This PR fixes #1917

Implemented changes

Instead of separate shell scripts (which end users never have access to), the shortcut creation
is now implemented directly in Java inside IdeasyCommandlet.installIdeasy().

Linux: writes ~/.local/share/applications/ideasy-gui.desktop from a bundled template,
calls update-desktop-database and marks it as trusted via gio set metadata::trusted
macOS: creates ~/Applications/IDEasy GUI.command (a .command file is executable by Finder)
Windows: reads the real Desktop path from the Shell Folders registry key (handles
OneDrive-redirected Desktops), then creates .lnk shortcuts on the Desktop and in the
Start Menu via PowerShell WScript.Shell

Assets added to the release package (cli/src/main/package/gui/):

logo.png — IDEasy logo used as icon on Linux/macOS
logo.ico — pre-generated ICO for Windows shortcuts
linux/ideasy-gui.desktop — .desktop template (version injected by Maven at build time)

The old gui/scripts/ shell scripts are removed — they were never part of the release
distribution and never reached end users.

Testing instructions

Windows

Run ideasy install (or setup.bat from a fresh download)
A shortcut IDEasy GUI appears on the Desktop and in the Start Menu
Open the Windows search bar, type IDEasy GUI, press Enter → GUI launches
Alternatively: double-click the Desktop shortcut → GUI launches

Linux

Run ideasy install
~/.local/share/applications/ideasy-gui.desktop is created
Open your application launcher, search for IDEasy GUI → entry appears and launches the GUI

macOS

Run ideasy install
~/Applications/IDEasy GUI.command is created
Double-click the file in Finder → GUI launches (mark as trusted on first run if prompted)

Checklist for this PR

Make sure everything is checked before merging this PR. For further info please also see
our DoD.

When running mvn clean test locally all tests pass and build is successful
PR title is of the form #«issue-id»: «brief summary» (e.g. #921: fixed setup.bat). If no issue ID exists, title only.
PR top-level comment summarizes what has been done and contains link to addressed issue(s)
PR and issue(s) have suitable labels
Issue is set to In Progress and assigned to you or there is no issue (might happen for very small PRs)
You followed all coding conventions
You have added the issue implemented by your PR in CHANGELOG.adoc unless issue is labeled
with internal
You have formulated clear instructions on how to test your contribution under "Testing instructions"

CLAassistant · 2026-06-17T09:31:22Z

All committers have signed the CLA.

coveralls · 2026-06-17T09:34:55Z

Coverage Report for CI Build 29107234689

Coverage increased (+0.02%) to 72.243%

Details

Coverage increased (+0.02%) from the base build.
Patch coverage: No coverable lines changed in this PR.
76 coverage regressions across 1 file.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

76 previously-covered lines in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
com/devonfw/tools/ide/tool/IdeasyCommandlet.java	76	74.56%

Coverage Stats


Relevant Lines:	16781
Covered Lines:	12633
Line Coverage:	75.28%
Relevant Branches:	7476
Covered Branches:	4891
Branch Coverage:	65.42%
Branches in Coverage %:	Yes
Coverage Strength:	3.19 hits per line

💛 - Coveralls

laert-ll · 2026-06-18T08:21:10Z

 laert@arch  ~/projects/IDEasy_1917/workspaces/main/IDEasy/gui/scripts/linux   feature/1917-create-desktop-shortcut ±  ./create-shortcuts.sh          
✓ Created: /home/laert/.local/share/applications/ideasy-gui.desktop
ℹ Launch from: Application Menu or Launcher
✓ Created: /home/laert//ideasy-gui.desktop
ℹ Launch from: Desktop

✓ IDEasy GUI shortcuts ready!

Usage:
  • Open your Application Menu and search for 'IDEasy GUI'
  • Or double-click the shortcut on your Desktop
  • First launch may take longer as Maven downloads dependencies

 laert@arch  ~/projects/IDEasy_1917/workspaces/main/IDEasy/gui/scripts/linux   feature/1917-create-desktop-shortcut ±  /./home/laert/ideasy-gui.desktop
/./home/laert/ideasy-gui.desktop: line 1: [Desktop: command not found
/./home/laert/ideasy-gui.desktop: line 4: GUI: command not found
/./home/laert/ideasy-gui.desktop: line 5: IDEasy: command not found
/./home/laert/ideasy-gui.desktop: line 9: IDE: command not found

The script works and the shortcut does appear in the Application Menu, but I cannot seem to open it either from the Launcher or by using the script in the home directory itself.

….com/quando632/IDEasy into feature/1917-create-desktop-shortcut

laert-ll · 2026-06-18T11:37:24Z

 laert@arch  ~/projects/IDEasy_1917/workspaces/main/IDEasy/gui/scripts/linux   feature/1917-create-desktop-shortcut ±  cat ~/.ideasy-gui.log        
---- Enj 18 Qer 2026 01:33:59.MD CEST ----
Error: IDEasy is not installed or not in PATH
Please install IDEasy first: https://github.com/devonfw/IDEasy#setup

As for the ideasy-gui.desktop script, I still get the same error message.

AdemZarrouki

when running the create-shortcuts in windows i get this:

$ powershell -File create-shortcuts.ps1
IDEasy GUI Launcher Setup
Project: C:\Users\projects\IDEasy\workspaces\main\IDEasy

Icon generated from devonfw.png
Creating shortcut: C:\Users\OneDrive - Capgemini\Desktop\IDEasy GUI.lnk
Created: C:\Users\OneDrive - Capgemini\Desktop\IDEasy GUI.lnk
Creating shortcut: C:\Users\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\IDEasy GUI.lnk
Created: C:\Users\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\IDEasy GUI.lnk

Setup complete!

But when running the gui i get this error

Error: IDEasy is not installed or not in PATH
https://github.com/devonfw/IDEasy#setup

Press any key to continue . . .

AdemZarrouki · 2026-06-24T07:37:58Z

Tested again in windows after the changes.
The Gui is successfully launched but the side terminal is present even after the gui is launched. Also when closing the GUI the side terminal still present with the same message Starting IDEasy GUI....

I think we need to change this behavior of the shortcut.

AdemZarrouki · 2026-06-24T07:46:09Z

In macos i get this

./create-shortcuts.sh                                                                                                                                                 ─╯
ℹ AppleScript unavailable, falling back to symlink...
✓ Created symlink: /Users/Applications/IDEasy GUI.command
ℹ Launch from: Applications > IDEasy GUI
ℹ AppleScript unavailable, falling back to symlink...
✓ Created symlink: /Users/Desktop/IDEasy GUI.command
ℹ Launch from: Desktop

✓ IDEasy GUI shortcuts ready!

Usage:
  • Open Finder and go to Applications
  • Double-click 'IDEasy GUI' to launch
  • Or double-click the Desktop shortcut

But then when opening the shortcut i get this

/Users//Projects/IDEasy/workspaces/main/IDEasy/gui/scripts/macos/launch-gui.command ; exit;
Error: IDEasy is not installed
Please install IDEasy first:
https://github.com/devonfw/IDEasy#setup

AdemZarrouki · 2026-06-24T12:47:09Z

Tested again after the changes on Windows and macOS. The shortcut was successfully created, and when clicking on it, the GUI launches.
The only issue I see is that it takes 5–7 seconds for the GUI to become visible to the user. This can be addressed in a separate issue (if relevant).

laert-ll · 2026-06-25T05:55:02Z

I tested the scripts locally on Linux again from the branch checkout and it works as intended. The create-shortcuts.sh creates the .desktop entry, and in the application menu I'm able to launch the GUI with no issues. Initially I had a lot of difficulties with this, because it turned out ide gui itself was not working in my environment in the first place. I'm not sure if ide gui is a feature intended to work out of the box or if there's extra steps to be done, but that is outside of the scope of this issue.

Also it is worth noting that the scripts are committed without the executable bit, so I had to chmod +x them before running them. Not sure if this is intentional.

Scripts were committed as 644 (likely from a Windows checkout), requiring a manual chmod +x before they could be run directly after checkout.

quando632 · 2026-06-26T09:35:40Z

Yeah you right i have added the correct executable bit for linux now

hohwille

@quando632 thanks for your PR. 👍
However, it seems things have been not clear.

Wasn't the expectation of the story #1917 that the start-menu entry and/or desktop shortcut gets installed automatically during the installation of IDEasy?

How would the end-user run create-shortcuts script if it is not included in our release that the end-user will download (he usually does not have the source-code of IDEasy)?

Further, sorry, if nobody told you before but after lots of trouble with scripting hell in CMD, Power-Shell, Bash, etc. we have decided to avoid such scripting and do as much as possible in Java avoiding any scripting as much as possible - see for example #1055

Since the scripts are not working for me, I think we need some rework.
I would suggest the following:

ensure to include our logo into the release, please also use our IDEasy logo instead of devonfw.png what is not our project logo.
as the logo will IMHO not change, simply generate the logo.ico for windows and also add it to git then you can avoid all the complex transformation scripting logic.

put the creation of the desktop entry into the Java installation code with OS specific if else coding. In case it is not clear where this is get started here:

IDEasy/cli/src/main/java/com/devonfw/tools/ide/tool/IdeasyCommandlet.java

Lines 267 to 301 in 423b614

    
           public void installIdeasy(Path cwd) { 
        
             Path ideRoot = determineIdeRoot(cwd); 
        
             Path idePath = ideRoot.resolve(IdeContext.FOLDER_UNDERSCORE_IDE); 
        
             Path installationPath = idePath.resolve(IdeContext.FOLDER_INSTALLATION); 
        
             Path ideasySoftwarePath = idePath.resolve(IdeContext.FOLDER_SOFTWARE).resolve(MvnRepository.ID).resolve(IdeasyCommandlet.TOOL_NAME) 
        
                 .resolve(IdeasyCommandlet.TOOL_NAME); 
        
             Path ideasyVersionPath = ideasySoftwarePath.resolve(IdeVersion.getVersionString()); 
        
             FileAccess fileAccess = this.context.getFileAccess(); 
        
             if (Files.isDirectory(ideasyVersionPath)) { 
        
               LOG.error("IDEasy is already installed at {} - if your installation is broken, delete it manually and rerun setup!", ideasyVersionPath); 
        
             } else { 
        
               List<Path> installationArtifacts = new ArrayList<>(); 
        
               for (Map.Entry<String, Boolean> artifactEntry : REQUIRED_INSTALLATION_ARTIFACTS.entrySet()) { 
        
                 String artifactName = artifactEntry.getKey(); 
        
                 boolean required = artifactEntry.getValue(); 
        
                 boolean success = addInstallationArtifact(cwd, artifactName, required, installationArtifacts); 
        
                 if (!success) { 
        
                   throw new CliException("IDEasy release is inconsistent at %s [artifact=%s]".formatted(cwd, artifactName)); 
        
                 } 
        
               } 
        
               fileAccess.mkdirs(ideasyVersionPath); 
        
               for (Path installationArtifact : installationArtifacts) { 
        
                 fileAccess.copy(installationArtifact, ideasyVersionPath); 
        
               } 
        
               this.context.writeVersionFile(IdeVersion.getVersionIdentifier(), ideasyVersionPath); 
        
             } 
        
             fileAccess.symlink(ideasyVersionPath, installationPath); 
        
             addToShellRc(BASHRC, ideRoot, null); 
        
             addToShellRc(ZSHRC, ideRoot, "autoload -U +X bashcompinit && bashcompinit"); 
        
             installIdeasyWindowsEnv(ideRoot, installationPath); 
        
             IdeLogLevel.SUCCESS.log(LOG, "IDEasy has been installed successfully on your system."); 
        
             LOG.warn("IDEasy has been setup for new shells but it cannot work in your current shell(s).\n" 
        
                 + "To use it here, run 'source ~/.bashrc' (or your shell config). Otherwise, open a new terminal or reboot."); 
        
           }

You can still include a static asset for e.g. the linux desktop file ideasy-gui.desktop into the OS specific folder under a new Linux subfolder. Then you can use maven filtering with placeholders so instead of hardcoding the version to 1.0 you can use

Version=$[project.version]

See here for how we have configured maven for this:

IDEasy/cli/pom.xml

Line 165 in 423b614

…esktop-shortcut # Conflicts: # CHANGELOG.adoc

…-desktop-shortcut # Conflicts: # CHANGELOG.adoc

….com/quando632/IDEasy into feature/1917-create-desktop-shortcut

hohwille

@quando632 thanks for your rework. This looks great now. 👍
Sorry, I could not fully complete the review today. However, I already wanted to provide the review comments I already made.
I guess there will not come more but I still have to complete the review next week.

BTW: For the logo.png that we here use as a small icon, should we scale it down and make it smaller? Otherwise we already have the logo.png in our git. If we keep it as is can't we avoid duplicating it in git by moving it and changing the references or by including it into the Linux assembly from its existing location?

hohwille · 2026-07-07T19:01:56Z

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Version=test-SNAPSHOT


Suggested change

Version=test-SNAPSHOT

Version=$[project.version]

hohwille · 2026-07-10T16:30:18Z

+Type=Application
+Name=IDEasy GUI
+Comment=Launch IDEasy GUI
+Exec=@IDEASY_BIN@ gui


Can't we come up with a simple command here that needs no additional replacement?
Something like

bash -c "$IDE_ROOT/_ide/installation/bin/ideasy gui"

hohwille · 2026-07-10T16:40:24Z

@@ -0,0 +1 @@
+logo.ico mock


Can't you just remove this Downloads folder and instead in your test simply copy ../cli/src/main/package/ to the faked HOME directory and use that as "installationPath"?
Then you do not need to mock resources.
And in case you do a *.png or *.ico file it should be valid (it may be an empty image with 0x0 pixels but it should be a valid png/ico file then).
Still the easiest and most maintainable solution should be to delete this Downloads folder and copy the real files.

feat: add scripts for gui launcher windows, linux, macos

e4d996f

github-project-automation Bot added this to IDEasy board Jun 17, 2026

github-project-automation Bot moved this to 🆕 New in IDEasy board Jun 17, 2026

quando632 added enhancement New feature or request windows specific for Microsoft Windows OS macOS specific for Apple MacOS linux specific for linux OS (debian, ubunutu, suse, etc.) GUI Graphical User Interface of IDEasy (aka dashboard) build with JavaFx labels Jun 17, 2026

quando632 added 2 commits June 17, 2026 12:13

feat: update scripts and using correct icon

e7c5854

Merge branch 'main' into feature/1917-create-desktop-shortcut

4fdac6f

Merge branch 'main' into feature/1917-create-desktop-shortcut

8ebccaf

hohwille assigned quando632 Jun 18, 2026

quando632 added 2 commits June 18, 2026 11:12

fix: minor directory bug for linux

2a7d872

Merge branch 'feature/1917-create-desktop-shortcut' of https://github…

88bbd81

….com/quando632/IDEasy into feature/1917-create-desktop-shortcut

feat: update linux script

470006e

quando632 moved this from 🆕 New to 🏗 In progress in IDEasy board Jun 19, 2026

hohwille moved this from 🏗 In progress to Team Review in IDEasy board Jun 22, 2026

hohwille assigned AdemZarrouki Jun 22, 2026

quando632 marked this pull request as ready for review June 22, 2026 08:49

Merge branch 'main' into feature/1917-create-desktop-shortcut

86ac392

AdemZarrouki suggested changes Jun 23, 2026

View reviewed changes

Comment thread .gitignore

Comment thread .gitattributes

quando632 added 2 commits June 23, 2026 15:04

fix: not updated root environment

1c7a1cc

fix: reset gitignore and attributes

87c0e24

doc: add issue to changelog

79e973c

quando632 added 3 commits June 24, 2026 10:13

feat: update window script to not open a new terminal

690be00

feat: add fix for macOs and Linux script

824a9a5

Merge branch 'main' into feature/1917-create-desktop-shortcut

bef16c6

AdemZarrouki approved these changes Jun 24, 2026

View reviewed changes

laert-ll self-assigned this Jun 25, 2026

fix: set executable bit on linux/macos gui shortcut scripts

193569b

Scripts were committed as 644 (likely from a Windows checkout), requiring a manual chmod +x before they could be run directly after checkout.

quando632 moved this from Team Review to 👀 In review in IDEasy board Jun 26, 2026

Merge branch 'main' into feature/1917-create-desktop-shortcut

033a2bf

hohwille requested changes Jul 3, 2026

View reviewed changes

Comment thread gui/scripts/linux/create-shortcuts.sh Outdated

Comment thread gui/scripts/linux/create-shortcuts.sh Outdated

Comment thread gui/scripts/linux/launch-gui.sh Outdated

maybeec and others added 7 commits July 4, 2026 11:45

Merge remote-tracking branch 'origin/main' into feature/1917-create-d…

0928f15

…esktop-shortcut # Conflicts: # CHANGELOG.adoc

Merge remote-tracking branch 'upstream/main' into feature/1917-create…

7276e4c

…-desktop-shortcut # Conflicts: # CHANGELOG.adoc

feat: create shortcut on ide installation

1c43f0e

devonfw#1917: create desktop shortcut on ide installation

1724881

devonfw#1917: add tests and fix shortcut creation robustness

1644850

Merge branch 'feature/1917-create-desktop-shortcut' of https://github…

11b1878

….com/quando632/IDEasy into feature/1917-create-desktop-shortcut

devonfw#1917: fix duplicate import and improve comment

e809173

quando632 moved this from 👀 In review to Team Review in IDEasy board Jul 8, 2026

quando632 and others added 3 commits July 8, 2026 14:52

fix: minor code quality issues

a216be2

Merge branch 'main' into feature/1917-create-desktop-shortcut

accfa9c

Update CHANGELOG for release 2026.07.002

a837418

hohwille reviewed Jul 10, 2026

View reviewed changes

	public void installIdeasy(Path cwd) {
	Path ideRoot = determineIdeRoot(cwd);
	Path idePath = ideRoot.resolve(IdeContext.FOLDER_UNDERSCORE_IDE);
	Path installationPath = idePath.resolve(IdeContext.FOLDER_INSTALLATION);
	Path ideasySoftwarePath = idePath.resolve(IdeContext.FOLDER_SOFTWARE).resolve(MvnRepository.ID).resolve(IdeasyCommandlet.TOOL_NAME)
	.resolve(IdeasyCommandlet.TOOL_NAME);
	Path ideasyVersionPath = ideasySoftwarePath.resolve(IdeVersion.getVersionString());
	FileAccess fileAccess = this.context.getFileAccess();
	if (Files.isDirectory(ideasyVersionPath)) {
	LOG.error("IDEasy is already installed at {} - if your installation is broken, delete it manually and rerun setup!", ideasyVersionPath);
	} else {
	List<Path> installationArtifacts = new ArrayList<>();
	for (Map.Entry<String, Boolean> artifactEntry : REQUIRED_INSTALLATION_ARTIFACTS.entrySet()) {
	String artifactName = artifactEntry.getKey();
	boolean required = artifactEntry.getValue();
	boolean success = addInstallationArtifact(cwd, artifactName, required, installationArtifacts);
	if (!success) {
	throw new CliException("IDEasy release is inconsistent at %s [artifact=%s]".formatted(cwd, artifactName));
	}
	}

	fileAccess.mkdirs(ideasyVersionPath);
	for (Path installationArtifact : installationArtifacts) {
	fileAccess.copy(installationArtifact, ideasyVersionPath);
	}
	this.context.writeVersionFile(IdeVersion.getVersionIdentifier(), ideasyVersionPath);
	}
	fileAccess.symlink(ideasyVersionPath, installationPath);
	addToShellRc(BASHRC, ideRoot, null);
	addToShellRc(ZSHRC, ideRoot, "autoload -U +X bashcompinit && bashcompinit");
	installIdeasyWindowsEnv(ideRoot, installationPath);
	IdeLogLevel.SUCCESS.log(LOG, "IDEasy has been installed successfully on your system.");
	LOG.warn("IDEasy has been setup for new shells but it cannot work in your current shell(s).\n"
	+ "To use it here, run 'source ~/.bashrc' (or your shell config). Otherwise, open a new terminal or reboot.");
	}

Uh oh!

Conversation

quando632 commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This PR fixes #1917

Implemented changes

Testing instructions

Checklist for this PR

Uh oh!

CLAassistant commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 29107234689

Coverage increased (+0.02%) to 72.243%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

laert-ll commented Jun 18, 2026

Uh oh!

laert-ll commented Jun 18, 2026

Uh oh!

AdemZarrouki left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AdemZarrouki commented Jun 24, 2026

Uh oh!

AdemZarrouki commented Jun 24, 2026

Uh oh!

AdemZarrouki commented Jun 24, 2026

Uh oh!

laert-ll commented Jun 25, 2026

Uh oh!

quando632 commented Jun 26, 2026

Uh oh!

hohwille left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hohwille left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hohwille Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

hohwille Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hohwille Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

quando632 commented Jun 17, 2026 •

edited

Loading

CLAassistant commented Jun 17, 2026 •

edited

Loading

coveralls commented Jun 17, 2026 •

edited

Loading

AdemZarrouki left a comment •

edited

Loading

hohwille left a comment •

edited

Loading