This templateis a Gradle project model for building a Windows Visual Client application in the form of an installation file in MSI (Microsoft Windows Installer) or ZIP format. This build requires the Adelia objects in this application to be grouped in the form of artifacts generated by an Adelia build project.
Generally speaking, the included artifacts will be WinClient type (see Table 1 Adelia application area-based build) and produced independently by an application area- or component-based build.
The product installer is an installation assistant-type (setup wizard-type) graphical application involving interactive installation. The installer can also be run in silent mode (non-interactive installation).
Incidentally, an installer can also be produced in the form of a file in ZIP format containing all the objects from the application configuration.
Prerequisites
Building an installer in MSI format uses the open-source Wix Toolset (https://wixtoolset.org/). This framework needs to be installed by downloading the latest version ("Downloads" section) of the installation assistant. After running it, the WIX environment variable (containing the toolset installation path) is created.
This build template uses the Gradle de.inetsoftware.setupbuilder plugin to configure and run the utilities provided by Wix Toolset. It may be necessary to consult its documentation (https://github.com/i-net-software/SetupBuilder/wiki) for requirements outside the scope of this documentation.
Creating an Adelia Windows Client build project
The project is created by unzipping the %ADELIWS%\Build\templates\adelia windows client application.zip file: the obtained 'adelia windows client application' directory can be moved and renamed as required.
The Windows Visual Client application and Adelia build machine may be two different machines. ↑ Top of page
Configuring an Adelia Windows Client build project
After creating a project, it needs to be configured before it can be executed.
Build project configuration and initialization are based on the settings entered in the gradle.properties file, namely:
General settings
adeliaVersion (mandatory)
Alphanumeric string representing the version number of the Adelia template used to package the application.
adeliaRuntimeVersion (optional)
Alphanumeric string representing the version number of the Adelia runtime included when installing the application.
This runtime version must be higher than or equal to the one used by the Adelia build machine to generate artifacts.
Integration of the Adelia runtime is chosen via the adeliaRuntimeIntegration property.
version (mandatory)
Alphanumeric string representing the application artifact version number (MSI and/or ZIP). Each artifact built will have the same version number. There are several version types:
The release (or final) versions representing the official versions of the application (e.g. 1.0.0),
The snapshot (or instantaneous) versions representing the versions of the application that are under development (e.g. 1.0.1-SNAPSHOT),
The pre-release (or release-candidate) versions representing the versions which are candidates for being final versions (e.g. 1.0.1-RC01).
If the setupBuilder.version property (MSI version number for the application) is not entered, the value of this property is used (as the specification of Windows application version numbers requires X.Y.Z syntax, only the "release" part of the version property is used).
group (mandatory)
Alphanumeric string representing the identifier of the group or organization instigating the project.
The value follows the same naming rules as Java packages (e.g. com.hardis), and the name of the project's top package is generally chosen as a value.
adeliaRuntimeIntegration (optional)
Integrates the Adelia runtime files required to run the user application. This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.
The integrated runtime corresponds to the artifact provided by Hardis in the official repository and corresponding to the three identification elements:
- group id: com.hardis.adelia
artifact id: crtadelia
version: adeliaRuntimeVersion property value
If the runtime is not integrated into the application, its content must be accessible by the application's executable files (runtime path in the Windows PATH for example).
microsoftVCRedistInstallation (optional)
Installs the Microsoft Visual C++ Redistributable runtime required to execute the Adelia runtime. This parameter has an alphanumeric value "Y" (installation) or "N" (no installation). This parameter is "N" by default.
For an installation request, the files to install are first copied into the "vcredistrib" sub-directory of the application directory, then redistributables installation is executed. If there is an error, the processing log files for the process are available in this sub-directory.
General parameters for the application installer
These parameters are used when producing an MSI installer and enable the installer and the installed application to be configured.
setupBuilder.name (optional)
Alphanumeric string representing the application name. This name appears in the installer's title. It identifies the application in the list of installed applications ("Applications" settings in Windows) and the name of the folder containing the application execution shortcuts.
If no value is entered, the Gradle project name is taken as a property value.
setupBuilder.appIdentifier (optional)
Alphanumeric string identifying the application in a unique way. Must not contain spaces.
If no value is entered, the Gradle project name is taken as a property value.
setupBuilder.vendor (optional)
Alphanumeric string representing the group or organization which owns the application.
setupBuilder.copyright (optional)
Alphanumeric string identifying the copyright of the application owner.
setupBuilder.description (optional)
Alphanumeric string briefly describing the application.
setupBuilder.longDescriptions (optional)
Alphanumeric string describing the application in detail. The value must be an object array in JSON format. Each object contains a description file path (relating to the build project root) and an associated language (locale in line with standard IETF BCP 47). If an object does not have a language, the description file corresponds to the default language (application.defaultResourceLanguage property).
Example:
application.longDescriptions
[{"resource": "longDesc_default_locale.txt"}, {"locale": "fr-FR",
"resource": "fr/longDesc_fr_FR.txt"}, {"locale": "it-IT", "resource":
"it/longDesc_it_IT.txt"}]
Describes three description files:
- longDesc_default_locale.txt placed at the project root and localized with the default locale
- longDesc_fr_FR.txt placed in the 'fr' sub-directory and localized with the 'fr-FR' locale
- longDesc_it_IT.txt placed in the 'it' sub-directory and localized with the 'it-IT' locale
setupBuilder.icons (optional)
Alphanumeric string describing the list of icon files (.ICO extension) used when installing the application. A Windows application uses the standard icon sizes 16 X 16, 32 X 32, 48 X 48 and 256 X 256 pixels.
The value is either an alphanumeric string in JSON format (describes the path, relating to the build project root, of a single .ICO file) or an alphanumeric string array in JSON format (each string describes the path, relating to the build project root, of an .ICO file).
Examples:
application.icons
"just_one_ico_file.ico" ["images/small_16_32.ico", "images/large_48_256.ico"]
setupBuilder.defaultResourceLanguage (optional)
Alphanumeric string describing the default language (locale in line with standard IETF BCP 47) used for resource management. The default value is the 'en' locale.
setupBuilder.licenseFiles (optional)
Alphanumeric string describing the list of license text files displayed when installing the application. The value must be an object array in JSON format. Each object contains a license file path (relating to the build project root) and an associated language (locale in line with standard IETF BCP 47). If an object does not have a language, the license file corresponds to the default language (application.defaultResourceLanguage property).
Example:
application.licenseFiles
[{"resource": "license_default_locale.txt"}, {"locale": "fr-FR", "resource": "fr/license_fr_FR.txt"}, {"locale": "it-IT", "resource": "it/license_it_IT.txt"}]
Describes three license files:
- license_default_locale.txt placed at the project root and localized with the default locale
- license_fr_FR.txt placed in the 'fr' sub-directory and localized with the 'fr-FR' locale
- license_it_IT.txt placed in the 'it' sub-directory and localized with the 'it-IT' locale
Extended parameters for the MSI installer
Detailed configuration parameters for the MSI installer for Windows.
Click on the following link for more details https://github.com/i-net-software/SetupBuilder/wiki/DSL-of-Windows-Builder.
msi.arch (optional)
Defines the processor architecture compatible with the installer. The possible values are: x86, x64, ia64 and x86-only (the installer will not run on a 64-bit architecture). The default value is the architecture of the machine executing the build project.
msi.minOS (optional)
Defines the minimum value of the Windows operating system on which the installer can run. The default value is the Windows Server 2008 operating system.
msi.installScope (optional)
Defines the scope of the application's installation, i.e. installation on the current user account only or installation on all of the machine's user accounts. The possible values are as follows: 'perUser' or 'perMachine'. The default value 'perMachine'.
msi.bannerBmp (optional)
Defines the image displayed in the upper part of the installation assistant window. The value is an alphanumeric string defining the image path (absolute or relative in relation to the build project root). The supported image formats are: BMP, JPEG (Windows 7 onwards) and PNG (Windows 8 onwards). The optimal image size is 493 X 58 pixels.
msi.dialogBmp (optional)
Defines the image displayed in the left-hand section of the installation assistant window. The value is an alphanumeric string defining the image path (absolute or relative in relation to the build project root). The supported image formats are: BMP, JPEG (Windows 7 onwards) and PNG (Windows 8 onwards). The optimal image size is 493 X 312 pixels.
msi.languages (optional)
Alphanumeric string describing the list of languages supported by the installation assistant (the alphanumeric strings displayed by the assistant, like "Previous" and "Next" are localized according to the supported languages). The value must be an alphanumeric string array in JSON format. Each string describes a language (locale in line with standard IETF BCP 47). The default value is all the languages supported by the Wix toolset (see https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html).
Example:
msi.languages
["en-US", "de-DE", "fr-FR"]
Repository manager settings
Artifact repositories are used during the following phases when executing an Adelia Windows Client build:
In the installation file (MSI or ZIP) creation phase, the build uses a repository (download repository) to download the artifacts required to build the installer artifact. These artifacts are:
the Hardis artifact needed to execute the build template and the Adelia runtime artifact if requested to add it to the built application,
your own Adelia object artifacts comprising your application: these are generated by the execution of an Adelia build project.
In the final storage phase for the built artifact, a repository (upload repository) can be defined to transfer this versioned artifact.
According to the version type (release or snapshot), the associated repository can be defined.
downloadArtifactsReleaseRepo (mandatory)
Access URL to the download repository of the dependent artifacts needed for the build. This repository should make it possible to access:
Hardis repository artifacts (Adelia runtime for example),
your own Adelia object artifacts comprising your application. These artifacts are in release version if you build your application in the release version.
By default, and by way of example only, the value of this parameter is the URL of the repository provided by Hardis.
In its place, in your Nexus, you need to create your own private repository so the Hardis repository and your private repository are grouped together in the release version. Depending on your own Nexus configuration used for your Adelia build projects, it is either the repository created by default by Nexus and called "Releases", or another "hosted repository" with a "Repository policy" set to Release and created by you.
To do this, after logging in to Nexus, in the "Repositories" view, add a new repository defined as a group of repositories described above:
Open the repository definition window via the "Add repository group" command,
From the "Available Repositories" section, add, in the "Ordered Group Repositories" section, the private repository which is a proxy of the Hardis repository as well as the private hosted repository used to store your artifacts in release version.
To finish, replace the downloadArtifactsReleaseRepo parameter value with the "Repository Path" URL of the newly created group repository.
downloadArtifactsReleaseRepo.username / downloadArtifactsReleaseRepo.password (optional)
Defines the user profile and password used to connect to the download repository.
By default, and by way of example, these identifiers are those of the Hardis download repository but they need to be replaced by those of your own group private repository (see downloadArtifactsReleaseRepo above).
When you access this repository in read-only mode, Nexus authorizes an anonymous connection: in this case, leave the "username" and "password" fields blank.
downloadArtifactsSnapshotRepo (optional)
Access URL to the download repository of the dependent artifacts needed for the build. This repository should make it possible to access your own Adelia object artifacts comprising your application. These artifacts are in snapshot version if you build your own application in snapshot version.
NB: Hardis repository artifacts are only available in release version (no snapshot version available).
In your Nexus, you need to create your own private repository so the Hardis repository and your private repository are grouped together in the snapshot version. Depending on your own Nexus configuration used for your Adelia build projects, it is either the repository created by default by Nexus and called "Snapshots", or another "hosted repository" with a "Repository policy" set to Snapshot and created by you.
To do this, after logging in to Nexus, in the "Repositories" view, add a new repository defined as a group of repositories described above:
Open the repository definition window via the "Add repository group" command,
From the "Available Repositories" section, add, in the "Ordered Group Repositories" section, the private repository which is a proxy of the Hardis repository as well as the private hosted repository used to store your artifacts in snapshot version.
To finish, replace the downloadArtifactsSnapshotRepo parameter value with the "Repository Path" URL of the newly created group repository.
downloadArtifactsSnapshotRepo.username / downloadArtifactsSnapshotRepo.password (optional)
Defines the user profile and password used to connect to the download repository. This profile should enable you to access your own private group repository (see downloadArtifactsSnapshotRepo above).
When you access this repository in read-only mode, Nexus authorizes an anonymous connection: in this case, leave the "username" and "password" fields blank.
uploadArchivesReleaseRepo (optional)
Access URL to the upload repository used to store the MSI or ZIP artifact built with a release version.
This repository enables the artifacts to be made available in the final version.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)
Defines the user profile and password used to connect to the artifact upload repository in the release version.
uploadArchivesSnapshotRepo (optional)
Access URL to the upload repository used to store the MSI or ZIP artifact built with a snapshot version.
This repository enables the artifacts under development to be made available.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)
Defines the user profile and password used to connect to the artifact upload repository in the snapshot version.
Configuring the components of the Adelia Windows Client application to build
These components are the Adelia object artifacts generated by the execution of an Adelia build project.
They need to be declared in the Adelia Windows Client build project in order to be added to the product installer.
To do this:
open the build.gradle file with a text editor, then
in the "dependencies" section (Declare your artifacts needed to build the Windows application here), declare your artifacts.
WinClient-type artifacts
These artifacts must be declared by inserting the following instruction:
winClient group: '<artifact group name>', name: '<artifact file name without version>', version: '<artifact version number>'
Example of declaration of artifact generated by an application area-based build:
For the WinClient-type artifact with the file name myapp-app_area_1_winclient-1.1.0-SNAPSHOT.zip, enter runtime group: 'my.company', name: 'myapp-app_area_1_winclient', version: '1.1.0-SNAPSHOT'.
The group value is that of the "group" setting in the gradle.properties file of the Adelia build project which built the artifact.
Example of declaration of artifact generated by a component-based build:
For the WinClient-type artifact with the file name prefix_compo_1_winclient-1.1.0-SNAPSHOT.zip, enter runtime group: 'my.company', name: 'prefix_compo_1_winclient', version: '1.1.0-SNAPSHOT'.
The group value is that of the "groupId" setting of the component which generates the artifact.
The content of artifacts declared as above is added to the application as follows: The files from unzipping each artifact are copied to the application root when it is installed (the choice of installation directory is left to the user by the installation assistant).
Adelia runtime artifact
The Adelia runtime artifact 'com.hardis.adelia:crtadelia:X.Y.Z' (where X.Y.Z has the value of the adeliaRuntimeVersion property) is added to the application if the adeliaRuntimeIntegration property is "Y". In this case, the files contained in this artifact are copied to the application root.
Other artifacts
Other artifacts (in ZIP or JAR format) can be added to the application like, for example, an artifact containing the file resources required for the application to work and built by a third-party tool (Gradle, Maven or other). In this case, it is possible to, as an example, declare them by inserting the following instruction:
othersResourcesConf group: '<artifact group name>', name: '<artifact file name without version>', version: '<artifact version number>'
The 'othersResourcesConf' configuration must first be declared in the 'configurations' closure (declaration to uncomment). The artifact content will be inserted into the application in the 'setupBuilder' closure: this content can either be added at the application root or in a sub-directory (code to uncomment).
↑ Top of page
It is possible to declare access or object launch shortcuts for your application (executable .EXE file, .CHM or .HTML help file for example). To do this, you need to declare a 'desktopStarter' closure inside the 'setupBuilder' closure. The closure properties are as follows:
- displayName: Shortcut text,
- description: Short descriptive text associated with the shortcut,
- executable: Path relating to the root of the object application to launch, such as the name of a VAI program executable (e.g. LAUCH.EXE),
- workDir: Startup path (relating to the application root) of the object to launch,
- startArguments: Additional arguments for starting the object (optional),
- icons: Icon file (.ICO) associated with the shortcut (optional. By default, the value is taken from the application.icons property),
- location: Shortcut positioning. The possible values are as follows: 'ApplicationMenu' (shortcut in the application menu), 'StartMenu' (shortcut in the start menu), 'InstallDir' (shortcut in the application installation directory) and 'DesktopDir' (desktop shortcut).
As many 'desktopStarter" closures can be declared as there are shortcuts to define.
To internationalize the text (displayName) of a shortcut:
- Create a .properties file for each supported language (e.g. shortcut_fr_FR.properties, shortcut_en_US.properties) at the build project root,
- For each file, add an entry (syntax key = value) with the same key name and for each key, the text of the translated shortcut (e.g. In shortcut_fr_FR.properties, add my_key_shortcut_launch=My application and in shortcut_en_US.properties, add my_key_shortcut_launch=My application)
- In the 'desktopStarter' closure, set the '!(loc.my_key_shortcut_launch)' (displayName='!(loc.my_key_shortcut_launch)') string as the displayName property
In the "msi" closure, associate the .properties resource files as well as their language:
msi closuremsi { i18n { // set locale locale = "fr-FR" // set the localization resource filename (relative to root project directory) resource = "shortcut_fr_FR.properties" } i18n { // set locale locale = "en-US" // set the localization resource filename (relative to root project directory) resource = "shortcut_en_US.properties" } }
Configuration files for the Adelia Windows Client application to build
Depending on your application's architecture, some Adelia configuration files may be required to execute it, like the mwclient.ini file for example. To add these files to the application, use the Gradle copy directive 'from' to copy these files into the application installation directory (a commented example is given in the build.gradle template provided).
Executing an Adelia Windows Client build project
List of Gradle tasks for Adelia Windows Client build
clean
Task enabling the objects created when executing msi and zipApp build tasks to be deleted (the build sub-directory is deleted).
msi
Launches the installation file build in MSI format. The produced file is in the 'build\distributions' sub-directory. Its name is the result of the concatenation of application.appIdentifier and version properties.
Important note:
Depending on the configuration of the machine executing the build, the msi task may trigger the following error message "Microsoft VBScript 46 execution error": Permission denied when executing the "cscript" command. This error may be due to the machine's antivirus which, when scanning created files in real time, locks the .MSI file. The solution is to configure the antivirus so that it does not scan the .MSI file build directory, i.e. the default Windows temporary directory %USERPROFILE%\AppData\Local\Temp.
The Wix Toolset can be used to change this temporary build directory via the "WIX_TEMP" environment variable and to specify a build-specific directory.
zipApp
Launches the archiving file build for the application in ZIP format. The produced file is in the 'build\distributions' sub-directory. Its name is the result of the concatenation of application.appIdentifier and version properties.
This file groups together:
- the content of the project's dependent artifacts (artifacts defined in winClient, otherResourcesConf configurations),
- the content of the Adelia runtime artifact (if it is integrated),
- the added configuration files (mwclient.ini, etc.).
uploadArchives
This task transfers the built artifacts (by calling the msi and/or zipApp tasks) to the upload repository.
You must specify the uploadArchivesReleaseRepo or uploadArchivesSnapshotRepo key, depending on the artifact version type.
install
This task transfers the built artifacts (by calling the msi and/or zipApp tasks) to the repository local to the build machine (local repository in %USERPROFILE%\.m2 directory).
MSI installation assistant
The installation assistant's standard screens
Here is an example of the installation assistant's screen sequence. Note that in advanced programming, the de.inetsoftware.setupbuilder plugin offers extended features (service startup, triggering of processing after installation and before uninstalling, file deletion, etc.) as well as the option of adding your own dialog boxes by programming them via the Wix Toolset.
Quiet installation
The installation assistant can be launched without interaction with the user. In this case, the application installation is executed with the default options (installation directory for example).
To launch the quiet installer, you need to launch the .MSI file produced with administrator rights.
To see the available execution options, launch the .MSI file with the '/help' option.
For example, to launch an installation in the 'C:\testInstall' directory, you need to execute:
msiexec /i mynewapp-1.0.0-SNAPSHOT.msi /quiet INSTALLDIR=C:\testInstall