- Documentations of functions
- 1. Functions for testing flags
- 2. Functions for input and output
- 3. Environment Checks
- 4. Functions to verify requirements
- 5. Functions for generic command execution
- 6. Functions for IO operations (download, install, backup, extract, load, save)
- 6.1. doBackup
- 6.2. doBrewInstall
- 6.3. doDownload
- 6.4. doDownloadInternal
- 6.5. doEnvironmentProject
- 6.6. doExtract
- 6.7. doGitPullOrClone
- 6.8. doInstall
- 6.9. doInstallWithPackageManager
- 6.10. doLoadProperties
- 6.11. doMoveGlobSafe
- 6.12. doOpen
- 6.13. doReplaceExtracted
- 6.14. doReplaceExtractedFile
- 6.15. doReplaceExtractedSkipSingleFolder
- 6.16. doUnzip
- 6.17. doUpdateUrls
- 6.18. doCheckNetworkStatus
- 7. Functions on system PATH, files, or folders
- 8. Version handling
- 8.1. doCheckSoftwareSecurityVersion
- 8.2. doCheckVersionRange
- 8.3. doGetAnyLatestSoftwareVersion
- 8.4. doGetLatestSoftwareVersion
- 8.5. doGetNextVersion
- 8.6. doGetSoftwareEdition
- 8.7. doGetSoftwareVersion
- 8.8. doIsDevVersion
- 8.9. doListSoftwareVersions
- 8.10. doReportVersionSecurityWarning
- 8.11. doSetSoftwareVersion
- 8.12. doVersionCompare
- 9. Functions on workspaces
- 10. Functions for Maven
- 11. Misc
The functions for testing flags return 0 (true) if flag is set and 1 (false) otherwise.
The name of the flag is part of the function name.
Determines if batch mode is active.
This mode shall be used for non-interactive usage (e.g. in automated invocations) where no user is available for interactive feedback.
It can be enabled with -b or --batch.
Determines if debug mode is active.
This mode activates more verbose output for debugging.
It can be enabled with -d or --debug.
Determines if force mode is active.
This mode enforces specific aspects such as downloading cached resources again or to answer questions to continue automatically with yes.
It can be enabled with option -f or --force.
Output functions like doEcho support backslash-escaped characters, for example "\n" for new line.
Display a question and ask the user if he wants to continue. In force or batch mode, it will continue automatically.
Param |
Name |
Description |
|
question |
The question to display. Defaults to |
|
return |
If the user does not want to continue, this function will exit immediately by default. However, if |
Passes all arguments to doWarning to print as warning. Then it calls doAskToContinue.
Prints the given arguments as debug message with according coloring (in gray). Debug messages will be printed in debug mode.
Prints the given arguments as regular info message. The message will be suppressed in quiet mode.
Like doWarning but prefixes the message with an ATTENTION header.
Prints the given arguments as interaction message with according coloring (in light blue). An interaction message is an information or question the end-user should react to with interactive feedback.
Prints the given arguments as option message with according coloring (in light blue). An option message is an option the user can choose from.
Prints the given arguments as step message with according coloring (in purple). A step message informs about a step as part of a command or process that has been completed.
Prints the given arguments as error message with according coloring (in bright red). An error message informs the user that something went wrong. The coloring should help to highlight such problems.
Prints the given arguments as info message with according coloring (in blue). An information message is a more important message but not indicating any problem (like warning or error).
Ensures that the end-user confirms the license agreement of devonfw-ide on the first usage on his machine.
If the user has already confirmed, this function will have no effect.
Otherwise it will print the logo followed by the license information.
This contains a link that will also be opened automatically in the web-browser.
Then doAskToContinue is used to let the user confirm the license agreement.
If the user does not confirm or runs in batch mode this function will fail with an error message.
Otherwise, the user confirmation will be saved to $DEVON_HOME_DIR/.devon/.license.agreement.
Prints out the devon logo with clipping if the width of the terminal is too small to prevent line-wrapping.
Passes arguments to doEchoInteraction.
Calls doDevonCommandAndReturn and passes all the parameters. On success it calls doUpdatePath to ensure the PATH is updated after an installation. On failure it will ask to continue if not in batch mode or exit immediately with the error code.
Iterates over all workspaces (sub-folders of workspaces folder) and executes the given commandlet in each of them.
Runs the commandlet at $DEVON_IDE_HOME/scripts/command/$1 with the further given arguments.
It will automatically pass mode options like batch to the commandlet before other given arguments.
Further it prints an error message if the commandlet was not successful.
It will return with the exit code of the commandlet that has been invoked.
Param |
Name |
Description |
|
commandlet |
The devonfw-ide commandlet to call. E.g. |
|
args |
Any additional argument is passed to the specified commandlet. |
Executes the given command ($1).
If a a third parameter ($3) is provided, it has to point to an existing directory where to command will be executed and the function will return back to the original directory afterwards.
It will use doResult using the message ($2) to handle the result of the command execution (success or failure).
Param |
Name |
Description |
|
command |
The command to execute including all its parameters. |
|
message |
Optional description of the command. Will fall back to "run command" followed by a simplification of the command ( |
|
dir |
Optional working directory where to execute the command. |
Runs the first executable from the given arguments. It supports executables but can also run EXE and MSI files on windows.
It will only return if the execution was successful. Otherwise it will always exit.
For example doRunFirstExecutable "${dir}/".msi "${dir}/".exe will run the first found MSI or EXE file from the directory ${dir}.
Takes a file or directory as the first parameter and the date after which the backup directory is named that is to be created in the updates/backups subdirectory for the backup as the second parameter.
If the second parameter is not specified, the current date is used.
If a single file is specified in the first parameter and such a file already exists in the backup directory, then a time stamp is added to the backup directory as an additional subdirectory.
Then the backup directory is created and the files to be backed up are moved there.
Installs a tool using homebrew.
If homebrew is installed (brew command found), the desired tool will be installed using brew install.
Otherwise, the function will fail with an error message guiding the user to install homebrew.
Downloads an artifact from the internet.
If the URL is not provided as first argument, it will use the urls config to automatically determine the URL from the other arguments.
Param |
Name |
Description |
|
URL |
The explicit URL to download from or |
|
dir |
The optional target directory where to save the downloaded file. |
|
name |
The name of the software to download. |
|
version |
The version of the software to download. May be omitted to download the latest version. |
|
edition |
The optional edition of the software to install (e.g. "enterprise" or "community"). |
|
os |
The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically. |
|
arch |
The optional architecture (e.g. x86_64). |
|
ext |
The optional extension (e.g. 'tar.gz' or 'zip'). |
|
filename |
The optional filename to save the downloaded file to. |
Takes the URL as the first parameter, a temporary name for the file to be downloaded as the second, and the target directory in which the file is to be stored as the third parameter. Optionally, the name of the downloaded file can be given as a fourth parameter. 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.
Loads all devon.properties via 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 doUpdatePath and exports it.
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.
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. If not, a corresponding message is output and the function is ended with a return value of 1. If the directory is not a Git repository and no URL was specified, the function is aborted with a doFail message. However, if a URL was specified, the specified directory is created, changed to the directory and the repository of the specified URL is cloned into the specified directory. If the branch was also specified in the URL, a checkout is carried out on this branch.
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 |
|
software |
The name of the software to install. |
|
version |
The version of the software to install. May be omitted to install the latest version. |
|
silent |
The optional silent flag ('silent' to suppress output if already up-to-date or empty for version output). |
|
edition |
The optional edition of the software to install (e.g. "enterprise" or "community"). |
|
path |
The absolute target path where to install the software. |
|
os |
The optional OS indicator ('-' if OS independent). If omitted the OS will be determined automatically. |
|
noUnpack |
The optional argument to ignore extracting downloaded files (use 'noUnpack' or leave empty to extract) |
|
repo |
The optional software repository. |
|
url |
The optional download URL. |
|
target filename |
The optional target filename. |
Called with a list of installation options for various (non windows) operating systems.
For each provided installer option it will check if that installer (e.g. apt-get, yum, apk, brew) is present.
If present, it will call that option with sudo and return.
In case none of the provided installer options could be executed, it will fail with an according error message.
Loads a .properties file given as first argument into variables of the bash context.
The second argument allows to specify an optional prefix for the variables to load.
So e.g. if the properties file contains foo=bar and seconds argument is some_ it will result in the variable assignment some_foo=bar.
In case the third argument is not empty, then all variables will be exported.
*ATTENTION: This function is defined in the file environment-project.
Moves the file specified as the second parameter after checking whether it exists to the target specified in parameter one and outputs the performed action via doEcho.
Opens the URL passed to it in the browser window or calls the specified program under Windows or MacOS.
Prepares to move an unpacked archive (specified in the first parameter). The current date is defined as the name for the backup directory of the currently installed software. Then it is checked whether the target directory (specified in the second parameter) corresponds to DEVON_IDE_HOME. If it does not correspond to DEVON_IDE_HOME, the function doReplaceExtractedSkipSingleFolder is called and the parameters archive directory, target directory, backup directory and the specification that all files in the archive directory are to be processed are passed. If the target directory is DEVON_IDE_HOME, which corresponds to the complete devonfw IDE installation, then all files and directories, except the workspaces directory, are passed in a loop to the doReplaceExtractedFile function as the first parameter, the second parameter specifies the target directory with the corresponding subdirectory names and the third Parameter is the backup directory. Attention: for one installation package the function doReplaceExtractedSkipSingleFolder is called, while in the other case the function doReplaceExtractedFile is called in a loop.
Called with the three parameters path of the file or directory to be moved, the target directory and a backup directory. The function creates missing directories, makes a backup from the target directory to the backup directory. Then the files specified in the first parameter are moved to the target directory. Finally, the migration script is run to migrate the ide to the latest version.
The parameters source directory, target directory, backup directory and possibly a list of files and directories via shell file name expansion (globbing) are passed to the doReplaceExtractedSkipSingleFolder function. The first three parameters are taken directly into variables and removed from the list of passed parameters with the shift so that the last specification can be viewed as a whole. If the last parameter is a single directory and, on MacOS, not a directory with a name like *.app, it is taken as the source directory. Then the function doReplaceExtractedFile is called with the saved parameters, with source directory, target directory and backup directory.
Checks if an unzip program is installed, and if not, installs the program. The file specified in the first parameter is then unpacked into the directory specified in the second parameter.
Uses doGitPullOrClone to clone or pull urls ensuring that everything is up-to-date.
Takes a directory as a parameter. The function then checks whether the "bin" subdirectory exists in the transferred directory. If the directory exists, the PATH variable is extended by this "bin" directory. Otherwise the PATH variable is expanded with the passed directory.
Takes a file name as a parameter, including the path, and returns the file extension as the result.
Takes a list of directories as a parameter and then checks in the specified order until one of the specified directories exists. This directory is then output and the function ends with the return value 0. If none of the passed directories exist, the function ends with the return value 1.
Takes a list of directories as a parameter and then checks in the specified sequence until one of the specified directories exists. This directory is then output and the function ends with the return value 0. If none of the directories passed exist, the doFail function is called with a corresponding message.
Checks whether the directory passed as a parameter is empty. If the directory is empty, the return value is 0, otherwise 1.
Checks whether the directory that is passed to it as a parameter corresponds to the directory target, eclipse-target, node_modules, .git, or .svn and returns the return code 0 otherwise 255.
Checks whether the file extension of the file specified in the parameter is an executable file, i.e. .exe .msi .pkg or .bat. If so, the function returns 0, otherwise 255.
Determines whether the actual version is contained in the security file for the corresponding tool and print out a message if so.
Determines the latest available version of software and returns it. If a prefix is given, it will be taken into account.
Determines the latest stable available version of software and returns it. If a prefix is given, it will be taken into account.
A version number is passed to the function doGetNextVersion as an argument and the next version number is generated from this by incrementing the last digit by one and outputs it.
Determines the currently in the environment configured edition of a software and returns it.
Determines the currently installed version of a software and prints it out for the end-user.
Param |
Name |
Description |
|
software |
The software tool to check (e.g. |
|
version_cmd |
The command to determine the version via the software. Maybe |
|
commandlet |
The commandlet corresponding to the software. Typically the same as |
Checks whether one of the two values "dev-SNAPSHOT" or "0-SNAPSHOT" was passed to it as a parameter.
If this is the case, it ends with the return value 0 otherwise 1.
Takes the name of the tool as a parameter and displays the available versions.
Used to set a specific version of a software tool, and requires 2 parameters: the name of the software tool and the desired version.
The version is saved as «tool»_VERSION variable in settings/devon.properties.
Runs the configurator using doRunConfigurator to configure a workspace.
Creates a launch script for the IDE given as first argument (e.g. eclipse) and the configured workspace ($WORKSPACE).
Calls maven to generate archetype (project template) for the given parameters.
Uses $ARCHETYPE_GROUP_ID and $ARCHETYPE_ARTIFACT_ID that default to devon4j template.
The doMavenGetLatestVersion function looks in the artifact repository specified in the (url) parameter for the latest version of the software stored there.
The function doUpgradeMavenArtifact first looks in the target directory to see if it is a git repository and then carries out a doGitPullOrClone if necessary and then terminates the function. If the target directory is not a git repository and LATEST was specified as the fourth parameter for the target version, then the latest target version of the Maven artifact (parameter 3) is determined under the url (parameter 2). Now the current version (parameter 6) is compared with the desired target version, and if it is the same or if the current version is greater than the target version, the function aborts with a corresponding message. If the target version is larger than the current version, the software is installed in the target version in the target directory (parameter 1).
An array is defined from a number of elements, with the last element being defined as a prefix. The function doArrayContainsItemWithPrefix now checks the array if it contains elements that start with this prefix. 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.
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.
Creates a sha256 checksum for a file and compares it to the given checksum
-
is one of the options -b, -f, -d or -q and accordingly sets the associated variable batch, force, debug or quiet and terminates the function with the return value 0.
-
is the option version. In this case, it does the handling to
list,get, orsetthe version and exits the program.
If — is passed, a variable is set that prevents further calls of this function and ends with the return value 0. If none of these options are passed, the return value is 255.