/****************************************************************************
**
** Copyright (C) 2023 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Installer Framework.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \previouspage scripting.html
    \page operations.html
    \nextpage ifw-tools.html

    \title 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 \e DO step that contains instructions for
    the installer and an \e UNDO step that contains instructions for the
    uninstaller.

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

    \section1 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:
    \code
    <Operations>
      <Operation name="operation">
        <Argument>argument1</Argument>
        <Argument>argument2</Argument>
      </Operation>
    </Operations>
    \endcode
    \note The argument order in component.xml is the same as in scripting, except for
    \c Extract operation where the argument \c archive is optional, and must be defined
    as the last argument.

    \table
        \header
            \li Operation
            \li Syntax
            \li Use
        \row
            \li Copy
            \li "Copy" \c source \c target
            \li Copies a file from \c source to \c target.
            \note The file will be restored during unistallation. If you want
                to skip the copying, you can overwrite the \e UNDO by passing
                \e UNDOOPERATION and \e "", to the end of the argument list.
        \row
            \li Move
            \li "Move" \c source \c target
            \li Moves a file from \c source to \c target.
            \note Files restored during uninstallation. If you want to move the
            files persistently, you can overwrite the \e UNDO by passing \e
            UNDOOPERATION and \e "", to the end of the argument list.
        \row
            \li SimpleMoveFile
            \li "SimpleMoveFile" \c source \c target
            \li Moves a file from \c source to \c target.

            \note Files will be moved from \c target to \c source during uninstallation.
            If you want to move the files persistently, you can overwrite the \e UNDO
            by passing \e UNDOOPERATION and \e "", to the end of the argument list.
        \row
            \li Delete
            \li "Delete" \c filename
            \li Deletes the file specified by \c filename.
            \note File will be restored during uninstallation. If you want to
            delete the files persistently, you can overwrite the \e UNDO by
            passing \e UNDOOPERATION and \e "", to the end of the argument list.
        \row
            \li Mkdir
            \li "Mkdir" \c path
            \li Creates the directory path \c path.
            \note Directory will be deleted during uninstallation.
            If you want to create the directory persistently, you can overwrite the \e UNDO
            by passing \e UNDOOPERATION and \e "", to the end of the argument list. Note that
            during full uninstall, directory will be deleted if it was created to target directory
            and \c RemoveTargetDir is false.
        \row
            \li Rmdir
            \li "Rmdir" \c path
            \li Removes the directory path \c path.
            \note Directory will be recreated during uninstallation.
            If you want to remove the directory persistently, you can overwrite the \e UNDO
            by passing \e UNDOOPERATION and \e "", to the end of the argument list.
        \row
            \li CopyDirectory
            \li "CopyDirectory" \c sourcePath \c targetPath
            \li Copies a directory from \c sourcePath to \c targetPath.
            \note Directories will be reset during uninstallation. If you want to copy the
                directory persistently, you can overwrite the \e UNDO by passing \e UNDOOPERATION
                and \e "", to the end of the argument list.
        \row
            \li AppendFile
            \li "AppendFile" \c filename \c text
            \li Appends \c text to the file specified by \c filename. \c 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 \e UNDO by passing \e UNDOOPERATION
                and \e "", to the end of the argument list.
        \row
            \li PrependFile
            \li "PrependFile" \c filename \c text
            \li Prepends \c text to the file specified by \c filename. \c 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 \e UNDO by passing \e UNDOOPERATION
                and \e "", to the end of the argument list.
        \row
            \li Replace
            \li "Replace" \c file \c search \c replace \c mode
            \li Opens \c file to find \c search string and replaces that with the \c replace string,
                using \c mode that can be either \c string or \c regex. For regular expressions
                containing capturing groups, occurrences of \c \1, \c \2, ..., in \c replace are
                replaced with the string captured by the corresponding capturing group.

                Note that testing the operation using \c devtool does not support commas inside the
                \c search pattern as they are used as argument separators. When using \c regex mode you
                should also ensure the \c search pattern adheres to \c QRegularExpression class
                documentation, particularly to the escaping rules for characters.
        \row
            \li LineReplace
            \li "LineReplace" \c file \c search \c replace
            \li Opens \c file to find lines that start with \c search string and
                replaces that with the \c replace string. Lines are trimmed before
                the search.
        \row
            \li Execute
            \li "Execute" [{\c exitcodes}] \c command [\c parameter1 [\c parameter... [\c parameter10]]]
            \li Executes the command specified by \c 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:
                \c{component.addOperation("Execute", "touch", "test.txt", "UNDOEXECUTE", "rm", "test.txt")}
        \row
            \li CreateShortcut
            \li "CreateShortcut" \c filename \c linkname [\c arguments]
            \li Creates a shortcut from the file specified by \c filename to
                \c linkname.
                On Windows, this creates a .lnk file which can have
                \c arguments. Furthermore, \c filename can be
                an HTTP, HTTPS or FTP URL in which case a URL shortcut is created.
                \note If the \c @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.
        \row
            \li CreateDesktopEntry
            \li "CreateDesktopEntry" \c {filename "key=value[ key2=value2[ key3=value3]]]"}
            \li Creates a .desktop initialization file, as specified by
                freedesktop.org. This operation is useful only on X11 or
                Wayland based Linux distributions.

                If \c filename is absolute, the desktop entry is stored there.
                Otherwise, it is stored in the location specified in
                \c{$XDG_DATA_HOME/applications}, including the default path,
                as defined by freedesktop.org. For system-wide installations,
                it is stored in \c {/usr/local/share/applications} instead.

                The key-value pairs are written to the file.

                The file is set to use UTF-8 encoding.
        \row
            \li InstallIcons
            \li "InstallIcons" \c directory \c [Vendorprefix]
            \li Installs the contents of \c directory into a location, as
                specified by freedesktop.org. That is, into
                \c {$XDG_DATA_HOME/icons}, \c {$HOME/.local/share/icons} or
                \c {/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 \c Vendorprefix it replaces all characters up to the
                first dash (-) in the filename of the icon with this prefix.
        \row
            \li Extract
            \li "Extract" \c archive \c targetdirectory
            \li Extracts \c archive to \c targetdirectory.
                Extract operations are called before other operations. Note that in component.xml
                argument \c archive is optional and thus must be defined as the last parameter.

        \row
            \li GlobalConfig
            \li "GlobalConfig" \c company \c application \c key \c value

                or

                "GlobalConfig" \c scope \c company \c application \c key \c value

                or

                "GlobalConfig" \c filename \c key \c value
            \li Stores \c value for \c key in a configuration file. The
                configuration file is specified either by \c filename
                (using \c QSettings::NativeFormat, which might be the Windows
                registry) or by \c application and \c company name. Set \c 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 \e UNDO by passing \e UNDOOPERATION and
                \e "", 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.
        \row
            \li EnvironmentVariable
            \li "EnvironmentVariable" \c key \c value [\c persistent [\c system]]
            \li Sets the environment variable \c key to \c value. If
                \c persistent is set to \c true, the variable is set
                persistently. This is currently only supported on Windows.
                If \c system is set to \c 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.
        \row
            \li RegisterFileType
            \li "RegisterFileType" \c extension \c command [\c description [\c contentType [\c icon]]].
            \li Registers the file type with \c extension to be opened via
                \c command. Optionally, you can specify \c description,
                \c contentType, and \c 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 \e UNDO by passing \e UNDOOPERATION
                and \e "", to the end of the argument list.
        \row
            \li ConsumeOutput
            \li "ConsumeOutput" \c installerKeyName \c executablePath \c processArguments
            \li Saves the output from running the executable located at
                \c executablePath with the arguments \c processArguments to the
                installer key specified by \c installerKeyName. Additional
                arguments can be passed.
        \row
            \li CreateLink
            \li "CreateLink" \c linkPath \c targetPath
            \li Creates a link in the location specified by \c linkPath that
                points to the location specified by \c targetPath.
        \row
            \li CreateLocalRepository
            \li "CreateLocalRepository" \c binaryPath \c repoPath
            \li Creates a local repository in the directory specified by
                \c repoPath. For offline installers, stores binary data in the
                directory specified by \c binaryPath.
                \note The repository will be deleted during uninstallation. If you want keep
                the repository, you can overwrite the \e UNDO by passing \e UNDOOPERATION
                and \e "", to the end of the argument list.
        \row
            \li FakeStopProcessForUpdate
            \li "FakeStopProcessForUpdate" \c processlist
            \li Matches running processes against the comma-separated entries in \c processlist
                during uninstallation. If matches are found, shows a messagebox asking the user
                to stop those processes before continuing.
        \row
            \li License
            \li "License" \c licenses
            \li Copies the license files specified by \c licenses to a subfolder called \c Licenses
                in the target directory. This operation is automatically added for packages
                declaring \c <Licenses> in their package description file.
        \row
            \li MinimumProgress
            \li "MinimumProgress"
            \li Increases the progress value by one.
        \row
            \li SelfRestart
            \li "SelfRestart" \c core
            \li Restarts the updater or package manager specified by \c core.
        \row
            \li Settings
            \li "Settings" \c path \c method \c key \c value
            \li Sets or removes the \c value of \c key in the settings file located at
                \c path, depending on the value of \c method: \c set, \c remove,
                \c add_array_value, and \c remove_array_value.
                Example: \c{component.addOperation("Settings", "path=settings.ini", "method=add", "key=myKey", "value=myValue")}
    \endtable

    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 \c devtool. However,
    variables are not resolved, so you need to use absolute values.

    For example, to test copying a file:
    \code
    devtool operation <binary> DO,Copy,<source>,<target>
    \endcode

    \section1 Execution Groups

    The operations owned by a component belong to either of two groups: \e Unpack or \e Install.
    The \c Extract operations are performed as part of the \e 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 \e Install group and
    executed sequentially for each component at a time.

    Custom operations can define their execution group by calling the \c setGroup() method
    in their constructor. For more information about custom operations, see
    \l{Registering Custom Operations}.
*/
