App descriptor: Version 1 and 2 (OBSOLETE)

WARNING: this page refers to an obsolete descriptor format - which is still opened but MoonDeploy, but now deprecated. Please consult the latest documentation

Introduction

An app descriptor declares that a version of the application is available at a given base URL, from which its packages (that is, one or more zip archives containing the application files) will be downloaded.

The app descriptor must be a JSON file called App.moondeploy, whereas its companion zip archives can be created as you wish - for example, by Gradle's application plugin.

Descriptor format

The structure is fairly simple - let's see and comment an example where all the fields are employed:

{
	"DescriptorVersion": "1.0",

	"Name":    "My application",
	"Version": "1.5",
	"SkipUpdateCheck": false,

	"Description": "A simple application to download",
	"IconPath": {
		"windows": "mainIcon.ico",
		"*": "mainIcon.png"
	},

	"BaseURL": "https://github.com/giancosta86/test/releases/latest",
	"Publisher": "Gianluca Costa",

	"PackageVersions": {
      "alpha.zip": "1.3",
      "beta.zip": ""
    },

	"CommandLine": {
		"windows": ["bin\\myApp.bat"],
		"*": ["bash", "bin/myApp"]    
  },

	"SkipPackageLevels": 1
}

The fields can be in any order (as it is a JSON file), and can be briefly described as follows:

• DescriptorVersion: refers to MoonDeploy's engine version. For now, it should always be set to 1.0. Required

• Name: application name. Used when resolving the application's directory and shown in desktop shortcuts as well. Required

• Version: the application version related to this descriptor. Versions have the format:

  MAJOR.MINOR.BUILD.RELEASE

  where every component is an integer number >= 0, and only MAJOR is mandatory. Required

  This field is paramount because it can be used by MoonDeploy to update an application and its files whenever the application starts: if the version has not changed, no update is performed.

• SkipUpdateCheck: if set to true, will prevent the application from checking for updates on startup. Optional (defaults to false)

• Description: application's description. Employed, for example, when creating desktop shortcuts. Optional (defaults to an empty string)

• Icon path: relative path (within the directory containing the application's files) of the application icon, consulted when creating a desktop shortcut. It is organized as a map:

  • its keys are the operating system name according to Go's runtime (in particular, windows, linux and darwin). A special key is *, which always matches any operating system not declared in the map.

  • the corresponding values must be relative paths (for example, bin/mainIcon.png)

  Optional. If the entire Icon path is missing, or if the current operating system does not match any of the declared keys, MoonDeploy's default icon will be used.

  A note on consistency: usually, Windows requires .ico icons, whereas Linux desktop environments usually require .png icons. Which is why Icon path is organized as a dictionary.

• BaseURL: the URL (HTTP or HTTPS) from which the packages will be downloaded. It generally refers to the URL where the descriptor itself will reside. Furthermore, it should be HTTPS, for enhanced security. Mandatory

  NOTE: if BaseURL has the following format: https://github.com/USER_NAME/REPO_NAME/releases/latest, then MoonDeploy will automatically call GitHub's API to resolve the actual URL of the latest descriptor for the given repository.

• Publisher: the publisher will be shown at the application's first run. Mandatory

• PackageVersions: contains a map of package name - version elements, to be interpreted as follows:

  • package name is the actual relative path of a zip archive residing under baseURL, usually along with the descriptor itself. Such zip files contain the application's files

  • version is a package-specific version following the format described above, or an empty string

  This field is important when a newer version of the application is found (that is, a descriptor having a Version newer than the Version of the descriptor saved in the app gallery at the end of the previous app execution):

  0. For every package in the new descriptor:

  > if its version is an empty string *or* if the old version is an empty string *or* if it was not present in the old descriptor *or* the package version in the new descriptor is newer than the package version in the old descriptor, then download it
  

  0. If all the packages in the new descriptor are to be downloaded, the whole local directory containing the application files is deleted and created anew

  This field is actually optional, but it would default to an empty dictionary (therefore, it would end up deleting the application's files directory). This might be interesting to create applications not strictly relying on own files - for example, for customizations of existing applications.

• CommandLine: a map similar to IconPath (see above), but its values are command-line arrays: each array has an executable as its first item (which might also be a program in the PATH, such ash bash), followed by zero or more arguments. In the example, you can see a typical pattern working for the programs created by Gradle's application plugin. This field is optional, but an application won't run if the current OS doesn't match a key of the map.

• SkipPackageLevels: when extracting a package, this parameter defines the number of directories that will be ignored in the archive tree during extraction. For example, if a tool like Gradle's application plugin creates an archive whose tree starts with the directory "APPNAME VERSION", you can avoid decompressing such root directory and only retrieve its internal files by setting SkipPackageLevels: 1. Optional (defaults to 0).

Consistency considerations

The fields of a descriptor can change from a version to the other, EXCEPT Name and BaseURL, which uniquely define an application.