Skip to content

Label Variables Reference

Jump to bottom
Adam Codega edited this page Nov 10, 2023 · 5 revisions

In Installomator we call a given software installation for a “label”. A label is part if a case statement in zsh, and need to contain a name in the beginning and “;;” in the end.

Building a new label?

See CONTRIBUTING.md for how to contribute new software labels to the project.

If you need a new piece of software to be supported by Installomator, start out by reading our various tutorials for this.

In short get the URL of the download, and give it to buildLabel.sh that will try to figure out the easy part of the label creation. But various web servers use different methods for these downloads, and various developers are versioning their software different, and our tutorials is trying to illustrate that.

Reference guide to labels

There are four required variables that needs to be part of the label, some variables that are strongly recommended, and several optional variables.

Required Variables

The script requires four pieces of information to download and install an application:

spotify)
    name="Spotify"
    type="dmg"
    downloadURL="https://download.scdn.co/Spotify.dmg"
    expectedTeamID="2FNC3A47ZF"
    ;;

The four required variables are

  • name: The display name of the installed application without the .app extensions.

  • type: The type of installation. Possible values:

    • dmg: application in disk image file (drag'n drop installation)
    • pkg: flat pkg download
    • zip: application in zip archive (zip extension)
    • tbz: application in tbz archive (tbz extension)
    • pkgInDmg: a pkg file inside a disk image
    • pkgInZip: a pkg file inside a zip
    • appInDmgInZip: an app in a dmg file that has been zip'ed

  • downloadURL: The URL from which to download the archive. The URL can be generated by a series of commands, for example when you need to parse an xml file for the latest URL. (See labels bbedit, desktoppr, or omnigraffle for examples.) Sometimes version differs between Intel and Apple Silicon versions. (See labels brave, obsidian, omnidisksweeper, or notion.)

  • expectedTeamID: The 10-character Developer Team ID with which the application or pkg is signed and notarized.

    Obtain the team ID by running:

    • Applications (in dmgs or zips) spctl -a -vv /Applications/BBEdit.app

    • Installation Packages (pkg) spctl -a -vv -t install ~/Downloads/desktoppr-0.2.pkg

Strongly Recommended Variables

  • appNewVersion (optional, but very highly recommended):

Version of the downloaded software.

When given, it will be compared to installed version. This can prevent unnecessary downloads and installations.

Installomator does not compare the version for being greater or lesser, but only for being different.

It is not always easy or possible to determine the latest version. Sometimes this is listed on the downloads page, sometimes in other places. There is no general strategy to determine it and this is often the hardest part of build a new label. (See labels abstract, bbedit, brave, desktoppr, googlechrome, or omnidisksweeper.)

The value must match a version that can be read from the installed app.

We want this variable for all applications and tools where it is possible. We will question new PRs without this field, and require a reason for not including it.

  • versionKey (optional): When the version is being compared to the locally installed app, sometimes we need another field than CFBundleShortVersionString. Often CFBundleVersion is the right one, but techically it could be another field. It's usually dependant on what number the web sites most easily returns.

  • packageID (optional, but recommended for pkgs without an app) This variable is for pkg bundle IDs. Very usefull if a pkg only install command line tools, or the like that does not install an app. (See label desktoppr, golang, installomator_st, odrive, or teamviewerhost.)

Optional Variables

Depending on the application or pkg there are a few more variables you can or need to set. Many of these are derived from the required variables, but may need to be set manually if those derived values do not work.

  • archiveName: (optional) The name of the downloaded file. When not given the archiveName is set to $name.$type

  • appName: (optional) File name of the app bundle in the dmg to verify and copy (include the .app). When not given, the appName is set to $name.app. This is also the name of the app that will get reopned, if we closed any blockingProcesses (see further down)

  • appCustomVersion : (optional) This function can be added to your label, if a specific custom mechanism has to be used for getting the installed version. (Instead of checking the .app version on disk, or checking a pkg receipt) Commonly used to check the output of a binary command, like /usr/bin/MyApp --version. Example: See labels zulujdk11, zulujdk13, zulujdk15.

  • targetDir: (optional) dmg or zip: Applications will be copied to this directory. Default value is '/Applications' for dmg and zip installations. pkg: targetDir is used as the install-location. Default is '/'.

  • blockingProcesses: (optional) Array of process names that will block the installation or update. If no blockingProcesses array is given the default will be: blockingProcesses=( $name ) When a package contains multiple applications, all should be listed, e.g: blockingProcesses=( "Keynote" "Pages" "Numbers" ) When a workflow has no blocking processes or it should not be checked (if the pkg will handle this), use blockingProcesses=( NONE )

  • pkgName: (optional, only used for dmgInPkg and dmgInZip) File name of the pkg file inside the dmg or zip. When not given the pkgName is set to $name.pkg.

  • updateTool, updateToolArguments: When Installomator detects an existing installation of the application, and the updateTool variable is set then $updateTool $updateArguments Will be run instead of of downloading and installing a complete new version. Use this when the updateTool does differential and optimized downloads. e.g. msupdate (see various Microsoft labels).

  • updateToolRunAsCurrentUser: When this variable is set (any value), $updateTool will be run as the current user. Default is unset and

  • CLIInstaller:

  • CLIArguments: If the downloaded dmg is actually an installer that we can call using CLI, we can use these two variables for what to call. We need to define name for the installed app (to be version checked), as well as installerTool for the installer app (if named differently that name. Installomator will add the path to the folder/disk image with the binary, and it will be called like this: $CLIInstaller $CLIArguments For most installations CLIInstaller should contain the installerTool for the CLI call (if it’s the same). We can support a whole range of other software titles by implementing this. (See label adobecreativeclouddesktop.)

  • installerTool: Introduced as part of CLIInstaller. If the installer in the DMG or ZIP is named differently than the installed app, then this variable can be used to name the installer that should be located after mounting/expanding the downloaded archive. (See label adobecreativeclouddesktop.)

  • curlOptions (optional): If the downloadURL cannot work directly using curl-command, then we can usually add some options to that command, and the server will return what we need. For instance if the server automatically detects platform due to header fields, we might need to add a header field -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.1 Safari/605.1.15". This variable should be an array, so it should be surrounded by (). Se labels mmhmm and mochatelnet, or canva for even more headings in a curl request.

Clone this wiki locally