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

.. meta::
 :description: WAPT documentation version 2.7 Quickstart - Create your first WAPT Package
 :keywords: Quickstart, WAPT, package, create

.. role:: green
   :class: green-text

.. role:: red
   :class: red-text

.. _quickstart_create_first_package:

###########################################
Quickstart - Create your first WAPT Package
###########################################

This tutorial will guide you through **creating custom WAPT packages** to deploy software that is **not available in the WAPT store** or to tailor existing software to your specific needs.
Whether you need to integrate an internal tool, a business application, or a modified version of a software, this method allows you to **control deployment** across your infrastructure.

******************************************************
Prerequisites: Setting Up Your Development Environment
******************************************************

To create and test WAPT packages, you need to meet the following requirements:

- **Administrator Rights**: You must be a **local administrator** on the development machine to use WAPT's integrated development environment.

- **Controlled Environment**: We strongly recommend creating and editing packages in a **safe and disposable environment**, such as a **virtual machine (e.g., VirtualBox)**. This avoids any impact on production systems.

- **Development Tools**: Install a **code editor** to modify package files. We recommend:
  - **Visual Studio Code** (with the WAPT extension)
  - **PyScripter 3** (specifically designed for WAPT)
  - *Avoid*: PyScripter 4 (not compatible with WAPT development features).

- **WAPT Development Package**: Import and install the **`tis-waptdev`** package from your WAPT repository. This package includes all the necessary tools for creating and testing WAPT packages.
  If you need help importing or installing this package, refer to:
  :ref:`How to import and install a WAPT Package <quickstart_manage_package>`.


***********************
Create the WAPT Package
***********************

**Creating a package template from the WAPT Console (MSI file)**

We use the Naps2 MSI setup downloaded from the Naps2 official website.

* `Download Naps2 for x64 <https://github.com/cyanfish/naps2/releases/download/v8.3.2/naps2-8.3.2-win-x64.msi>`_.

* Create a WAPT package Template from the installer.

  In the WAPT Console, click on the :guilabel:`Packages Inventory` :red:`(1)` tab → :guilabel:`Make package template from setup file` :red:`(2)` → :guilabel:`template package` :red:`(3)`.

  .. figure:: wapt-resources/quickstart-template_package.png
    :scale: 75%
    :align: center
    :alt: Menu option template package

* Select :guilabel:`Windows installer` :red:`(1)` and search the MSI setup file of naps2 :red:`(2)`.
  
  Click on :guilabel:`continue`. :red:`(3)`

  .. figure:: wapt-resources/quickstart-console-make-package-template_menu-option.png
    :scale: 75%
    :align: center
    :alt: Menu option for creating a WAPT package template in the WAPT Console

    Menu option for creating a WAPT package template in the WAPT Console

* Verify that the **package name does not contains any version number**.

  .. figure:: wapt-resources/quickstart-console-package-wizard.png
    :scale: 75%
    :align: center
    :alt: Menu option package wizard in the WAPT Console

    Menu option package wizard in the WAPT Console


* **Two solutions are available:**

  * Click on :guilabel:`Build and upload` to directly build and upload the package into your private repository **without testing**..

  * Click on :guilabel:`Edit manually` (recommended) to verify the WAPT package and customize it to your Organization's specific needs.

.. tab-set::

  .. tab-item:: Build and upload

      .. Warning::
      
        The button :guilabel:`Build and upload` directly uploads the package into the private repository **without testing**.

        This method works relatively well with MSI installers because their installation is more standardized.

        However, the **Edit manually method** that consists of first testing locally the package before uploading **is the recommended method**.

      * If you trust or have already tested the package, you can click :guilabel:`Make and upload` :red:`(1)` to build and upload the package directly to your private repository.

      .. figure:: wapt-resources/quickstart-build_and_upload.png
        :scale: 75%
        :align: center
        :alt: make and upload package

        Make and upload package

      The package is now available in your **package inventory**.

      * All that remains is to **deploy the package to your test machine** and verify its proper installation and uninstallation.

      You can refer to the previous documentation to review how to :ref:`verify the correct installation of the new package on the workstation <adding_package_dependency>`.

      To check its uninstallation, see the :ref:`dedicated documentation on uninstalling and removing a package dependency <quickstart_uninstall_package>`.
  
  .. tab-item:: Edit manually
    :name: edit

    .. note::

      This method is recommended because it allows you to first test the package locally on the packaging workstation (the computer used to create the package). It also gives you the opportunity to customize the package so that it matches your organization's requirements, for example by changing the installation directory, adding shortcuts, or configuring application-specific settings.

    To do this, click :guilabel:`Edit manually` :red:`(1)`.

    .. figure:: wapt-resources/quickstart-edit_manually.png
      :scale: 75%
      :align: center
      :alt: Edit package manually

      Edit package manually

    This will open your code editor and automatically position it on the :file:`setup.py` file. You will see the following;

    .. code-block::
        
      # -*- coding: utf-8 -*-
      from setuphelpers import *

      r"""
      Usable WAPT package functions: install(), uninstall(), session_setup(), audit(), update_package()

      """
      # Declaring global variables - Warnings: 1) WAPT context is only available in package functions; 2) Global variables are not persistent between calls


      def install():
          # Declaring local variables

          # Installing the software
          print("Installing: naps2-8.3.2-win-x64.msi")
          install_msi_if_needed('naps2-8.3.2-win-x64.msi')

    .. rubric:: Testing locally the installation of the WAPT package
      :name: test_local_install
      :heading-level: 3

    You can then test the installation on your development workstation without making any modifications at first.

    .. figure:: wapt-resources/windows_pyscripter_run-install_menu-item.png
      :align: center
      :alt: PyScripter - Running an install command from the PyScripter console
      
    Once launched, you will see the output in the installation function's prompt, confirming that the installation completed successfully:

    .. code-block::

      Command Line : install "C:\waptdev\tis-naps2_8.3.2_Windows_PROD-wapt\WAPT\.."
      Using config file: C:\Program Files (x86)\wapt\wapt-get.ini
      Installing WAPT files C:\waptdev\tis-naps2_8.3.2_Windows_PROD-wapt
      Installing: naps2-8.3.2-win-x64.msi
      Installing: naps2-8.3.2-win-x64.msi (8.3.2)
      Waiting for key: {89793A72-1596-42A9-8EA6-4E86842830AC} to appear in Windows registry

      Results :

      === install packages ===
        C:\waptdev\tis-naps2_8.3.2_Windows_PROD-wapt | tis-naps2 (8.3.2-1)


    You can now verify that the software is properly installed and functional on the workstation:

    * Check its appearance in the Start Menu by searching for: naps2.
    
    * Launch and run the software.
    
    If everything works as expected, you can proceed to the next step: **uninstallation**.

    .. rubric:: Testing locally the uninstallation of the WAPT package
      :heading-level: 3

    You can then test the uninstall script on your development workstation.

    .. figure:: wapt-resources/windows_pyscripter_run-remove_menu-item.png
      :align: center
      :alt: PyScripter - Running a remove command from the PyScripter console

    Once executed, you will see the following output in the remove() function's prompt, confirming the uninstallation process:

    .. code-block::

      *** Remote Interpreter Reinitialized ***
      Command Line : remove "C:\waptdev\tis-naps2_8.3.2_Windows_PROD-wapt\WAPT\.."
      Using config file: C:\Program Files (x86)\wapt\wapt-get.ini
      Removing C:\waptdev\tis-naps2_8.3.2_Windows_PROD-wapt\WAPT\.. ...

      Waiting for the removal of key: {89793A72-1596-42A9-8EA6-4E86842830AC} from Windows registry
      === Removed packages ===
        tis-naps2


    You can now **verify that the software has been successfully uninstalled** from the workstation:

    * Check that it no longer appears in the Start Menu when searching for: naps2.
    
    If everything works as expected, you can proceed to the next step: **importing the package**.

    .. blue_toggle::
      :titleen: Add a Desktop Shortcut for Naps2 (optionnal)
      :titlefr: Ajouter un raccourci sur le bureau de Naps2 (optionnel)

      Now that both the installation and uninstallation are functional, you can further customize your package by adding additional code. In this example, we will add a desktop shortcut so users don't have to search for the software in the Start Menu.

      To achieve this, we can use the `Windows setuphelpers library <https://www.wapt.fr/apidoc/wapt-2.6/windows/index_setuphelpers.html>`_

      The function we need is :command:`create_desktop_shortcut`, We will add the shortcut creation during the installation process, specifically in the **install()** function.

      Here's how the code looks:

      .. code-block::

        # -*- coding: utf-8 -*-
        from setuphelpers import *

        r"""
        Usable WAPT package functions: install(), uninstall(), session_setup(), audit(), update_package()

        """
        # Declaring global variables - Warnings: 1) WAPT context is only available in package functions; 2) Global variables are not persistent between calls


        def install():
            # Declaring local variables

            # Installing the software
            print("Installing: naps2-8.3.2-win-x64.msi")
            install_msi_if_needed('naps2-8.3.2-win-x64.msi')
            create_desktop_shortcut("NAPS", r'C:\Program Files\NAPS2\NAPS2.exe') #Command for add a desktop shortcut
      
      We have successfully added the creation of a desktop shortcut. However, we must also handle its removal during uninstallation. For this, we use the :command:`remove_desktop_shortcut` command.

      Since the standard uninstallation process does not account for this shortcut (as it is not created in a standard way), we need to add a custom uninstallation step. This will be implemented in the **uninstall()** function.

      **During uninstallation, the uninstall() function will run first, followed by the standard software removal in the remove() function.**

      Here's the updated code:

      .. code-block::
          
        # -*- coding: utf-8 -*-
        from setuphelpers import *

        r"""
        Usable WAPT package functions: install(), uninstall(), session_setup(), audit(), update_package()

        """
        # Declaring global variables - Warnings: 1) WAPT context is only available in package functions; 2) Global variables are not persistent between calls


        def install():
            # Declaring local variables

            # Installing the software
            print("Installing: naps2-8.3.2-win-x64.msi")
            install_msi_if_needed('naps2-8.3.2-win-x64.msi')
            create_desktop_shortcut("NAPS", r'C:\Program Files\NAPS2\NAPS2.exe') # command for add a desktop shortcut

        def uninstall():

            remove_desktop_shortcut('NAPS') #Command for delete the desktop shortcut

      You should now test the functionality by running the installation function and **verifying that the desktop shortcut is created**.

      If necessary, you can review the :ref:`installation section again <test_local_install>`.

      Next, **test the removal of the desktop shortcut using the uninstall()** function.

      .. figure:: wapt-resources/windows_pyscripter_run-uninstall_menu-item.png
        :align: center
        :alt: PyScripter - Running an uninstall command from the PyScripter console
      
      Once the shortcut is removed, you can **proceed with the standard uninstallation using the remove()** function.

      Finally, verify that everything works correctly and import the package to the WAPT server.

    .. rubric:: Importing the New Package
      :heading-level: 3

    * Save your changes and exit the code editor.

    * Return to the WAPT console and import the newly created package:

    **WAPT Console** → package inventory tab → :guilabel:`Import package` :red:`(1)` → :guilabel:`import from file` :red:`(2)`.

    .. figure:: wapt-resources/quickstart-import_package_from_file.png
      :align: center
      :scale: 75%
      :alt: Import package from file
    
      Import package from file

    Now, you need to select the desired package:
    
    
    * By default, a waptdev repository is created at the root of your C: drive. Navigate to: C:\\waptdev :red:`(1)`.
    
    * Select the package repository :red:`(2)`.

    * Click on **Open** :red:`(3)`.

    .. figure:: wapt-resources/quickstart-select-repository-package.png
      :align: center
      :scale: 75%
      :alt: Select package repository
    
      Select package repository

    The package is now available in your Package Inventory.

    .. figure:: wapt-resources/quickstart-check_the_new_package.png
      :align: center
      :scale: 75%
      :alt: import package from file

    * All that remains is to **deploy the package to your test machine** and verify its proper installation and uninstallation.

    You can refer to the previous documentation to review how to :ref:`verify the correct installation of the new package on the workstation <adding_package_dependency>`.

    To check its uninstallation, see the :ref:`dedicated documentation on uninstalling and removing a package dependency <quickstart_uninstall_package>`.

