.. Reminder for header structure:        
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """""""""""""""""""""

.. meta::
  :description: WAPT package structure
  :keywords: WAPT, package, structure, setup.py, control

##########################
Package structure detailed
##########################

.. note::
  WAPT packages whose names end with the suffix :command:`-template`` are generic templates designed to be adapted to the specific needs of each organisation. :command:`They should not be installed directly without prior modification.`
  
  These packages act as working bases that :command:`require customisation` to meet the technical specifications or internal policies of your company or IT department.

.. _structure_wapt_package:

.. figure:: wapt-resources/windows_concept_wapt-package-structure_browser-window.png
  :align: center
  :scale: 75 %
  :alt: WAPT package structure shown in Windows Explorer

  WAPT package structure shown in Windows Explorer

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

* A :file:`setup.py` file.

* One or several binary files.

* Some additional optional files.

* A :file:`control` file in the :file:`WAPT` folder.

* A :file:`icon.png` file in the :file:`WAPT` folder.

* A :file:`certificate.crt` file in the folder :file:`WAPT`.

* A :file:`manifest.sha256` file in the folder :file:`WAPT`.

* A :file:`signature.sha256` file in the folder :file:`WAPT`.

* A :file:`wapt.psproj` file in the folder :file:`WAPT`, this file is used to store the :program:`PyScripter` configuration data for the WAPT package.

* Since WAPT 1.8, a hidden :file:`.vscode` folder that contains a :file:`launch.json` and a :file:`settings.json` file is used to store the :program:`VScode` configuration data for the WAPT package.

******************
The *control* file
******************

  .. _structure_control:

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

.. code-block:: ini

    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

.. list-table:: Description of options of the control file
  :header-rows: 1
  :widths: 25, 50, 25

  * - Settings
    - Description
    - Example value
  * - :code:`package`
    - Defines the package name, **without any accent, nor space, nor any special or uppercase character**.
    - tis-geogebra
  * - :code:`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 (:kbd:`.`) and **MUST** finish with the WAPT packaging version separated by a dash (:kbd:`-`) character.
    - 5.0.309.0-1
  * - :code:`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
  * - :code:`section`
    - Defines the WAPT package type (``host``, ``group``, ``base``).

      Allowed values are:

      - **host**: host package;
      - **group**: group package;
      - **base**: software package;
      - **unit**: :abbr:`OU (Organizational Unit)` package;
    - base
  * - :code:`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
  * - :code:`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>
  * - :code:`description`
    - Defines the WAPT package description that will appear in the WAPT Console and in the self-service.

      Adding a field :code:`description_fr` or :code:`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
  * - :code:`description_fr`
    - Localizes the description of the package.
    - Calculatrice graphique
  * - :code:`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
  * - :code:`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 :code:`depends`.

      Several conflicts may be defined by splitting them with commas (*,*).

    - tis-graph
  * - :code:`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 :code:`maturities` attribute **MUST** be set in the :file:`wapt-get-ini` configuration file of the WAPT Agent.
    - PROD
  * - :code:`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 :code:`locales` in :file:`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 :file:`wapt-get-ini` configuration file of the WAPT Agent.
    - fr,en,es
  * - :code:`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 :code:`target_os` can have several data, it has to correspond to the :code:`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
  * - :code:`min_os_version`
    - Defines the minimum version of Windows for the package to be seen by the WAPT Agent.

      For a :code:`target_os` = ``windows``, this field defines the minimal `Windows Operating System Version <https://docs.microsoft.com/en-us/windows/win32/sysinfo/operating-system-version?redirectedfrom=MSDN>`_.
      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
  * - :code:`max_os_version`
    - Defines the maximum version of Windows for the package to be seen by the WAPT Agent.

      For a :code:`target_os` = ``windows``, it defines the maximal `Windows Operating System Version <https://docs.microsoft.com/en-us/windows/win32/sysinfo/operating-system-version?redirectedfrom=MSDN>`_.
      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
  * - :code:`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
  * - :code:`sources`
    - Defines the path to the SVN location of the WAPT package (:command:`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/
  * - :code:`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 :file:`C:\\Program Files` folder.

      The value set in :code:`installed_size` **MUST** be in bytes.

      To convert storage values to bytes, visit `bit-calculator <https://bit-calculator.com/>`_.
    - 254251008
  * - :code:`impacted_process`
    - Indicates a list of impacted processes when installing a WAPT package.

      :code:`impacted_process` is used by the functions :command:`install_msi_if_needed` and :command:`install_exe_if_needed` if :code:`killbefore` has not been filled.

      :code:`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
  * - :code:`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
  * - :code:`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
  * - :code:`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
  * - :code:`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

  * - :code:`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/

  * - :code:`package_uuid`
    - Unique identifier of the package. It is automatically generated when building the package.
    - dc66ccd1-d987-482e-b792-04e89a3803f7

  * - :code:`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

  * - :code:`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

  * - :code:`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

  * - :code:`signer`
    - Defines the :abbr:`CN (Common Name)` 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
  * - :code:`signer_fingerprint`
    - Provides the fingerprint of the certificate holder's signature.

      The value is automatically inserted when signing the WAPT package.
    - 2BAFAF007C174A3B00F12E9CA1E74956
  * - :code:`signature`
    - Provides the SHA256 hash of the WAPT package.

      The value is automatically inserted when signing the WAPT package.
    - MLOzLiz0qC(...)hsEjGRaMLBlod/p8w==
  * - :code:`signature_date`
    - Provides the date when the package was signed.

      The value is automatically inserted when signing the WAPT package.
    - 20180307-230413
  * - :code:`signed_attributes`
    - Lists of attributes of the :file:`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

.. _utf8_no_bom:

.. attention::

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

.. figure:: wapt-resources/wapt_pyscripter_utf8NoBOM_menu-selection.png
  :align: center
  :scale: 50%
  :alt: PyScripter - UTF-8 (No BOM)

  PyScripter - UTF-8 (No BOM)

*******************
The *setup.py* file
*******************

* :code:`import setuphelpers` is found at the beginning of every WAPT package that embeds a :file:`setup.py`:

  .. code-block:: python

    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 :code:`uninstallkey` list to associate a list of *uninstall keys* to the WAPT package.

  .. code-block:: python

    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:

  .. code-block:: python

    uninstallkey = []

* followed by functions such as :code:`def_install()`, :code:`def_uninstall()`, :code:`def_session-setup()` and :code:`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.

**********************
The *wapt.psproj* file
**********************

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

It is the :program:`PyScripter` project file for the WAPT package.

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

*******************
The *icon.png* file
*******************

The :file:`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 :mimetype:`.png` file.

**************************
The *manifest.sha256* file
**************************

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

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

********************
The *signature* file
********************

The :file:`signature` file is located in the WAPT folder.

It contains the signature of the :file:`manifest.sha256` file.

On installing a WAPT package, :program:`wapt-get` checks:

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

* That the sha256 fingerprint of each file is identical to the fingerprint in the :file:`manifest.sha256` file.

**************************
The *certificate.crt* file
**************************

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

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

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

***********
Other files
***********

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

* An installer beside the :file:`setup.py` to be called from the :program:`setup.py`.

* An answer file to pass on to the software installer.

* A license file.

* Etc.