Package App

This section covers the steps required to package an application for distribution. The packaging process is used to create a zip file that contains the application and all necessary dependencies (or configuration, depending on packaging method).

Packaging Requirements

Before packaging an application, it is important to ensure the application is in a clean state and that the intended application and extensions are included in the build. The following steps should be taken to ensure the application is ready for packaging:

Cleaning Up

Packages are created from the contents of the _build directory. Before building an application for packaging, it is recommended to ensure only the intended application and extensions are included in the build. This can be verified by checking the following three locations:

  1. premake5.lua - Ensure only the intended application is defined in the -- Apps section. The applications defined in this section are defined as define_app("my_company.my_app.kit"). If there are applications defined here that you do not intend to include in the package, delete the define_app line for that application.

  2. repo.toml - Ensure only the intended application is defined in the [repo_precache_exts] section. The applications defined in this section are defined within the apps array (e.g. apps = ["${root}/source/apps/my_company.my_app.kit"]). If there applications defined here that you do not intend to include in the package, delete the .kit file from the apps array.

  3. source/ - Within the source directory, it is important that only the applications (.kit files) that exist in the source/apps directory are those defined in the premake5.lua file. In addition, any extensions within the source/extensions that are not dependencies of the application to be packaged should be removed.

Finally, before performing a build, it is recommended to clean the current build directory if one exists. This can be done by running the build -c command from the root of the project.

Linux:

./repo.sh build -c

Windows:

.\repo.bat build -c

Release Build

From a clean application state (as described above), you can now perform a release build. A release build is the default for the tooling provided by the kit-app-template repository. This build will prepare the application and its dependencies for packaging.

Linux:

./repo.sh build

Windows:

.\repo.bat build

Set Package Version

The Application version can be set in tools/VERSION.md. This version will be used by default in the final application package name in the following way:

{packag_name}@{version}-{config}.zip

Fat Package

A “fat” package includes everything to run the app: Kit Kernel and all Extensions. This package type should be used when the goal is to not require an end user to have to download anything at the time of installation. This type of package is suitable for internal sharing between teams, and in environments that do not have access to public repositories - such as air gapped organizations.

Create a Fat Package

A fat package is the default package type created by the repo package command.

Linux:

./repo.sh package --name {desired_package_name}

Windows:

.\repo.bat package --name {desired_package_name}

A package of the specified name, version, and configuration will be created within the _build/packages directory.

Launch a Fat Package

Because a fat package contains everything needed to run the application and is intended for distribution within development teams the tooling provided by the kit-app-template repository is capable of launching the application directly from the package.

Linux:

./repo.sh launch --package {path_to_package}

Windows:

.\repo.bat launch --package {path_to_package}

Note

A note for Windows users: Due to path length limitations on Windows it is recommended to move the package to a location closer to the root of the drive before attempting to launch the application. This will help avoid issues with the path length when launching the application from the package.

Thin Package

A “thin” package is the required packaging type for wider distribution. Thin packages contain the bare minimum required for an installation to be possible - but requires the ability to download Kit Kernel and extensions when the app is installed.

Installed thin packaged apps make use of shared storage of Kit Kernel and extensions. This approach optimizes the use of local storage - only downloading components that have not already been downloaded by other thin packaged apps. This package type is not suitable for air gapped environments.

Create a Thin Package

Linux:

./repo.sh package --name {desired_package_name} --thin

Windows:

.\repo.bat package --name {desired_package_name} --thin

A package of the specified name, version, and configuration will be created within the _build/packages directory.

Note that compared to the “fat package”, this thin package does not contain a kit or extscache directory. This makes the package a lot smaller - but also means that users will need to download those “on demand” during installation if they are not already installed from some prior installation.

Launch a Thin Package

Organizations distributing thin packages are encouraged to leverage the thin package application as a component within their own installer (or installation process). The repo launch command DOES NOT support launching thin packages directly. Instead, the package should be included in the organization’s installer and launched from there.

Below are the operations that need to be performed to complete the installation of, and launch a thin package:

  1. Download the thin package

  2. Extract .zip file to the desired location

  3. Run the pull_kit_sdk script to download the Kit Kernel and extensions

    Linux:

    ./{path_to_extracted_thin_package}/pull_kit_sdk.sh

    Windows:

    .\{path_to_extracted_thin_package}\pull_kit_sdk.bat

  4. Launch the application

    Linux:

    ./{path_to_extracted_thin_package}/{my_company.my_app}.kit.sh

    Windows:

    .\{path_to_extracted_thin_package}\{my_company.my_app}.kit.bat

Note

A note for Windows users: Due to path length limitations on Windows, it is recommended to move the package to a location closer to the root of the drive before attempting to launch the application. This will help avoid issues with the path length when launching the application.