Configuration Classes

distbuilder logo

The following classes are used to create objects which are employed as arguments to various functions within the library. Many of these can be generated for you using the Configuration Factory.

PyInstallerConfig

Objects of this type define optional details for building binaries from .py scripts using the PyInstaller utility invoked via the pyScriptToExe function (which maybe employed by higher level
Process Classes under the hood).

Note that if a PyInstSpec attribute is provided for one of these objects, the build settings contained within that will override any which conflict with those specified via the attributes set directly on the PyInstallerConfig object. PyInstSpec objects may be created by supplying a traditional (perhaps legacy) spec file definition, or you may wish to generate one with distbuilder via the makePyInstSpec() function.
In either case, you may also opt to dynamically manipulate the spec via the implementation of that class.

Constructor:

PyInstallerConfig()

Attributes & default values:

pyInstallerPath = <python scripts directory>/pyinstaller

name            = None   
entryPointPy    = None

pyInstSpec      = None

isGui           = False
iconFilePath    = None

versionInfo     = None
versionFilePath = None

isAutoElevated  = False

isOneFile       = True     (note this differs from PyInstaller default)

importPaths     = []
hiddenImports   = []

dataFilePaths   = []
binaryFilePaths = []

distResources   = []
distDirs        = []

codeSignConfig  = []
codeSignTargets = []

otherPyInstArgs = ""  (open ended argument string)

distDirPath     = None

_pngIconResPath = None
isSpecFileRemoved = False

PyInstHook

Objects of this type are used for PyInstaller "hook" script creation, and programmatic manipulation. Such hooks are executed during a PyInstaller analyis process when an import is encountered with a matching hook name. The purpose of a hook is to help PyInstaller find and collect resources it would otherwise not know to include in the bundle.

Hooks are commonly installed by third party libraries for use across your Python environment whenever you employ PyInstaller. It is also possible to use custom hooks during a given a build process via the PyInstaller option --additional-hooks-dir (though that parameter does not override a hook which is registered for the system on the whole...)

If you are working in a context in which you can manipulate the build environment freely, the use of hooks is arguably a better means by which to gather resources for a distribition rather than by adding them through
PyInstallerConfig attributes hiddenImports, dataFilePaths, binaryFilePaths, etc.

Use cases for this class include: adding hooks to patch a build process, replacing bad hooks installed on your system, or to simply revisw them for some additional custom need.

For more on hooks, see: Understanding PyInstaller Hooks

Constructor:

PyInstHook( name, script=None,
            isContribHook=True, isRunTimeHook=False )

Attributes & default values:

name          = *required     
script        = None

isContribHook = True
isRunTimeHook = False

hooksDirPath  = None

Object Methods:

fileName()

read()
write()
remove()

debug()

toLines()
fromLines( lines )
injectLine( injection, lineNo )

Details:

The name attribute should simply specify the name of import which invokes the script. The name should not contain the literal "hook-" file name prefix, or a .py file extension.

isContribHook: Only respected for PyInstaller v4 or later, when it became available, and the new standard practice for hook distribution.

hooksDirPath may be override, as needed. If left as the default None, the path will be automatically resolved.

PyInstSpec

Objects of this type are used for PyInstaller spec file parsing, and programmatic manipulation. This class provides an easy mechanism for applying known PyInstaller patches, as well as convenient mechanisms for applying custom revisions for similar purposes.

Constructor:

PyInstSpec( filePath=None, pyInstConfig=None, content=None )

Attributes & default values:

filePath     = None
pyInstConfig = None 
content      = None

warningBehavior   = None 
    <options: PyInstSpec.WARN_IGNORE, PyInstSpec.WARN_ONCE, PyInstSpec.WARN_ERROR>    
isUnBufferedStdIo = False
isModInitDebug    = False

isInjected   = False

Static Method:

cfgToPath( pyInstConfig )

Object Methods:

path()

read()
write()

debug()

toLines()
fromLines( lines )
injectLine( injection, lineNo )

injectDuplicateDataPatch()

_parseAssigments()

IExpressConfig

WINDOWS ONLY

Objects of this type define optional details for building binaries from native Windows scripts (currently supporting Batch, PowerShell, VBScript, and JScript), using the IExpress utility built into the OS, as invoked via the batchScriptToExe, powerShellScriptToExe, vbScriptToExe, or jScriptToExe functions (which maybe employed by higher level
Process Classes under the hood).

Constructor:

IExpressConfig()

Attributes & default values:

name             = None
sourceDir        = None

entryPointScript = None
scriptHeader     = None
isScriptDebug    = False

versionInfo      = None
iconFilePath     = None
isAutoElevated   = False

scriptImports     = [] #Embedded
embeddedResources = [] #Embedded

distResources     = []  #External
distDirs          = []  #External (mkDir)

codeSignConfig    = []
codeSignTargets   = []

# result 
destDirPath      = None

isScriptDebug : TODO: Fill-in - Note the extended VbScript functionality

CodeSignConfig

This class defines the details used for code signing executables.

TODO: Make Cross Platform

Constructor:

CodeSignConfig( keyFilePath=None, keyPassword=None )

Attributes & default values:

keyFilePath = None
keyPassword = None

signToolPath = None <None==auto resolved>

fileDigest         = CodeSignConfig.DEFAULT_DIGEST       
timeStampDigest    = CodeSignConfig.DEFAULT_DIGEST 
timeStampServerUrl = CodeSignConfig.DEFAULT_TIMESTAMP_SERVER
otherSignToolArgs  = ""

isDebugMode = True

Class Constants:

DEFAULT_DIGEST           = "sha256"
DEFAULT_TIMESTAMP_SERVER = "http://timestamp.digicert.com"

signToolPath: Only applicable on WINDOWS. If None, this defaults to the path the this library will auto install the tool as needed. This attribute may also be set indirectly by running the script where an environmental variable call SIGNTOOL_PATH (defined the in constant SIGNTOOL_PATH_ENV_VAR) has been defined.

SelfSignedCertConfig

This class defines the details used for generating self-signed code signing certificates and keys.

TODO: Make Cross Platform

Constructor:

CodeSignConfig( companyTradeName, destDirPath=None )

Attributes & default values:

commonName  = companyTradeName
endDate     = SelfSignedCertConfig.DEFAULT_END_DATE

destDirPath = destDirPath or THIS_DIR

caCertPath     = <auto, based on destDirPath> 
privateKeyPath = <auto, based on destDirPath>

makeCertPath = None <None, auto resolved >

_maxCertChildren  = SelfSignedCertConfig.NO_MAX_CHILDREN       
_enhancedKeyUsage = SelfSignedCertConfig.LIFETIME_SIGNING_EKU

otherArgs         = ""
isDebugMode = True

Object Methods:

_forceMakeCertMethod()

Class Constants:

DEFAULT_END_DATE     = '12/31/2050'
NO_MAX_CHILDREN      = 0
LIFETIME_SIGNING_EKU = '1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13'

makeCertPath: Only applicable on WINDOWS. Normally used on legacy versions of Windows (v8.0 an earlier), where new standard means for creating such files - i.e. the PowerShell function New-SelfSignedCertificate is not available. If None, this defaults to the path where this library will auto install the tool as needed. This attribute may also be set indirectly by running the script where an environmental variable call MAKECERT_PATH (defined the in constant MAKECERT_PATH_ENV_VAR) has been defined.

Pvk2PfxConfig

Used in legacy Windows mechanisms for creating code signing certificates. Specified defines the details for converting .pvk files (old style private keys) generated by the now defunct makecert utility, into .pfx files.

Constructor:

Pvk2PfxConfig( caCertPath, privateKeyPath, 
               keyPassword=None, pfxFilePath=None )

Attributes & default values:

caCertPath     = <required>        
privateKeyPath = <required>
keyPassword    = None  
keyFilePath    = <result - pfxFilePath or auto based on privateKeyPath>

pvk2PfxPath = None <None, auto resolved>

otherArgs  = ""
isDebugMode = True

pvk2PfxPath: If None, this defaults to the path the this library will auto install the tool as needed. This attribute may also be set indirectly by running the script where an environmental variable call PVK2PFX_PATH (defined the in constant PVK2PFX_PATH_ENV_VAR) has been defined.

WindowsExeVersionInfo

Objects of this type define meta data branded into Windows executables. This is the object type intended for PyInstallerConfig.versionInfo attributes.

Constructor:

WindowsExeVersionInfo()

Attributes & default values:

major = 0
minor = 0
micro = 0
build = 0
companyName = ""
productName = ""
description = ""
exeName     = ""

Static Methods:

defaultPath()

Object Methods:

version( isCommaDelim=False )    
copyright() 
internalName()

fileName()
write()
debug()

QtIfwConfig

Objects of this type provide the highest level definition of a QtIFW installer configuration to use for building an installer via the buildInstaller function (which maybe employed by higher level
Process Classes under the hood).

Constructor:

QtIfwConfig( installerDefDirPath=None,
             packages=None,
             configXml=None,
             controlScript=None, 
             setupExeName="setup" )

Attributes & default values:

installerDefDirPath = None

packages            = None <list of QtIfwPackages OR directory paths>
configXml           = None    
controlScript       = None

setupExeName        = "setup"

<other IFW command line options>
isDebugMode    = True
otherQtIfwArgs = ""

Functions:

addUiElements( uiElements, isOverWrite=True ) 
addLicense( licensePath, name="End User License Agreement" )

QtIfwConfigXml

Objects of this type define the contents of a QtIFW config.xml which will be dynamically generated when invoking the buildInstaller function.

The config.xml file represents the highest level definition of a QtIFW installer, containing information such as the product name and version. Most of the attributes in this class correspond directly to the name of the tags added to the xml file.
Attributes set to None values will not be written, otherwise they will be.

Constructor:

QtIfwConfigXml( name, version, publisher,
                iconFilePath=None, 
                controlScriptName=None,
                primaryContentExe=None, isPrimaryExeGui=True,
                primaryExeWrapper=None,
                companyTradeName=None,
                wizardStyle=None, 
                logoFilePath=None, bannerFilePath=None )

Attributes:

primaryContentExe (used indirectly w/ isGui)    
companyTradeName  (used indirectly)
iconFilePath      (used indirectly)    
logoFilePath      (used indirectly)
bannerFilePath    (used indirectly)

primaryExeWrapper

Name                     
Version                  
Publisher

<Windows / Mac>        
    InstallerApplicationIcon  (icon root name, i.e. omit extension)
<Linux>
    InstallerWindowIcon       (.png name, with extension)

Title                
TitleColor                (HTML color code, such as "#88FF33")

ControlScript

TargetDir                
StartMenuDir

RunProgram               
RunProgramDescription

WizardStyle              
WizardDefaultWidth           
WizardDefaultHeight      
Logo                     
Banner

ProductUrl

runProgramArgList  (used indirectly)

otherElements (open ended dictionary of key/value pairs to inject)

Functions:

setPrimaryContentExe( ifwPackage )
setDefaultVersion()
setDefaultTitle()    
setDefaultPaths()

addCustomTags( root )

write()

debug()
toPrettyXml()

exists()            
path()   
dirPath()

Static Constants:

DEFAULT_WIZARD_STYLE
WizardStyle.AERO     <Windows Default>  
WizardStyle.MAC      <MacOS Default>
WizardStyle.MODERN   <Linux Default>
WizardStyle.CLASSIC  <Simliar to MODERN>

QtIfwControlScript

QtIfw installers may have a "Control Script" and/or a collection of "Package Scripts". The "Control Script" is intended to dictate how the installer interface behaves, and other high level logic pertaining to the installer itself. In contrast, "Package Scripts" are intended for applying custom logic to manipulate a target environment when installing a given package. See QtIfwPackageScript for more info.

The QtIfwControlScript class provides an abstraction layer for QtIfw script generation. QtIfw scripts are written in Qt Script (which is conceptually a spin off from JavaScript), with additional custom objects and methods for this context. Using this abstraction, you can achieve a great many custom behaviors without having to learn much about the language yourself. Refer to the details on Installer Scripting to learn more about the low level helpers provided by the library for this purpose.

For maximum flexibility, rather than using the dynamic methods, you may directly define the entire script via a raw string, by setting the script attribute. Or, you may specify an external file as the source instead via script_path. In addition, you may always delegate scripts to a traditional QtIfw definition by using a higher level configuration QtIfwConfig to specify such.

The way this class works, in summary, is that you may provide an optional script as a raw string, or a path to script you wish to load directly. If specified, those resources act as a base, from which you may continue to add on to.

A QtIfw control script is "driven" by the builtin framework. When a given "event" occurs a "handler" function is invoked (if it has been defined). QtIfwControlScript object has a set of attributes related to each page and such event/handler pair in the framework. One is a boolean, controlling the "visibility" of the page. Setting that to False skips over that wizard page entirely. Another boolean is provided, dictating whether to auto generate the event handler using a set of fixed, built-in logic provided by distbuilder to add a notable amount of additional features to your installers "for free". The final attribute in this pattern is the body of the event handler (normally auto generated), which allows for an atomic replacement of that code.

When the write() function is invoked, the actual script file to be embedded in the installer is generated from the attributes. Prior to calling that, you may switch off the various auto generate options, and supply your own function definition from scratch.

If you wish to use the bulk of the "free" / standard add on logic, but then customize that the program flow should be to call _generate() first, which will define the function bodies using the auto generate options. Once that is done, you may disable select auto generates, and then directly add on to, or manipulate the event handling function bodies.

A large number of abstract, static "helper" functions have been provided which you may use to build your logic. Otherwise, you may certainly just add Qt Script snippets directly in the raw. See Installer Scripting.

The virtualArgs attribute is a dictionary, containing key/values which allows for hard coding Standard Installer Arguments into the installer, which are typically passed at runtime via the command line.

Constructor:

QtIfwControlScript( fileName="installscript.qs",                  
                    script=None, scriptPath=None,
                    virtualArgs={} ) :

Attributes & default values:

isLimitedMaintenance = True
virtualArgs = virtualArgs

uiPages = []
widgets = []

controllerGlobals = None
isAutoGlobals = True

controllerConstructorBody = None
controllerConstructorInjection = None
isAutoControllerConstructor = True

onPageChangeCallbackBody      = None
onPageChangeCallbackInjection = None
isAutoPageChangeCallBack      = True

onFinishedClickedCallbackBody      = None
onFinishedClickedCallbackInjection = None
isAutoFinishedClickedCallbackBody  = True

onPageInsertRequestCallbackBody = None
isAutoPageInsertRequestCallBack = True

onPageRemoveRequestCallbackBody = None
isAutoPageRemoveRequestCallBack = True

onPageVisibilityRequestCallbackBody = None
isAutoPageVisibilityRequestCallBack = True

onValueChangeCallbackBody      = None
onValueChangeCallbackInjection = None
isAutoValueChangeCallBack      = True

isIntroductionPageVisible = True                                                                                                                                
introductionPageCallbackBody = None
introductionPageOnInstall = None
introductionPageOnMaintain = None    
isAutoIntroductionPageCallback = True

isTargetDirectoryPageVisible = True
targetDirectoryPageCallbackBody = None
isAutoTargetDirectoryPageCallback = True

isComponentSelectionPageVisible = True
componentSelectionPageCallbackBody = None
componentSelectionPageInjection = None
isAutoComponentSelectionPageCallback = True

isLicenseAgreementPageVisible = True
licenseAgreementPageCallbackBody = None
isAutoLicenseAgreementPageCallback = True

isStartMenuDirectoryPageVisible = True
startMenuDirectoryPageCallbackBody = None
isAutoStartMenuDirectoryPageCallback = True

isReadyForInstallationPageVisible = True
readyForInstallationPageCallbackBody = None
readyForInstallationPageOnInstall = None
readyForInstallationPageOnMaintain = None            
isAutoReadyForInstallationPageCallback = True

isPerformInstallationPageVisible = True
performInstallationPageCallbackBody = None
isAutoPerformInstallationPageCallback = True

isFinishedPageVisible = True        
finishedPageCallbackBody = None
finishedPageOnInstall = None
finishedPageOnMaintain = None
isAutoFinishedPageCallback = True

isRunProgVisible = True
isRunProgEnabled = True
isRunProgChecked = True

Object Methods:

registerAsyncFunc( func ) <takes QtIfwAsyncFunc>          
registerStandardEventHandler( signalName, slotName, slotBody )
registerAutoPilotEventHandler( signalName, slotName, slotBody )    
registerGuiEventHandler( signalName, slotName, slotBody )
registerWidgetEventHandler( pageId, controlName, 
                            signalName, slotName, slotBody )

_generate()

write()
debug()

exists()            
path()
dirPath()

QtIfwPackage

Objects of this type define the packages with an installer. A QtIfwConfig contains a list of these. Notably, these package objects define the source content to be included in the installer via srcDirPath or simply srcExePath attributes. They also contain QtIfwPackageXml and QtIfwPackageScript objects, for extended configuration details.

Constructor:

QtIfwPackage( pkgId=None, pkgType=None, name=None, 
              subDirName=None,
              srcDirPath=None, srcExePath=None,    
              resBasePath=None, isTempSrc=False,
              pkgXml=None, pkgScript=None,
              licenses={}, uiPages=[], widgets=[] )

Attributes:

<internal id / type>
pkgId           = None       
pkgType         = None

<QtIFW definition>
name            = None
pkgXml          = None
pkgScript       = None
uiPages         = []
widgets         = []
licenses        = {} <in the form name:filePath>
isLicenseFormatPreserved = False

<source content>            
srcDirPath    = None <package ENTIRE source directory>
srcExePath    = None
resBasePath   = None
distResources = None    
isTempSrc     = False

<destination content>
subDirName   = None
exeName      = None   
exeWrapper   = None

<other configuration details>
isGui           = False
codeSignTargets = None <list of relative paths within package> 
qtCppConfig     = None

Functions:

dirPath()
metaDirPath() 
contentTopDirPath()
contentDirPath()

Static Functions:

topDirPath()

QtIfwPackageXml

Objects of this type define the a QtIFW package.xml file which will be dynamically generated when invoking the buildInstaller function. This file defines a component within the installer which maybe selected by the user to install. Most of the attributes in these objects correspond directly to the name of tags added to the xml. Attributes set to None values will not be written, otherwise they will be.

Constructor:

QtIfwPackageXml( pkgName, displayName, description, version, 
                 scriptName=None, 
                 isDefault=True, isRequired=False, 
                 isHidden=False, isCheckable=True )

Attributes & default values:

pkgName = <required>

SortingPriority    = None               
DisplayName        = <required>
Description        = <required>
Version            = <required>            
Script             = None     
ReleaseDate        = date.today()
Default            = True    
ForcedInstallation = False <isRequired>
Virtual            = False <isHidden>
Checkable          = True
Dependencies       = None
AutoDependOn       = None

UserInterfaces = []
Licenses       = []

Functions:

addCustomTags( root )

write()

debug()
toPrettyXml()

exists()            
path()   
dirPath()

QtIfwPackageScript

QtIFW installers may have a "Control Script" and/or a collection of "Package Scripts". The "Control Script" is intended to dictate how the installer interface behaves, and other high level logic pertaining to the installer itself. In contrast, "Package Scripts" are intended for applying custom logic to manipulate a target environment when installing a given package. See QtIfwControlScript for more info.

Objects of the type QtIfwPackageScript are used to dynamically generate a script used by a QtIFW package. Refer to the details on Installer Scripting to learn more about the low level helpers provided by the library for this purpose.

For maximum flexibility, rather than using the dynamic methods, you may directly define the entire script via a raw string, by setting the script attribute. Or, you may specify an external file as the source instead via script_path. In addition, you may always delegate scripts to a traditional QtIFW definition by using a higher level configuration QtIfwConfig to specify such.

This class works in an analogous manner to QtIfwControlScript. Please refer to the that documentation for an explanation of how use these script objects in general.

Note that for this class QtIfwShortcut objects are used for the shortcuts attribute, QtIfwExternalOp objects are used for externalOps, and QtIfwKillOp objects are used for killOps.

Constructor:

QtIfwPackageScript( pkgName, pkgVersion, pkgSubDirName=None,
                    shortcuts=[], bundledScripts=[], dynamicTexts={},
                    externalOps=[], installResources=[],
                    uiPages=[], widgets=[],
                    fileName="installscript.qs", 
                    script=None, scriptPath=None )

Attributes & default values:

pkgName       = <required>
pkgVersion    = <required>
pkgSubDirName = None

fileName = "installscript.qs"    
script   = None <or loaded via scriptPath>

shortcuts        = []    
bundledScripts   = []    
dynamicTexts     = {} fileName:content
externalOps      = []
installResources = []
killOps          = []
preOpSupport     = None
customOperations = None

<LINUX / MAC only>
    externalDependencies     = []
    areDependenciesPreserved = True

uiPages = []
widgets = []

packageGlobals = None
isAutoGlobals = True

componentConstructorBody = None
isAutoComponentConstructor = True

componentLoadedCallbackBody = None
isAutoComponentLoadedCallback = True

componentCreateOperationsBody = None
isAutoComponentCreateOperations = True

componentCreateOperationsForArchiveBody = None
isAutoComponentCreateOperationsForArchive = True

<Linux Only>
    isAskPassProgRequired = False

Methods

addSimpleOperation( name, parms=[], isElevated=False, isAutoQuote=True )

addSimpleOperation: Appends a QScript snippet to be appended to the customOperations attribute. The available operations are documented on https://doc.qt.io/qtinstallerframework/operations.html. Note that these operations implicitly occur during installation, have implicit "undo" operations (where possible), and cannot be made to occur specifically during an install vs update vs uninstall.
They are, however, cross platform and relatively painless to implement. For more flexibility, use QtIfwExternalOp objects. (The draw back to such is you will need to call upon / include utilities or add ExecutableScripts containing platform specific code.

QtIfwShortcut

These shortcut objects are use by QtIfwPackageScript objects, to create shortcuts on the installation target environments.

Constructor:

QtIfwShortcut( productName=QT_IFW_PRODUCT_NAME, 
               command=None, args=[], 
               exeDir=QT_IFW_TARGET_DIR, exeName=None, 
               exeVersion="0.0.0.0",
               isGui=True, pngIconResPath=None )

Attributes & default values:

productName       = "@ProductName@" <QtIfw Built-in Variable>
command           = None    
exeDir            = "@TargetDir@" <QtIfw Built-in Variable>
exeName           = None
args              = None

isGui             = True <used in Mac / Linux>

windowStyle       = None <used in Windows>

exeVersion        = "0.0.0.0" <used in Linux>        
pngIconResPath    = None <used in Linux>

isAppShortcut       = True
isDesktopShortcut   = False
isAdjancentShortcut = False

QtIfwExternalOp

This class is used to represent and control the invocation of shell commands, external utilities, and embedded ExecutableScripts.
It is employed by QtIfwPackageScript to add operations to the installation, and/or uninstallation, process of the package to which those operations are associated.

This simple example (for *nix based systems), may serve well to clarify how this class is intended to be used:

filePath = joinPathQtIfw( QT_IFW_HOME_DIR, "test.txt" )     
createFileOp = QtIfwExternalOp( exePath="touch",          args=[filePath],
                                uninstExePath="rm", uninstArgs=[filePath] )         
pkg.pkgScript.externalOps = [ createFileOp ]

This purpose of this class should not be confused with the Installer Scripting function execute( binPath, args ).
While that is also a means to invoke sub processes and shell commands from QtIWF, that is more generally used in a "Controller scripting" context for on demand, often conditional and/or dynamic needs. More to the point, QtIfwExternalOp objects are bound directly to packages and to install/uninstall events, where the QtScript execute function can be dropped into installation scripts anywhere, in an unrestricted manner.

Note the intended design by Qt for creating sophisticated, cross platform, custom operations is to modify to the installer engine itself, writing in Qt C++, and recompile it yourself for a specific platform. See: https://doc.qt.io/qtinstallerframework/scripting.html#registering-custom-operations If you really want to do that, here's the source you'll require: https://github.com/qtproject/installer-framework It is the opinion of the distbuilder developers that this typically going to be an absurdly complicated and time consuming endeavor for most use cases. This "external operation" mechanism, while having draw backs is likely a good deal more practical!

Constructor:

QtIfwExternalOp( 
          script=None,       exePath=None,       args=[], successRetCodes=[0],  
    uninstScript=None, uninstExePath=None, uninstArgs=[],  uninstRetCodes=[0],
    isElevated=False, workingDir=QT_IFW_TARGET_DIR, onErrorMessage=None,
    resourceScripts=[], uninstResourceScripts=[], externalRes=[] )

Attributes & default values:

script          = None
exePath         = None
args            = []
successRetCodes = [0]

uninstScript    = None
uninstExePath   = None
uninstArgs      = []
uninstRetCodes  = [0]

isElevated      = False 
workingDir      = QT_IFW_TARGET_DIR

onErrorMessage  = None

resourceScripts       = []
uninstResourceScripts = []
externalRes      = []

Notes:

QtIfw will execute these operations synchronously.
By default, if the return code from the sub process is not 0, this is treated as an installation error. To expand the options for what is viewed as a "success", or can at least be ignored, the attributes successRetCodes, and uninstRetCodes, allow specifying lists of codes for either the installation or uninstallation processes, respectively.

The QtIfwPackageScript attribute externalOps is a list to be executed in order. Note that during uninstallation, that list is processed in reverse order. It is possible (and common), to define operations as only for installation or only for uninstallation. Having direct counterparts is not required. When defining an externalOps list with "pure uninstallation" actions, you should especially keep the reverse order of such operations in mind.

resourceScripts, uninstResourceScripts: Lists of additional ExecutableScripts to make available on the target, for this operation to draw upon. To reference the script, build a path using the python constant QT_IFW_SCRIPTS_DIR or from directly within another script use @ScriptsDir@.

externalRes: A list of QtIfwExternalResource objects. Tools defined this list will be rolled into the installer without explicitly updating the QtIfwPackageScript owner of this operation object.

QtIfwExternalOp Builders

ON_INSTALL, ON_UNINSTALL, ON_BOTH, AUTO_UNDO

Event constants for convenience methods.

opDataPath

opDataPath( rootFileName, isDetached=False, 
            isNative=True, quotes=None, isDoubleBackslash=False )

Dynamically resolve paths to temp data files used by the operations, or to embed in custom scripts.

rootFileName: Under normal circumstances, provide a simple "data key" identifier (with no file extension) for this parameter. If a parent directory is included (be it an absolute or relative path), however, then the path will not be modified further (i.e. it will not built from a root name). Such allows for other functions that internally employ this one to implicitly handle files located elsewhere as well. For example, wrapping rootFileName in qtIfwDetachedOpDataPath(), is another means to reference the alternate "detached" path (rather than via the isDetached option).

isDetached: Operation data files are normally created within an installer sub directory, inside of the user/system temp directory. Everything in this directory is automatically purged when the installer/uninstaller completes. If you use a "detached op data file path", however, the file will be written to the root of the temp directory, and will not be automatically purged. That clean up is left for you to perform. The general use case for this feature is to support "detached operations" which can, and typically do, live beyond the installer/uninstaller's process..

isNative: By default, paths are returned in a native format, i.e. with backslashes vs forward slashes as applicable.

quotes: Optionally, you may provide explicit quote strings (e.g. " or ', or some escaped version of them) to wrap the returned path in such.

isDoubleBackslash: Optionally, use this on Windows, to escape backslashes by doubling them up.

QtIfwExternalOp.MakeDir

MakeDir( event, dirPath,
         owner=QT_IFW_USER, group=QT_IFW_USER, <LINUX/MAC ONLY>
         access="755",                         <LINUX/MAC ONLY>
         isElevated=True )

QtIfwExternalOp.RemoveDir

RemoveDir( event, dirPath, isElevated=True )

QtIfwExternalOp.WriteFile

WriteFile( event, filePath, data, isOverwrite=True,
           owner=QT_IFW_USER, group=QT_IFW_USER, <LINUX/MAC ONLY>
           access="644",                         <LINUX/MAC ONLY>
           isElevated=True )

QtIfwExternalOp.RemoveFile

RemoveFile( event, filePath, isElevated=True )

QtIfwExternalOp.CreateOpFlagFile

CreateOpFlagFile( event, fileName, dynamicVar=None, isElevated=True )

dynamicVar: Control the creation of this file via a dynamic installer variable. Note that a "false" condition will be met when a boolean variable is explicitly set to false, or if the variable is undefined, or it contains no content, or if it is set to 0. The opposing true condition, required to create the flag file, is simply the inverse of that. By default, this argument is set to None, and therefore the file will be created without any logical controls.

QtIfwExternalOp.WriteOpDataFile

WriteOpDataFile( event, fileName, data, isElevated=True )

QtIfwExternalOp.RunProgram

RunProgram( event, path, arguments=None, isAutoQuote=True,  
            isHidden=False, isSynchronous=True, isElevated=True, 
            runConditionFileName=None, isRunConditionNegated=False,
            isAutoBitContext=True )

On Windows, set isAutoBitContext=False if you need to execute a 64 bit program from the installer's 32 bit context.

QtIfwExternalOp.WaitForProcess

WaitForProcess( event, exeName=None, pidFileName=None,
                timeOutSeconds=30, onTimeOut=None,   
                isWaitForStart=False,  
                isSuccessNoWait=True, 
                isAutoBitContext=True )

pidFileName: This optional "op data file" argument, takes precedence over the exeName when provided. It should contain a process id to query. Such a file would normally be created via a prior QtIfwExternalOp.WriteOpDataFile operation or via a writeFile() invocation from QScript (leaning on QtIfwExternalOp.opDataPath() to dynamically resolve the path).

onTimeOut: Additional script snippet to inject. Will be invoked on the event.

On Windows, set isAutoBitContext=False if you need to execute a 64 bit program from the installer's 32 bit context.

QtIfwExternalOp.CreateStartupEntry

CreateStartupEntry( pkg=None, exePath=None, displayName=None, 
                    isAllUsers=False )

TODO: Add Linux & macOS implementations

QtIfwExternalOp.CreateExternPackageFoundFlagFile

MAC / LINUX

CreateExternPackageFoundFlagFile( event, altPkgNames, fileName )

QtIfwExternalOp.InstallExternPackage

MAC / LINUX

InstallExternPackage( event, altPkgNames )

altPkgNames: May be a single string, or a list of them. If providing a list, alternate names will be used based on what is available within a given package manager on the target.
For example, the package "xvfb" maybe specified as ["xvfb","Xvfb"]. That handles the fact the "X" is capitalized within some contexts (e.g. within YUM on RHEL...) but is lower case in others.

QtIfwExternalOp.UninstallExternPackage

MAC / LINUX

UninstallExternPackage( event, altPkgNames )

altPkgNames: May be a single string, or a list of them. If providing a list, alternate names will be used based on what is available within a given package manager on the target.
For example, the package "xvfb" maybe specified as ["xvfb","Xvfb"]. That handles the fact the "X" is capitalized within some contexts (e.g. within YUM on RHEL...) but is lower case in others.

QtIfwExternalOp.CreateWindowsAppFoundFlagFile

WINDOWS ONLY

CreateWindowsAppFoundFlagFile( event, appName, fileName, 
                               isAutoBitContext=True )

QtIfwExternalOp.UninstallWindowsApp

WINDOWS ONLY

UninstallWindowsApp( appName, arguments=None,
                     isSynchronous=True, isHidden=True, 
                     isAutoBitContext=True,
                     isSuccessOnNotFound=True )

QtIfwExternalOp.CreateRegistryKey

WINDOWS ONLY

CreateRegistryKey( event, key, isAutoBitContext=True )

Set isAutoBitContext=False if you need to access 64 bit entries from the installer's 32 bit context, and/or wish to be explicit in the use of SysWow64 nodes.

QtIfwExternalOp.RemoveRegistryKey

WINDOWS ONLY

RemoveRegistryKey( event, key, isAutoBitContext=True )

Set isAutoBitContext=False if you need to access 64 bit entries from the installer's 32 bit context, and/or wish to be explicit in the use of SysWow64 nodes.

QtIfwExternalOp.CreateRegistryEntry

WINDOWS ONLY

CreateRegistryEntry( event, 
    key, valueName=None, value="", valueType="String",
    isAutoBitContext=True )

Set isAutoBitContext=False if you need to access 64 bit entries from the installer's 32 bit context, and/or wish to be explicit in the use of SysWow64 nodes.

QtIfwExternalOp.RemoveRegistryEntry

WINDOWS ONLY

RemoveRegistryEntry( event, 
    key, valueName=None, isAutoBitContext=True )

Set isAutoBitContext=False if you need to access 64 bit entries from the installer's 32 bit context, and/or wish to be explicit in the use of SysWow64 nodes.

QtIfwExternalOp.CreateExeFromScript

WINDOWS ONLY

CreateExeFromScript( script, brandingInfo, srcIconPath,
                     targetDir=QT_IFW_TARGET_DIR )

script: ExecutableScripts

QtIfwExternalOp.WrapperScript2Exe

WINDOWS ONLY

Script2Exe( scriptPath, exePath, brandingInfo,
            iconDirPath, iconName, 
            isScriptRemoved=False, isIconDirRemoved=False )

QtIfwExternalOp.WrapperScript2Exe

WINDOWS ONLY

WrapperScript2Exe( scriptPath, exePath, 
                   targetPath, brandingInfo, iconName="0.ico" )

QtIfwExternalOp Convenience Scripts

Self-Destructing Script Snippets

In some circumstances, e.g. when using scripts with QtIfwOnFinishedDetachedExec or QtIfwOnFinishedCheckbox, you may wish for your scripts to "self-destruct" (i.e. delete themselves).

The following functions return strings that you may append to / weave into your custom scripts to serve this purpose.

QtIfwExternalOp.batchSelfDestructSnippet

QtIfwExternalOp.powerShellSelfDestructSnippet

QtIfwExternalOp.vbScriptSelfDestructSnippet

QtIfwExternalOp.shellScriptSelfDestructSnippet

QtIfwExternalOp.appleScriptSelfDestructSnippet

QtIfwExternalOp.CreateOpFlagFileScript

CreateOpFlagFile( fileName, dynamicVar=None )

dynamicVar: Control the creation of the flag file via a dynamic installer variable. Note that a "false" condition will be met when a boolean variable is explicitly set to false, or if the variable is undefined, or it contains no content, or if it is set to 0. The opposing true condition, required to create the flag file, is simply the inverse of that. So notably, the flag can be raised by having a value in the dynamic variable, to then just simply "true". By default, this argument is set to None, and therefore the file will be created without any logical controls.

Note that the flag is either raised by this function or not. This function does not remove a file that already exists.