mirror of
https://github.com/QuasarApp/installer-framework.git
synced 2025-04-28 22:44:32 +00:00
98c4b02da6
Change-Id: I6f6fb88644722a6acf0d168cc481e854ff188b11 Reviewed-by: Niels Weber <niels.weber@digia.com>
297 lines
9.6 KiB
Plaintext
297 lines
9.6 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/legal
|
|
**
|
|
** 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 Digia. For licensing terms and
|
|
** conditions see http://qt.digia.com/licensing. For further information
|
|
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\contentspage{index.html}{Qt Installer Framework}
|
|
\previouspage noninteractive.html
|
|
\page scripting.html
|
|
\nextpage operations.html
|
|
|
|
\title Component Scripting
|
|
|
|
For each component, you can specify one script that prepares the operations
|
|
to be performed by the installer. The script format has to be
|
|
compatible with QJSEngine.
|
|
|
|
\section1 Construction
|
|
|
|
The script has to contain a \c Component object that the installer creates
|
|
when it loads the script. Therefore, the script must contain at
|
|
least the \c Component() function, which performs initialization, such as
|
|
putting pages in the correct places or connecting signals and slots.
|
|
|
|
The following code snippet places the \c ErrorPage (which is the class
|
|
name of the user interface file loaded from errorpage.ui) in front of the
|
|
ready for installation page and sets its completeness to \c false.
|
|
|
|
\code
|
|
function Component()
|
|
{
|
|
// Add a user interface file called ErrorPage, which should not be complete
|
|
installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
|
|
component.userInterface( "ErrorPage" ).complete = false;
|
|
}
|
|
\endcode
|
|
|
|
For more information, see the documentation for \l QInstaller::addWizardPage and
|
|
\l Component::userInterface.
|
|
|
|
\section1 Installer Hooks
|
|
|
|
You can add the following hook methods into your script:
|
|
|
|
\table
|
|
\header
|
|
\li Method
|
|
\li Description
|
|
\row
|
|
\li \c{Component.prototype.retranslateUi}
|
|
\li Called when the language of the installer changes.
|
|
\row
|
|
\li \c{Component.prototype.createOperations}
|
|
\li See \l Component::createOperations.
|
|
\row
|
|
\li \c{Component.prototype.createOperationsForArchive}
|
|
\li See \l Component::createOperationsForArchive.
|
|
\row
|
|
\li \c{Component.prototype.createOperationsForPath}
|
|
\li See \l Component::createOperationsForPath.
|
|
\endtable
|
|
|
|
\section1 Global Variables
|
|
|
|
The installer puts the following symbols into the script space:
|
|
|
|
\table
|
|
\header
|
|
\li Symbol
|
|
\li Description
|
|
\row
|
|
\li installer
|
|
\li Reference to the \l QInstaller of the component
|
|
\row
|
|
\li component
|
|
\li Reference to the \l Component of the component
|
|
\endtable
|
|
|
|
\section1 Message Boxes
|
|
|
|
You can show a QMessageBox from within the script by using the following
|
|
static members:
|
|
|
|
\list
|
|
\li QMessageBox::critical()
|
|
\li QMessageBox::information()
|
|
\li QMessageBox::question()
|
|
\li QMessageBox::warning()
|
|
\endlist
|
|
|
|
For your convenience, the values for QMessageBox::StandardButton are made
|
|
available by using \c QMessageBox.Ok, \c QMessageBox.Open, and so on.
|
|
|
|
\section1 Adding Operations to Components
|
|
|
|
You might want to add custom operations after extracting the content, when
|
|
copying files or patching file content, for example. You can create and add
|
|
update operations to the installation from within
|
|
a script using \c QInstaller::Component::addOperation.
|
|
If you need to run an operation that requires administrative rights, use
|
|
\c QInstaller::Component::addElevatedOperation instead.
|
|
|
|
Each operation has a unique key used for identification and can take up to
|
|
five parameters. In the parameter values, you can use variables as set in
|
|
\c QInstaller::Installer::setValue. For more information, see
|
|
\l{Predefined Variables}.
|
|
|
|
For a summary of all available operations, see \l{Operations}.
|
|
|
|
\section1 Registering Custom Operations
|
|
|
|
You can register custom installation operations in the installer by deriving
|
|
\c KDUpdater::UpdateOperation. The following code displays the methods that
|
|
you must implement:
|
|
|
|
\code
|
|
#include <KDUpdater/UpdateOperation>
|
|
|
|
class CustomOperation : public KDUpdater::UpdateOperation
|
|
{
|
|
public:
|
|
CustomOperation()
|
|
{
|
|
setName( "CustomOperation" );
|
|
}
|
|
|
|
void backup()
|
|
{
|
|
// do whatever is needed to restore the state in undoOperation()
|
|
}
|
|
|
|
bool performOperation()
|
|
{
|
|
const QStringList args = arguments();
|
|
// do whatever is needed to do for the given arguments
|
|
|
|
bool success = ...;
|
|
return success;
|
|
}
|
|
|
|
void undoOperation()
|
|
{
|
|
// restore the previous state, as saved in backup()
|
|
}
|
|
|
|
bool testOperation()
|
|
{
|
|
// currently unused
|
|
return true;
|
|
}
|
|
|
|
CustomOperation* clone() const
|
|
{
|
|
return new CustomOperation;
|
|
}
|
|
|
|
QDomDocument toXml()
|
|
{
|
|
// automatically adds the operation's arguments and everything set via setValue
|
|
QDomDocument doc = KDUpdater::UpdateOperation::toXml();
|
|
|
|
// if you need any information to undo the operation you did,
|
|
// add them to the doc here
|
|
|
|
return doc;
|
|
}
|
|
|
|
bool fromXml( const QDomDocument& doc )
|
|
{
|
|
// automatically loads the operation's arguments and everything set via setValue
|
|
if( !KDUpdater::UpdateOperation::fromXml( doc ) )
|
|
return false;
|
|
|
|
// if you need any information to undo the operation you did,
|
|
// read them from the doc here
|
|
|
|
return true;
|
|
}
|
|
};
|
|
\endcode
|
|
|
|
Finally, you need to register your custom operation class, as follows:
|
|
\code
|
|
#include <KDupdater/UpdateOperationFactory>
|
|
|
|
KDUpdater::UpdateOperationFactory::instance().registerUpdateOperation< CustomOperation >( "CustomOperation" );
|
|
\endcode
|
|
|
|
Now you can use your operation in the installer in the same way as the
|
|
predefined operations.
|
|
|
|
\section1 Predefined Variables
|
|
|
|
You can use the following predefined variables in scripts to facilitate
|
|
directory access:
|
|
|
|
\table
|
|
\header
|
|
\li Symbol
|
|
\li Description
|
|
\row
|
|
\li ProductName
|
|
\li Name of the product to be installed, as defined in config.xml.
|
|
\row
|
|
\li ProductVersion
|
|
\li Version number of the product to be installed, as defined in
|
|
config.xml.
|
|
\row
|
|
\li Title
|
|
\li Title of the installation program, as defined in config.xml.
|
|
\row
|
|
\li Publisher
|
|
\li Publisher of the installation program, as defined in config.xml.
|
|
\row
|
|
\li Url
|
|
\li Product URL, as defined in config.xml.
|
|
\row
|
|
\li StartMenuDir
|
|
\li Start menu group, as defined in config.xml. Only available on Windows.
|
|
\row
|
|
\li TargetDir
|
|
\li Target directory for installation, as selected by the user.
|
|
\row
|
|
\li DesktopDir
|
|
\li Name of the directory that contains the user's desktop.
|
|
|
|
Only available on Windows.
|
|
\row
|
|
\li os
|
|
\li Current platform: \c "x11", \c "win", or \c "mac".
|
|
\row
|
|
\li RootDir
|
|
\li Root directory of the filesystem.
|
|
\row
|
|
\li HomeDir
|
|
\li Home directory of the current user.
|
|
\row
|
|
\li ApplicationsDir
|
|
\li Applications directory.
|
|
|
|
For example, \c {C:\Program Files} on Windows,
|
|
\c {/opt} on Linux and \c {/Applications} on OS X.
|
|
\row
|
|
\li InstallerDirPath
|
|
\li The directory that contains the installer application executable.
|
|
\row
|
|
\li InstallerFilePath
|
|
\li The file path of the installer application executable.
|
|
\row
|
|
\li UserStartMenuProgramsPath
|
|
\li The path to the folder containing the items in the Start menu of the user.
|
|
|
|
For example, \c {C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs}
|
|
|
|
Only available on Windows.
|
|
\row
|
|
\li AllUsersStartMenuProgramsPath
|
|
\li The path to the folder containing the items in the Start menu for all users.
|
|
|
|
For example, \c {C:\ProgramData\Microsoft\Windows\Start Menu\Programs}
|
|
|
|
Only available on Windows.
|
|
\endtable
|
|
|
|
The variables can be resolved by calls to \c installer.value(). If embedded
|
|
in '@' they can also be part of strings passed as arguments to installation
|
|
operations:
|
|
|
|
\code
|
|
if (installer.value("os") === "win") {
|
|
component.addOperation("CreateShortcut", "@TargetDir@/MyApp.exe", "@StartMenuDir@/MyApp.lnk");
|
|
}
|
|
\endcode
|
|
*/
|