mirror of
https://github.com/QuasarApp/installer-framework.git
synced 2025-04-28 22:44:32 +00:00
315 lines
11 KiB
Plaintext
315 lines
11 KiB
Plaintext
/*!
|
||
\contentspage{index.html}{InstallerFramework}
|
||
\page scripting.html
|
||
|
||
\title Component Scripting
|
||
|
||
\section1 Scripting abilities inside of components
|
||
|
||
Each component can specify one script, which is loaded and run by the
|
||
installer. The format has to be compatible to QScriptEngine.
|
||
|
||
\section1 Contruction
|
||
|
||
The script has to provide an object Component, which will be created by the
|
||
Installer when loading the script. Therefore the script must contains at
|
||
least a function Component(), which can do all the initialization needed,
|
||
like putting user interfaces in place or connecting signals/slots:
|
||
|
||
\code
|
||
function Component()
|
||
{
|
||
// let's assume we have a user interface ErrorPage - which should not be complete
|
||
installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
|
||
component.userInterface( "ErrorPage" ).complete = false;
|
||
}
|
||
\endcode
|
||
|
||
The example above places the user interface "ErrorPage" (which is the class
|
||
name of the ui file loaded from errorpage.ui) in front of the installer
|
||
page "Ready for Installation" and sets his completeness to false. See the
|
||
documentation for addWizardPage and userInterface for details.
|
||
|
||
\section1 Installer Hooks
|
||
|
||
You can add several hook methods into your script:
|
||
|
||
\list
|
||
\o \bold{Component.prototype.retranslateUi} is called, whenever the language of the Installer changes.
|
||
\o \bold{Component.prototype.createOperations} - see QInstaller::Component::createOperations
|
||
\o \bold{Component.prototype.createOperationsForArchive} - see QInstaller::Component::createOperationsForArchive
|
||
\o \bold{Component.prototype.createOperationsForPath} - see QInstaller::Component::createOperationsForPath
|
||
\endlist
|
||
|
||
\section1 Global variables
|
||
|
||
The Installer puts the following symbols into the scripts space:
|
||
|
||
\list
|
||
\o \bold{installer} A reference to the component's Installer
|
||
\o \bold{component} A reference to the component's Component
|
||
\endlist
|
||
|
||
All methods marked with \a Q_INVOKABLE as well as all signals, slots and
|
||
properties can be used by the script.
|
||
|
||
\section1 Message boxes
|
||
|
||
You can show a QMessageBox from within the script by using:
|
||
|
||
\code
|
||
QMessageBox.critical
|
||
QMessageBox.information
|
||
QMessageBox.question
|
||
QMessageBox.warning
|
||
\endcode
|
||
|
||
For your convenience, the values for QMessageBox::StandardButton are made
|
||
available by using QMessageBox.Ok, QMessageBox.Open, ...
|
||
|
||
\section1 Adding operations to the component
|
||
|
||
In certain situations if it very useful to add custom operations after
|
||
extracting the content. Those include copying files as well as patching
|
||
content of files, etc.
|
||
Update operations can be created and added to the installation from within
|
||
a script using QInstaller::Component::addOperation.
|
||
Every operation has an unique key used for identification and up to five
|
||
parameters. Inside of the parameters, you can use variables as set in
|
||
QInstaller::Installer::setValue. See the list of
|
||
\l{Predefined variables}{predefined variables}.
|
||
|
||
Following a list of all available operations, which
|
||
can be added to a installation script.
|
||
|
||
\section2 Copy
|
||
|
||
\bold Syntax: "Copy" \a source \a target
|
||
|
||
Copies a file from \a source to \a target.
|
||
|
||
|
||
\section2 Move
|
||
|
||
\bold Syntax: "Move" \a source \a target
|
||
|
||
Moves a file from \a source to \a target.
|
||
|
||
|
||
\section2 Delete
|
||
|
||
\bold Syntax: "Delete" \a filename
|
||
|
||
Deletes the file specified by \a filename.
|
||
|
||
|
||
\section2 Mkdir
|
||
|
||
\bold Syntax: "Mkdir" \a path
|
||
|
||
Creates the directory path \a path.
|
||
|
||
|
||
\section2 Rmdir
|
||
|
||
\bold Syntax: "Rmdir" \a path
|
||
|
||
Removes the directory path \a path.
|
||
|
||
|
||
\section2 AppendFile
|
||
|
||
\bold Syntax: "AppendFile" \a filename \a text
|
||
|
||
Appends \a text to the file specified by \a filename. \a is threated as ASCII text.
|
||
|
||
|
||
\section2 PrependFile
|
||
|
||
\bold Syntax: "PrependFile" \a filename \a text
|
||
|
||
Prepends \a text to the file specified by \a filename. \a is threated as ASCII text.
|
||
|
||
|
||
\section2 Execute
|
||
|
||
\bold Syntax: "Execute" [{\a exitcodes}] \a command [\a parameter1 [\a parameter2 [\a parameter3 [\a parameter4]]]]
|
||
|
||
Executes the command specified by \a command. Up to four parameters can be passed.
|
||
|
||
Optionally, you can pass a comma separated list of numbers in {} as first argument, which defines the "valid" exit codes
|
||
of the process, i.e. the codes the execution is considered being successful. This defaults to "{0}".
|
||
|
||
\section2 CreateShortcut
|
||
|
||
\bold Syntax: "CreateShortcut" \a filename \a linkname [\a arguments]
|
||
|
||
Creates a shortcut from the file specified by \a filename to \a linkname.
|
||
On Windows, this will create a .lnk file which can have \a arguments, on Unix this will create a symobic link.
|
||
|
||
|
||
\section2 CreateDesktopEntry
|
||
|
||
\bold Syntax: "CreateDesktopEntry" \a filename \a "key=value[\nkey2=value2[\nkey3=value3]]]"
|
||
|
||
Creates an INI-file like .desktop file as specified by freedesktop.org
|
||
If \a filename is absolute, the desktop entry is stored there. Otherwise it's stored in locations defined in $XDG_DATA_DIRS/applications
|
||
or $XDG_DATA_HOME/applications, including the default pathes for boths, as defined by freedesktop.org.
|
||
|
||
The key/value pairs are written in the file.
|
||
|
||
The file is set to a encoding of UTF-8.
|
||
|
||
\section2 InstallIcons
|
||
|
||
\bold Syntax: "InstallIcons" \a directory
|
||
|
||
Installs the contents of \a directory into a location as specified by freedesktop.org, i.e. in any of $XDG_DATA_DIRS/icons or /usr/share/icons
|
||
or $HOME/.icons. The files are removed from their initial location. Make sure to add this operation after the operation extracting them form the archive.
|
||
|
||
\section2 Extract
|
||
|
||
\bold Syntax: "Extract" \a archive \a targetdirectory
|
||
|
||
Extracts \a archive to \a targetdirectory
|
||
|
||
|
||
\section2 GlobalConfig
|
||
|
||
\bold Syntax: "GlobalConfig" \a company \a application \a key \a value <br>
|
||
\a or <br>
|
||
\bold Syntax: "GlobalConfig" \a filename \a key \a value
|
||
|
||
Stores \a value for \a key in a configuration file. The configuration file is either
|
||
specified by \a filename (using QSettings::NativeFormat, which might be the Windows registry)
|
||
or via the \a application and the \a company name.
|
||
|
||
|
||
\section2 EnvironmentVariable
|
||
|
||
\bold Syntax: "EnvironmentVariable" \a key \a value [[\a persistent] \a system]
|
||
|
||
Sets the envirnoment variable \a key to a \a value. If \a persistent is set to true, the variable
|
||
will be set persistently. This is currently only supported on Windows. If \a system is set to true, the
|
||
persistent variable will be set system wide, not only for the current user.
|
||
|
||
|
||
\section2 RegisterFileType
|
||
|
||
\bold Syntax: "RegisterFileType" \a extension \a command [\a description [\a contentType [\a icon]]].
|
||
|
||
Registers the file type with \a extension to be opened via \a command. Optionally, you can specify
|
||
a \a description, a \a contentType and an \a icon. This is currently only supported on Windows.
|
||
|
||
|
||
\section2 RegisterQtInCreatorV2
|
||
|
||
\bold Syntax: "RegisterQtInCreatorV2", \a displayname, \a qt_or_qmake_path, [\a system_root, [\a sbs_path]].
|
||
|
||
Registers the Qt version \a displayname to Qt Creator with \a qt_or_qmake_path (if<69>the<68>path<74>does not<6F>end<6E>with<74>the qmake binary,<2C>it<69>will<6C>add<64>bin/qmake<6B>to<74>the<68>path<74>automatically). Optionally,<2C>you<6F>can<61>specify<66>a\<5C>system_root<6F>which.<2E>For<6F>Symbian<61>SDKs the instance<63>root<6F>will be where Qt Creator will find the Symbian SDK root (EPOCROOT). <20>For Symbian SDKs supporting sbs, you add<64>the<68>\a<>sbs_path .
|
||
|
||
\note The minimum Qt Creator version it supports is 2.2
|
||
|
||
|
||
\section1 Custom Operations
|
||
|
||
It is possible to register custom installation operations in the Installer. This works by deriving KDUpdater::UpdateOperation.
|
||
See the following code to know which methods must be implemented:
|
||
|
||
\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:
|
||
\code
|
||
#include <KDupdater/UpdateOperationFactory>
|
||
|
||
KDUpdater::UpdateOperationFactory::instance().registerUpdateOperation< CustomOperation >( "CustomOperation" );
|
||
\endcode
|
||
|
||
Now you can use your operation in the installer like every other of the predefined operations.
|
||
|
||
\section1 Predefined variables
|
||
|
||
Inside scripts you can use predefined variables to ease directory access. Those variables are
|
||
|
||
\list
|
||
\o \bold ProductName The name of the product to be installed as defined in config.xml
|
||
\o \bold ProductVersion The version of the product to be installed as defined in config.xml
|
||
\o \bold Title The title of the installation program as defined in config.xml
|
||
\o \bold Publisher The publisher of the installation program as defined in config.xml
|
||
\o \bold Url Product URL as defined in config.xml
|
||
\o \bold StartMenuDir Start menu group as defined in config.xml. Applies only to Microsoft Windows
|
||
\o \bold LicenseFile File name of the program license as defined in config.xml
|
||
\o \bold TargetDir Target directory for installation as selected by the user.
|
||
\o \bold DesktopDir Directory containing the user's desktop.
|
||
\o \bold os The current platform, might be "x11", "win" or "mac"
|
||
\endlist
|
||
|
||
\note You can use these variables inside of the parameter list for
|
||
installation operations. \a{"{TargetDir}/settings.xml"} might be expanded
|
||
to \a{"C:/Program Files/My Program/settings.xml"}.
|
||
*/
|