cinnamon-coder-hub
diff --git a/‎CHANGELOG.asciidoc
+5 b/‎CHANGELOG.asciidoc
+5
diff --git a/‎documentation/DoD.asciidoc
+3-1 b/‎documentation/DoD.asciidoc
+3-1
diff --git a/‎documentation/functions.asciidoc
+44-33 b/‎documentation/functions.asciidoc
+44-33
diff --git a/‎documentation/software.asciidoc
+7-5 b/‎documentation/software.asciidoc
+7-5
diff --git a/‎scripts/src/main/resources/scripts/command/aws
100644100755
+32-36 b/‎scripts/src/main/resources/scripts/command/aws
100644100755
+32-36
@@ -7,8 +7,13 @@ This file documents all notable changes to https://github.com/devonfw/ide[devonf
 New release with various improvements and bugfixes:
 
 * https://github.com/devonfw/ide/issues/826[#826]: List available versions for a tool
+* https://github.com/devonfw/ide/issues/878[#878]: Use default tool version from `available-versions`
+* https://github.com/devonfw/ide/issues/893[#893]: Ability to configure version prefix 
+* https://github.com/devonfw/ide/issues/908[#908]: AWS CLI integration for MacOS and bugfix for win/linux
+* https://github.com/devonfw/ide/issues/940[#940]: Make doInstall even more generic
 * https://github.com/devonfw/ide/issues/935[#935]: doDevonCommand should use doFail instead of doAskToContinue
 * https://github.com/devonfw/ide/issues/905[#905]: Better error handling when installing Eclipse plugins
+* https://github.com/devonfw/ide/issues/960[#960]: openshift version check fails
 * https://github.com/devonfw/ide/issues/929[#929]: Ensure function documentation is in sync
 
 The full list of changes for this release can be found in https://github.com/devonfw/ide/milestone/34?closed=1[milestone 2022.08.004].
 
@@ -22,7 +22,7 @@ However, chances to get your change merged quickly are higher if you address all
 * [ ] You followed all coding conventions (indent with 2 spaces, no tabs, functions start with `do` prefix, variables are enclosed with curly braces, variables in functions are declared with `local`, etc.)
 * [ ] You have already added the issue implemented by your PR in https://github.com/devonfw/ide/blob/master/CHANGELOG.asciidoc[CHANGELOG.asciidoc] to the next open release (see milestones or https://github.com/devonfw/ide/blob/master/.mvn/maven.config[maven.config]). If there is no issue for your PR consider creating it or directly link the PR itself. Please note that the CHANGELOG shall only reflect public changes relevant for end-users. So e.g. if we implement a story and then add another PR as bugfix or improvement to the same story, we do not need to document this in the CHANGELOG to avoid spam and confusion.
 * [ ] In case your PR adds a new tool `«tool»` as commandlet there are the following additional checks:
-** [ ] The tool is already available as folder `«tool»` in https://github.com/devonfw/ide-mirrors[ide-mirrors]
+** [ ] The tool is already available as folder `«tool»` in https://github.com/devonfw/ide-mirrors[ide-mirrors] including `available-versions`.
 ** [ ] A new commandlet named `«tool»` has been added to https://github.com/devonfw/ide/tree/master/scripts/src/main/resources/scripts/command[command] that allows to install and launch the given software.
 ** [ ] The tool can be installed automatically (during setup via settings) or via the commandlet call.
 ** [ ] During the installation process (`devon «tool» setup`) reasonable progress and status information are displayed.
@@ -36,6 +36,8 @@ However, chances to get your change merged quickly are higher if you address all
 ** [ ] The new tool is added to the table of tools in https://github.com/devonfw/ide/blob/master/documentation/LICENSE.asciidoc#license[LICENSE.asciidoc] with its according licesne. If that license is not yet included, the full license text needs to be added.
 ** [ ] The new commandlet is a https://github.com/devonfw/ide/blob/master/documentation/cli.asciidoc#command-wrapper[command-wrapper] for `«tool»`.
 ** [ ] The new commandlet installs potential dependencies automatically (e.g. `doDevonCommand «required-other-tool» setup silent`).
+** [ ] The new commandlet defines the variable `TOOL_VERSION_COMMAND` before sourcing the `functions`. If no version check is supported by the tool itself set the value to `-`. In case your commandlet is not about a tool that can be setup, simply set the value as empty to make this explicit.
+** [ ] If the new commandlet is about a tool that can be setup, then test that also `devon «tool» version list`, `devon «tool» version get`, and `devon «tool» version set` are all working.
 ** [ ] The variable `«TOOL»_VERSION` is honored by your commandlet so if present that version will be downloaded and installed.
 ** [ ] The new commandlet is tested on all plattforms it is availible for. Assuming you are using Windows, testing for Linux can be done with the Windows Subsystem for Linux and for MacOS we have a virtual cloud instance.
 * [ ] In case your PR adds, changes, or removes a function (in `functions` or `environment-project`) you need to update `functions.asciidoc` accordingly. There is an automated test that will fail otherwise.
@@ -192,11 +192,10 @@ If the URL is not provided as first argument, it will use the `mirrors` config t
 |`$3`   |name    |The name of the software to download.
 |`$4`   |version |The version of the software to download. May be omitted to download the latest version.
 |`$5`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
-|`$6`   |code    |The optional technical code used for specific software to compute download URL.
-|`$7`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
-|`$8`   |arch    |The optional architecture (e.g. x86_64).
-|`$9`   |ext     |The optional extension (e.g. 'tar.gz' or 'zip').
-|`$10`  |filename|The optional filename to save the downloaded file to.
+|`$6`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
+|`$7`   |arch    |The optional architecture (e.g. x86_64).
+|`$8`   |ext     |The optional extension (e.g. 'tar.gz' or 'zip').
+|`$9`   |filename|The optional filename to save the downloaded file to.
 |=======================
 
 === doDownloadInternal
@@ -206,10 +205,34 @@ If this does not happen, the name is determined from the URL.
 If the file exists and the force option was not specified, the function ends with a corresponding message and the return value 255.
 Otherwise the file is downloaded and, if successful, moved to the target directory.
 
+=== doEnvironmentProject
+Loads all `devon.properties` via xref:doLoadProperties[]. 
+If the first argument is not empty (set to `export`) it will export all the properties.
+Also it sets the environment variables `DEVON_HOME_DIR`, `WORKSPACE`, and `WORKSPACE_PATH`.
+Finally, it updates the `PATH` variable via xref:doUpdatePath[] and exports it.
+
 === doExtract
 Takes the file to be extracted and possibly a path to where it should be extracted.
 Then the right tool is selected based on the file extension and the file is unzipped.
 
+=== doResolveDownloadUrl
+Function for additional custom logic when resolving the download URL.
+The xref:doDownload[] function resolves standard variables like `version`, `os`, `arch`, and `ext` automatically in URLs from `mirrors` repository config.
+However, for special cases this is insufficient as some tools do not follow best-pratices for consistent and systematic download URLs.
+Therefore xref:doDownload[] will call this function to further resolve the computed download URL.
+By default this function does nothing but echoing the given URL (`$1`).
+However, a commandlet may override this function after souring `functions` in order to define custom logic for URL resolving.
+When required, we typically resolve a `code` variable that can be derived from the arguments given to this function.
+
+|=======================
+|*Param*|*Name*  |*Description*
+|`$1`   |URL     |The download URL with standard variables resolved.
+|`$2`   |version |The resolved version to download.
+|`$3`   |os      |The resolved/mapped operating system.
+|`$4`   |arch    |The resolved/mapped architecture (e.g. x86_64).
+|`$5`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
+|=======================
+
 === doGitPullOrClone
 Takes the target path and the URL or URL#branch as parameters.
 If the directory is a Git repository, it is tested whether remote repositories are configured and, if so, a git pull is performed.
@@ -219,37 +242,21 @@ However, if a URL was specified, the specified directory is created, changed to
 If the branch was also specified in the URL, a checkout is carried out on this branch.
 
 === doInstall
-The url of the software to be installed, the target directory in which the software is to be stored and the name of the software are given as parameters to the doInstall function.
-The function then downloads the software via doDownload into the download directory of the registered user, unpacks the software into the updates/extracted directory and then finally moves the software into the DEVON_IDE_HOME/software/"name of the software" directory.
-
-Additional parameters can also be passed to the function:
-
-* The version parameter ensures that a specific version of the software is installed.
-
-* If a "-" is passed to the function as the url, the settings from the Git repository ide-mirrors are used to download the correct software, e.g.
-depending on the operating system.
-
-* You can specify your own repository using the repository parameter or the DEVON_SOFTWARE_REPOSITORY variable.
-This ensures that the package to be installed is loaded from there.
-
-* If software is required that needs to be installed instead of just being unpacked and moved to the IDE_DEVON_HOME/software directory, you can set the directory for the installation software to DEVON_IDE_HOME/updates/install as the target directory.
-Following the doInstall call in the commandlet, the installation of the software can then be initiated.
-
-* If parameters five through nine (edition, code, os, arch, and ext) are specified, they are passed directly to the doDownload function.
+Ensures a specific version of a software is installed.
+If no fixed version is given, it resolves the final version (if version is empty use latest, in case of version prefix use latest matching version).
+In case the software is already installed in the resolved version, return `1`.
 
 |=======================
 |*Param*|*Name*  |*Description*
-|`$1`   |URL     |The explicit URL to download from or `-` to compute in xref:doDownload[].
-|`$2`   |path    |The absolute target path where to install the software.
-|`$3`   |name    |The name of the software to install.
-|`$4`   |version |The version of the software to install. May be omitted to install the latest version.
-|`$5`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
-|`$6`   |code    |The optional technical code used for specific software to compute download URL.
-|`$7`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
-|`$8`   |arch    |The optional architecture (e.g. x86_64).
-|`$9`   |ext     |The optional extension (e.g. 'tar.gz' or 'zip').
-|`$10`  |repo    |The optional software repository.
-|`$11`  |noUnpack|The optional argument to ignore extracting downloaded files (if not empty extracting will be skipped)
+|`$1`   |software|The name of the software to install.
+|`$2`   |version |The version of the software to install. May be omitted to install the latest version.
+|`$3`   |silent  |The optional silent flag ('silent' to suppress output if already up-to-date or empty for version output).
+|`$4`   |edition |The optional edition of the software to install (e.g. "enterprise" or "community").
+|`$5`   |path    |The absolute target path where to install the software.
+|`$6`   |os      |The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically.
+|`$7`   |noUnpack|The optional argument to ignore extracting downloaded files (use 'noUnpack' or leave empty to extract)
+|`$8`   |repo    |The optional software repository.
+|`$9`   |url     |The optional download URL.
 |=======================
 
 === doInstallWithPackageManager
@@ -408,6 +415,10 @@ If this is the case, the function ends with the return value 0, otherwise with 1
 Checks whether the module passed with the first parameter is contained in the package package.json.
 If so, then it ends with the return value 0 otherwise with a message and the return value 255.
 
+=== doIsPrefix
+Checks if the first arg is a prefix of the second arg.
+E.g. `doIsPrefix "foo/bar" "foo/bar/some"` will be true but `doIsPrefix "/foo/bar" "foo/bar/some"` will be false.
+
 === doParseOption
 Checks whether the parameter passed to it 
 
 
@@ -26,22 +26,24 @@ This subfolder needs to contain the tool in that version for every operating sys
 By default, each installation of `devonfw-ide` has its own physical installations of the required tools in the desired versions stored in its local `software` folder.
 While this is great for isolation of `devonfw-ide` installations and to prevent side-effects, it can cause a huge waste of disc resources in case you are having many installations of `devonfw-ide`.
 If you are a power-user of `devonfw-ide` with more then ten or even up to hundreds of installations on your machine, you might love to share installations of a software tool in a particular version between multiple `devonfw-ide` installations.
+In order to do so, you only need to link:configuration.asciidoc[configure] the variable `DEVON_SOFTWARE_PATH` in your `~/devon.properties` pointing to an existing absolute directory on your disc (e.g. `/projects/software` or `C:\projects\software`).
 
-CAUTION: 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 https://www.joshkel.com/2018/01/18/symlinks-in-windows/[Symlinks in Windows] and make your mind if you really want to do so. You might also use this link:advanced-tooling-windows.asciidoc#create-symbolic-links[hint] and maintain it manually without enabling the following feature.
+CAUTION: DEVON_SOFTWARE_PATH must be an absolte path that is an existing directory. On windows it has to be on the same drive as your IDE installations. If you use this power-feature you are taking responsibility for side-effects and should not expect support. You might also use this link:advanced-tooling-windows.asciidoc#create-symbolic-links[hint] and maintain it manually without enabling the following feature.
 
-In order to do so, you only need to link:configuration.asciidoc[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 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.
+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.
+This will disable this feature particularly for that specific sensitive `devonfw-ide` installation but let you use it for other ones.
 
 == Custom
 
 
@@ -10,19 +10,9 @@ then
   exit
 fi
 
-if [ -n "${DEVON_IDE_TRACE}" ]; then set -vx; fi
-TOOL_VERSION_COMMAND="aws --version"
 # shellcheck source=scripts/functions
 source "$(dirname "${0}")"/../functions
 
-# Call aws with specified arguments.
-function doRun() {
-  doSetup silent
-  findAws
-  doRunCommand "'${AWS}' ${*}"
-}
-
-
 # OS independent check if aws is installed.
 function findAws() {
   AWS="aws"
@@ -38,23 +28,32 @@ function findAws() {
     aws_win="${aws_win}/Amazon/AWSCLIV2/aws"
     if [ -f "${aws_win}" ]
     then
-      AWS="${aws_win}"
       AWS_INSTALLED="yes"
     fi
+    AWS="${aws_win}"
   fi
+  TOOL_VERSION_COMMAND="'${AWS}' --version"
+}
+
+findAws
+# shellcheck source=scripts/commandlet-cli
+source "$(dirname "${0}")"/../commandlet-cli
+
+# Call aws with specified arguments.
+function doRun() {
+  doSetup silent
+  findAws
+  doRunCommand "'${AWS}' ${*}"
 }
 
 # $1: path_to_package
-# $2: software version
-function doPackageInstall()
-{
+function doPackageInstall() {
   local path_to_package="${1}"
-  local version="${2}"
   if doIsWindows
   then
     doEcho "Installing AWS for Windows..."
     windows_path_to_package=$(cygpath -w "${path_to_package}")
-    powershell.exe -Command "Start-Process msiexec.exe -verb runas -Wait -ArgumentList '/I ${windows_path_to_package}\aws-${version}-windows.msi /quiet'"
+    powershell.exe -Command "Start-Process msiexec.exe -verb runas -Wait -ArgumentList '/I ${windows_path_to_package}\aws-*-windows.msi /quiet'"
   elif doIsMacOs
   then
     doEcho "Installing AWS for MacOS..."
@@ -71,45 +70,42 @@ function doPackageInstall()
 }
 
 function doSetup() {
-  local ERR=""
-  findAws
-  if [[ ${AWS_INSTALLED} != "yes" ]] || [[ "${1}" != "silent" ]]
+  if [ "${AWS_INSTALLED}" == "yes" ]
   then
-    # Get leatest release
-    if [ -z "${AWS_VERSION}" ]
+    if [ -z "${1}" ]
     then
-      doEcho "Getting latest release..."
-      AWS_VERSION=$(curl "https://github.com/aws/aws-cli/tags" | awk -F'tags/' '/archive/ { print $2}' | sort -r | head -1 | awk -F'.zip' '{print $1}')
+      doEcho "Aws already installed in version ${AWS_VERSION:-latest}"
+      doRunCommand "${TOOL_VERSION_COMMAND}" "verify installation of aws"
     fi
-
-    doInstall "-" "${DEVON_IDE_HOME}/updates/install/aws" "aws" "${AWS_VERSION}"
-    ERR="${?}"
-    if [ "${ERR}" = "0" ]
+  else
+    # workaround as we are downloading the installer and not installing the software itself
+    TOOL_VERSION_COMMAND="-"
+    doInstall "aws" "${AWS_VERSION}" "${1}" "" "${DEVON_IDE_HOME}/updates/install/aws"
+    if [ "${?}" = 0 ]
     then
-      doPackageInstall "${DEVON_IDE_HOME}/updates/install/aws" "${AWS_VERSION}"
+      doPackageInstall "${DEVON_IDE_HOME}/updates/install/aws"
+      findAws
+      if [ "${1}" != "silent" ] && ! doIsQuiet
+      then
+        doRunCommand "${TOOL_VERSION_COMMAND}" "verify installation of aws"
+      fi
     fi
     doRunCommand "rm -rf ${DEVON_IDE_HOME}/updates/install/aws"
-
-    if [ "${1}" != "silent" ] && ! doIsQuiet
-    then
-      doEcho "logon again to test aws with \"aws --version\""
-    fi
   fi
 }
 
-
 # CLI
 case ${1} in
 "help" | "-h")
   echo "Setup or run AWS CLI (command-line interface for Amazon-Web-Services)."
   echo
   echo "Arguments:"
   echo " setup                          install aws on your machine."
-  echo " «args»                         call aws with the specified arguments. Call aws --help for details or use aws directly as preferred."
+  echo " «args»                         call aws with the specified arguments. Call aws --help for details or use aws directly as preferred."
   echo
 ;;
 "setup" | "s" | "")
-  doSetup
+  doSetup "${2}"
 ;;
 *)
   doRun "${@}"