4. Package structure detailed

WAPT package structure shown in Windows Explorer

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 after 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 after 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 after 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.

PyScripter - UTF-8 (No BOM)

PyScripter - UTF-8 (No BOM)

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.