Operations

The operations are prepared by component and controller scripts or component.xml and performed by the installer.

Note: Operations are performed threaded.

Internally, each operation has a DO step that contains instructions for the installer and an UNDO step that contains instructions for the uninstaller.

Some operations especially in Windows might need native separators. Use installer.toNativeSeparators() to convert separators to ones that are appropriate for the underlying operating system.

Summary of Operations

The following table summarizes the available operations and their syntax in component and controller scripts. Syntax for operations in component.xml is:

<Operations>
  <Operation name="operation">
    <Argument>argument1</Argument>
    <Argument>argument2</Argument>
  </Operation>
</Operations>

Note: The argument order in component.xml is the same as in scripting, except for Extract operation where the argument archive is optional, and must be defined as the last argument.

Operation	Syntax	Use
Copy	"Copy" `source` `target`	Copies a file from `source` to `target`. Note: The file will be restored during unistallation. If you want to skip the copying, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
Move	"Move" `source` `target`	Moves a file from `source` to `target`. Note: Files restored during uninstallation. If you want to move the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
SimpleMoveFile	"SimpleMoveFile" `source` `target`	Moves a file from `source` to `target`. Note: Files will be moved from `target` to `source` during uninstallation. If you want to move the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
Delete	"Delete" `filename`	Deletes the file specified by `filename`. Note: File will be restored during uninstallation. If you want to delete the files persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
Mkdir	"Mkdir" `path`	Creates the directory path `path`. Note: Directory will be deleted during uninstallation. If you want to create the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. Note that during full uninstall, directory will be deleted if it was created to target directory and `RemoveTargetDir` is false.
Rmdir	"Rmdir" `path`	Removes the directory path `path`. Note: Directory will be recreated during uninstallation. If you want to remove the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
CopyDirectory	"CopyDirectory" `sourcePath` `targetPath`	Copies a directory from `sourcePath` to `targetPath`. Note: Directories will be reset during uninstallation. If you want to copy the directory persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
AppendFile	"AppendFile" `filename` `text`	Appends `text` to the file specified by `filename`. `text` is treated as ASCII text. Note: Text will be removed from file during unistallation. If you want to append the text persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
PrependFile	"PrependFile" `filename` `text`	Prepends `text` to the file specified by `filename`. `text` is treated as ASCII text. Note: Text will be removed from file during unistallation. If you want to append the text persistently, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
Replace	"Replace" `file` `search` `replace` `mode`	Opens `file` to find `search` string and replaces that with the `replace` string, using `mode` that can be either `string` or `regex`. For regular expressions containing capturing groups, occurrences of `\1`, `\2`, ..., in `replace` are replaced with the string captured by the corresponding capturing group. Note that testing the operation using `devtool` does not support commas inside the `search` pattern as they are used as argument separators. When using `regex` mode you should also ensure the `search` pattern adheres to `QRegularExpression` class documentation, particularly to the escaping rules for characters.
LineReplace	"LineReplace" `file` `search` `replace`	Opens `file` to find lines that start with `search` string and replaces that with the `replace` string. Lines are trimmed before the search.
Execute	"Execute" [{`exitcodes`}] `command` [`parameter1` [`parameter...` [`parameter10`]]]	Executes the command specified by `command`. Up to 10 parameters can be passed. If that is not enough, you can use a JavaScript string array. Optionally, you can pass a comma-separated list of exit codes within curly brackets ({}) as the first argument to specify the exit codes for successful execution. This defaults to "{0}". Other optional named arguments are: "workingdirectory=<your_working_dir>"; "errormessage=<your_custom_errormessage>" In addition, a special argument, UNDOEXECUTE, separates the DO step of the operation from the UNDO step. Example: `component.addOperation("Execute", "touch", "test.txt", "UNDOEXECUTE", "rm", "test.txt")`
CreateShortcut	"CreateShortcut" `filename` `linkname` [`arguments`]	Creates a shortcut from the file specified by `filename` to `linkname`. On Windows, this creates a .lnk file which can have `arguments`. Furthermore, `filename` can be an HTTP, HTTPS or FTP URL in which case a URL shortcut is created. Note: If the `@AllUsersStartMenuProgramsPath@` is used for placing the shortcut, then due to a problem on Windows, it will drop any arguments to the target and any description set. In this case, you should place the shortcut elsewhere and copy it to the location desired. Note: Creating a shortcut to a network share is not supported. The operation is currently not implemented on other platforms.
CreateDesktopEntry	"CreateDesktopEntry" `filename "key=value[ key2=value2[ key3=value3]]]"`	Creates a .desktop initialization file, as specified by freedesktop.org. This operation is useful only on X11 or Wayland based Linux distributions. If `filename` is absolute, the desktop entry is stored there. Otherwise, it is stored in the location specified in `$XDG_DATA_HOME/applications`, including the default path, as defined by freedesktop.org. For system-wide installations, it is stored in `/usr/local/share/applications` instead. The key-value pairs are written to the file. The file is set to use UTF-8 encoding.
InstallIcons	"InstallIcons" `directory` `[Vendorprefix]`	Installs the contents of `directory` into a location, as specified by freedesktop.org. That is, into `$XDG_DATA_HOME/icons`, `$HOME/.local/share/icons` or `/usr/local/share/icons`. The files are removed from their initial location. Make sure to add this operation after the operation that extracts the files from the archive. If you provide a `Vendorprefix` it replaces all characters up to the first dash (-) in the filename of the icon with this prefix.
Extract	"Extract" `archive` `targetdirectory`	Extracts `archive` to `targetdirectory`. Extract operations are called before other operations. Note that in component.xml argument `archive` is optional and thus must be defined as the last parameter.
GlobalConfig	"GlobalConfig" `company` `application` `key` `value` or "GlobalConfig" `scope` `company` `application` `key` `value` or "GlobalConfig" `filename` `key` `value`	Stores `value` for `key` in a configuration file. The configuration file is specified either by `filename` (using `QSettings::NativeFormat`, which might be the Windows registry) or by `application` and `company` name. Set `scope` to "SystemScope" to create an entry in the system scope. Note: GlobalConfig will be reset during uninstallation. If you want to make the config persistent, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list. Note: The operation is using QSettings to store the key value pair. QSettings always treats backslash as a special character and provides no API for reading or writing such entries. Do not use slashes ('/' and '\') in section or key names; the backslash character is used to separate sub keys. On windows, '\' are converted by QSettings to '/', which makes them identical. Because the backslash character is used by QSettings to separate sub keys, you cannot read or write windows registry entries that contain slashes or backslashes. You should use a native windows API if you need to do so.
EnvironmentVariable	"EnvironmentVariable" `key` `value` [`persistent` [`system`]]	Sets the environment variable `key` to `value`. If `persistent` is set to `true`, the variable is set persistently. This is currently only supported on Windows. If `system` is set to `true`, the persistent variable is set system-wide, not only for the current user. Note, if you set path to environment variable, use '\' as separator, for example: @Targetdir@\lib\system.
RegisterFileType	"RegisterFileType" `extension` `command` [`description` [`contentType` [`icon`]]].	Registers the file type with `extension` to be opened via `command`. Optionally, you can specify `description`, `contentType`, and `icon`. This is currently only supported on Windows. Note: File type will be unregistered during uninstallation. If you want keep the type registered, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
ConsumeOutput	"ConsumeOutput" `installerKeyName` `executablePath` `processArguments`	Saves the output from running the executable located at `executablePath` with the arguments `processArguments` to the installer key specified by `installerKeyName`. Additional arguments can be passed.
CreateLink	"CreateLink" `linkPath` `targetPath`	Creates a link in the location specified by `linkPath` that points to the location specified by `targetPath`.
CreateLocalRepository	"CreateLocalRepository" `binaryPath` `repoPath`	Creates a local repository in the directory specified by `repoPath`. For offline installers, stores binary data in the directory specified by `binaryPath`. Note: The repository will be deleted during uninstallation. If you want keep the repository, you can overwrite the UNDO by passing UNDOOPERATION and "", to the end of the argument list.
FakeStopProcessForUpdate	"FakeStopProcessForUpdate" `processlist`	Matches running processes against the comma-separated entries in `processlist` during uninstallation. If matches are found, shows a messagebox asking the user to stop those processes before continuing.
License	"License" `licenses`	Copies the license files specified by `licenses` to a subfolder called `Licenses` in the target directory. This operation is automatically added for packages declaring `<Licenses>` in their package description file.
MinimumProgress	"MinimumProgress"	Increases the progress value by one.
SelfRestart	"SelfRestart" `core`	Restarts the updater or package manager specified by `core`.
Settings	"Settings" `path` `method` `key` `value`	Sets or removes the `value` of `key` in the settings file located at `path`, depending on the value of `method`: `set`, `remove`, `add_array_value`, and `remove_array_value`. Example: `component.addOperation("Settings", "path=settings.ini", "method=add", "key=myKey", "value=myValue")`

The Extract, License, and MinimumProgress operations are automatically added for matching components that do not overwrite the component::createOperations() method. See also component::autoCreateOperations.

If errors occur, you can test operations manually using the devtool. However, variables are not resolved, so you need to use absolute values.

For example, to test copying a file:

devtool operation <binary> DO,Copy,<source>,<target>

Execution Groups

The operations owned by a component belong to either of two groups: Unpack or Install. The Extract operations are performed as part of the Unpack group before all other operations and executed concurrently between all components that are going to be installed. The rest of the operations are performed in the Install group and executed sequentially for each component at a time.

Custom operations can define their execution group by calling the setGroup() method in their constructor. For more information about custom operations, see Registering Custom Operations.

Component Scripting Tools

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.