4. Package structure detailed¶

WAPT package structure shown in Windows Explorer¶

A WAPT package is a .zip file containing several things:

A setup.py file.
One or several binary files.
Some additional optional files.
A control file in the WAPT folder.
A icon.png file in the WAPT folder.
A certificate.crt file in the folder WAPT.
A manifest.sha256 file in the folder WAPT.
A signature.sha256 file in the folder WAPT.
A wapt.psproj file in the folder WAPT, this file is used to store the PyScripter configuration data for the WAPT package.
Since WAPT 1.8, a hidden .vscode folder that contains a launch.json and a settings.json file is used to store the VScode configuration data for the WAPT package.

4.1. The control file¶

The control file is the identity card of a WAPT package.

package           : tis-firefox-esr
version           : 62.0-0
architecture      : all
section           : base
priority          : optional
maintainer        : Administrateur
description       : Firefox Web Browser French
description_fr    : Navigateur Web Firefox Français
description_es    : Firefox Web Browser
depends           :
conflicts         :
maturity          : PROD
locale            : fr
target_os         : windows
min_os_version    :
max_os_version    :
min_wapt_version  : 1.6.2
sources           :
installed_size    :
impacted_process  : firefox.exe
audit_schedule    :
editor            : Mozilla
keywords          : Navigateur
licence           : MPL
homepage          : https://www.mozilla.org/en-US/firefox/organizations/
package_uuid      : dc66ccd1-d987-482e-b792-04e89a3803f7
valid_from        : 2022-02-23T00:00:00
valid_until       : 2022-03-23T00:00:00
forced_install_on : 2022-03-23T00:00:00
signer            : Tranquil IT
signer_fingerprint: 459934db53fd804bbb1dee79412a46b7d94b638737b03a0d73fc4907b994da5d
signature         : MLOzLiz0qCHN5fChdylnvXUZ8xNJj4rEu5FAAsDTdEtQ(...)hsduxGRJpN1wLEjGRaMLBlod/p8w==
signature_date    : 20170704-164552
signed_attributes : package,version,architecture,section,priority,maintainer,description,depends,conflicts,maturity,locale,min_os_version,max_os_version,min_wapt_version,sources,installed_size,signer,signer_fingerprint,signature_date,signed_attributes

Description of options of the control file¶
Settings	Description	Example value
`package`	Defines the package name, without any accent, nor space, nor any special or uppercase character.	tis-geogebra
`version`	Defines the package version (note: the version MUST not contain more than 5 delimiters, the last number being the version number of the packaging). The version MUST start with the packaged software version (digits only) split by points (`.`) and MUST finish with the WAPT packaging version separated by a dash (`-`) character.	5.0.309.0-1
`architecture`	Defines the processor architecture onto which the WAPT package will install. A x64 package will be invisible to a WAPT Agent installed on a x86 host. Allowed values are: x86: the package is designed for 32bit computers; x64: the package is designed for 64bit computers; all: the package is designed for any architecture.	x64
`section`	Defines the WAPT package type (`host`, `group`, `base`). Allowed values are: host: host package; group: group package; base: software package; unit: OU package;	base
`priority`	Defines the WAPT package install priority (optional). This option is not supported at this time. That field will be used to define package installation priority. This feature will become useful to define mandatory security updates.	Not used at this moment
`maintainer`	Defines the author of the WAPT package. To define the WAPT package maintainer’s email address may be useful. Use Firstname LASTNAME <email@example.com> format.	Arnold SCHWARZENEGGER <terminator@mydomain.lan>
`description`	Defines the WAPT package description that will appear in the WAPT Console and in the self-service. Adding a field `description_fr` or `description_es` allows you to internationalize the description of your package. If the language does not exist, the WAPT Agent will use the default language description.	The Graphing Calculator for Functions, Geometry, Algebra, Calculus, Statistics and 3D
`description_fr`	Localizes the description of the package.	Calculatrice graphique
`depends`	Defines the packages that MUST be installed before, for example tis-java is a dependency for the LibreOffice package and tis-java MUST be installed before LibreOffice. Several dependencies may be defined by splitting them with commas (,).	tis-java
`conflicts`	Defines WAPT packages that MUST be removed before installing the package, for example tis-firefox MUST be removed before the package tis-firefox-esr is installed, or OpenOffice MUST be removed before LibreOffice is installed. It works the opposite way of `depends`. Several conflicts may be defined by splitting them with commas (,).	tis-graph
`maturity`	Defines the maturity level of the WAPT package (`PREPROD`, `DEV`, `PROD`, etc). By default, WAPT Agents will see packages flagged as PROD and packages with an empty maturity. For a computer to see WAPT packages with different maturity levels, the `maturities` attribute MUST be set in the `wapt-get-ini` configuration file of the WAPT Agent.	PROD
`locale`	Defines the language environment for the WAPT package. A WAPT Agent will see by default packages that are configured for its language environment(s) and packages with no language specified. For a computer to see a package in another language, you will have to configure the `locales` in `wapt-get.ini` of the WAPT Agent. Case and order do not not matter. If you want to respect an order for maturities, you will need to set the order in the `wapt-get-ini` configuration file of the WAPT Agent.	fr,en,es
`target_os`	Defines the accepted Operating System for the WAPT package. A WAPT Agent will see by default packages that are configured for its operating system and packages with no operating system specified. Since version 2.3 the field `target_os` can have several data, it has to correspond to the `host_capabilities` tag. With debian, you can use < or >. The First three in the example are the most used.	windows, mac, linux, debian-bullseye, redhat_based, centos8, debian(>8), ubuntu, almalinux8
`min_os_version`	Defines the minimum version of Windows for the package to be seen by the WAPT Agent. For a `target_os` = `windows`, this field defines the minimal Windows Operating System Version. For example, this attribute may be used to avoid installing WAPT packages on WindowsXP that only work on Windows7 and above. Since version 1.8, it can also define the minimal macOS version. We advise not to use it with Linux since there are several different Linux distributions.	6.0
`max_os_version`	Defines the maximum version of Windows for the package to be seen by the WAPT Agent. For a `target_os` = `windows`, it defines the maximal Windows Operating System Version. For example, this attribute may be used to install on Windows7 more recent versions of a software that are no more supported on Windows XP. Since version 1.8, it can also define the minimal macOS version. We advise not to use it with Linux since there are several different distributions.	10.0
`min_wapt_version`	Defines the minimal version of the WAPT Agent for the WAPT package to work properly. With functionalities in WAPT evolving, some functions that you may have used in old packages may become obsolete with newer versions of WAPT Agents.	1.3.8
`sources`	Defines the path to the SVN location of the WAPT package (wapt-get source). Defines a repository for versionning WAPT packages, for example https://svn.mydomain.lan/sources/tis-geogebra-wapt/trunk/. This method allows to version a package and collaboratively work on it. Package versionning is particularly useful when several people create packages in a collaborative way. This function is also useful to trace the history of a package if you are subject to Regulations in your industry.	https://srv-svn.mydomain.lan/sources/tis-geogebra-wapt/trunk/
`installed_size`	Defines the minimum required free disk space to install the WAPT package. The testing of available free disk space is done on the `C:\Program Files` folder. The value set in `installed_size` MUST be in bytes. To convert storage values to bytes, visit bit-calculator.	254251008
`impacted_process`	Indicates a list of impacted processes when installing a WAPT package. `impacted_process` is used by the functions install_msi_if_needed and install_exe_if_needed if `killbefore` has not been filled. `impacted_process` is also used when uninstalling a WAPT package. This allows to close the application if the application is running before being uninstalled.	firefox.exe
`audit_schedule`	Defines the periodicity of execution of the audit function in the WAPT package. The periodicity may be indicated in two ways: an integer (in minutes); an integer followed by a letter (m = minutes, h = hours, d = days, w = weeks).	60
`editor`	Defines the editor of the software title embedded in the WAPT package. The values may be used as filters in the WAPT Console and with the WAPT Self-service.	Mozilla
`license`	Defines the licence of the software title embedded in the WAPT package. The values may be used as filters in the WAPT Console and with the WAPT Self-service.	GPLV3
`keywords`	Defines a set of keywords describing the WAPT package. The values may be used as filters in the WAPT Console and with the WAPT Self-service.	Productivity, Text Processor
`homepage`	Defines the official homepage of the software title embedded in the WAPT package. The values may be used as filters in the WAPT Console and with the WAPT Self-service.	https://www.tranquil.it/
`package_uuid`	Unique identifier of the package. It is automatically generated when building the package.	dc66ccd1-d987-482e-b792-04e89a3803f7
`valid_from`	Date / time from which the package may be installed. The WAPT Agent will refuse to install it before that date. The string is formated according to the ISO8601 standard: YYYY-MM-DDTHH:MM:SS. When the date has passed, WAPT will install the package when an update is triggered.	2022-02-23T00:00:00
`valid_until`	Date / time from which the package may not be installed. The WAPT Agent will refuse to install it after that date. The string is formated according to the ISO8601 standard: YYYY-MM-DDTHH:MM:SS.	2022-02-23T00:00:00
`forced_install_on`	Date / time from which the WAPT Agent will trigger a forced install of the package. The string is formated according to the ISO8601 standard: YYYY-MM-DDTHH:MM:SS.	2022-02-23T00:00:00
`signer`	Defines the CN of the WAPT package’s signer. It is generally the name of the signer’s full name. The value is automatically inserted when signing the WAPT package.	Tranquil IT
`signer_fingerprint`	Provides the fingerprint of the certificate holder’s signature. The value is automatically inserted when signing the WAPT package.	2BAFAF007C174A3B00F12E9CA1E74956
`signature`	Provides the SHA256 hash of the WAPT package. The value is automatically inserted when signing the WAPT package.	MLOzLiz0qC(…)hsEjGRaMLBlod/p8w==
`signature_date`	Provides the date when the package was signed. The value is automatically inserted when signing the WAPT package.	20180307-230413
`signed_attributes`	Lists of attributes of the `control` file of the WAPT package that are signed. The value is automatically inserted when signing the WAPT package.	package, version, architecture, section, priority, maintainer, description, depends, conflicts, maturity, locale, min_wapt_version, sources, installed_size, signer, signer_fingerprint, signature_date, signed_attributes

Attention

If the control file contains special characters, the control file MUST be saved in UTF-8 (No BOM) format.

4.2. The setup.py file¶

import setuphelpers is found at the beginning of every WAPT package that embeds a setup.py:
```
from setuphelpers import *
```
The WAPT package imports all SetupHelpers functions.

SetupHelpers is a WAPT library that offers many methods to easily develop highly functional WAPT packages.
followed by a uninstallkey list to associate a list of uninstall keys to the WAPT package.
```
uninstallkey = ['tisnaps2','Mozilla Firefox 45.6.0 ESR (x86 fr)']
```
When a package is removed, the WAPT Agent looks up the uninstallkey in the registry associated to the package. This uninstallkey will indicate to WAPT the actions to trigger to remove the software.

Even if there is no uninstallkey for a software, it is mandatory to declare an empty uninstallkey array:
```
uninstallkey = []
```
followed by functions such as def_install(), def_uninstall(), def_session-setup() and def_audit()

These functions describe the recipes of the WAPT package, the set of instructions that will be executed to install, remove, configure and audit a WAPT package.

4.3. The wapt.psproj file¶

Package project file wapt.psproj is located in the WAPT folder.

It is the PyScripter project file for the WAPT package.

To edit a package with PyScripter, just open the file.

4.4. The icon.png file¶

The icon.png icon file is located in the WAPT folder.

It associates an icon to the WAPT package.

Hint

The icon is used in the Self-Service, it is downloaded with its MD5 sum for security; if the MD5 sum is not good then the icon is removed.
The icon MUST be a 48px per 48px .png file.

4.5. The manifest.sha256 file¶

The manifest.sha256 manifest file is located in the WAPT folder.

It contains the sha256 fingerprint of every file in the WAPT package.

4.6. The signature file¶

The signature file is located in the WAPT folder.

It contains the signature of the manifest.sha256 file.

On installing a WAPT package, wapt-get checks:

That the signature of manifest.sha256 matches the actual manifest.sha256 file (the WAPT Agent will verify the public certificates in C:\Program Files (x86)\wapt\ssl on Windows and /opt/wapt/ssl on Linux and macOS).
That the sha256 fingerprint of each file is identical to the fingerprint in the manifest.sha256 file.

4.7. The certificate.crt file¶

The certificate.crt file is located in the WAPT folder.

It is the maintainer’s certificate whom signed the package.

On installing a WAPT package, wapt-get checks that the certificate.crt or its parent matches with certificates in C:\Program Files (x86)\wapt\ssl on Windows and /opt/wapt/ssl on Linux and macOS. If the certificate does not match, the WAPT package will not be installed.

4.8. Other files¶

Other files may be embedded in the WAPT package, for example:

An installer beside the setup.py to be called from the setup.py.
An answer file to pass on to the software installer.
A license file.
Etc.