updater

README

updater

The update window of MyGo apps, in the manner of Sparkle: it checks for updates in the background, shows the release notes of a new version and offers to install it, skip it or remind the user later, downloads it with a progress bar and relaunches the app into it. It is all Go, with no npm package.

import "github.com/egoist/mygo/plugins/updater"

mygo.Use(updater.Plugin) // or updater.New(updater.Options{Interval: ..., Icon: ...})

and "Check for Updates…" in the app's menu:

{Label: "My App", Submenu: []*mygo.MenuItem{
	{Role: mygo.RoleAbout},
	updater.MenuItem(),
	mygo.Separator(),
	{Role: mygo.RoleQuit},
}},

Apps whose windows all show native UI use native.Plugin (package github.com/egoist/mygo/plugins/updater/native) instead: the same window drawn in native UI, with no webview.

It speaks the user's language (English, Chinese, Dutch, French, German, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Ukrainian), and Options.Strings changes its texts or adds languages.

The app must be built with updates: see auto-updates. The plugin's documentation lists the options, the languages and the preferences (SetAutomaticChecks, SetAutomaticDownloads, and OnChange to hear them change) apps can offer.

Documentation

Overview

Package updater is the update window of MyGo apps, in the manner of Sparkle on macOS. It checks for updates in the background, once a day by default, and when a new version is out it shows its release notes and offers to install it, skip it or remind the user later. Installing downloads the update with a progress bar, then offers to relaunch the app into it.

mygo.Use(updater.Plugin)

Add "Check for Updates…" to the app's menu, after About on macOS:

{Label: "My App", Submenu: []*mygo.MenuItem{
	{Role: mygo.RoleAbout},
	updater.MenuItem(),
	...
}},

It is built on mygo.Updater, so the app must be built with updates (see the updates guide). Builds that cannot update themselves, such as development builds and apps installed by a package manager, never check in the background, and say why when the user checks.

The window speaks the user's language when the plugin has it, and Options.Strings changes its texts or adds languages (see Strings).

The user's choices are kept in updater.json in the app's user data directory: whether to check automatically (AutomaticChecks), whether to install updates without asking (AutomaticDownloads, the checkbox of the update window), the version they skipped and when the app last checked. OnChange tells the app when they changed, for a preferences page.

Index

• Variables
• func AutomaticChecks() bool
• func AutomaticDownloads() bool
• func CheckForUpdates()
• func LastCheck() time.Time
• func MenuItem() *mygo.MenuItem
• func New(opts Options) mygo.Plugin
• func OnChange(fn func()) (off func())
• func SetAutomaticChecks(on bool)
• func SetAutomaticDownloads(on bool)
• type Options
• type Strings

Variables

var Plugin = New(Options{})

Plugin is the plugin with the default options.

Functions

func AutomaticChecks

func AutomaticChecks() bool

AutomaticChecks reports whether the app checks for updates in the background.

func AutomaticDownloads

func AutomaticDownloads() bool

AutomaticDownloads reports whether updates found in the background are installed without asking: they run the next time the app starts. The update window offers to turn it on.

func CheckForUpdates

func CheckForUpdates()

CheckForUpdates checks for updates as the user asked, from a menu item or a button: the update window shows right away, says when the app is up to date or the check failed, and shows updates the user skipped. It returns at once; while a check is under way it brings its window to the front.

func LastCheck

func LastCheck() time.Time

LastCheck returns when the app last checked for updates successfully, or the zero time.

func MenuItem

func MenuItem() *mygo.MenuItem

MenuItem returns a "Check for Updates…" item that calls CheckForUpdates.

func New

func New(opts Options) mygo.Plugin

New returns the plugin with options. Use one of them only.

func OnChange

func OnChange(fn func()) (off func())

OnChange calls fn on the main thread after the choices of the user or the time of the last check changed: a check succeeded, the user answered the update window (its checkbox, Skip This Version), or the app called SetAutomaticChecks or SetAutomaticDownloads. A preferences page that shows AutomaticChecks, AutomaticDownloads or LastCheck reads them again. It returns a function that removes fn.

func SetAutomaticChecks

func SetAutomaticChecks(on bool)

SetAutomaticChecks turns checking for updates in the background on or off, for a preference of the app.

func SetAutomaticDownloads

func SetAutomaticDownloads(on bool)

SetAutomaticDownloads turns installing updates found in the background without asking on or off.

Types

type Options

type Options struct {
	// Interval between automatic checks. Zero means a day.
	Interval time.Duration
	// DisableAutomaticChecks turns automatic checks off until
	// SetAutomaticChecks turns them on, for apps that ask the user first or
	// only check from the menu.
	DisableAutomaticChecks bool
	// Icon is the PNG image shown in the update window. Nil means icon.png
	// among the app's resources, the default icon of `mygo build`, when
	// there is one.
	Icon []byte
	// Language of the window, a language tag such as "fr" or "zh-Hant".
	// Empty means the user's (App.Locale): the plugin shows the language
	// that matches it best among its own and those of Strings, else
	// English.
	Language string
	// Strings change the texts of the window by language tag, or add
	// languages. Their empty fields keep the plugin's texts, else the
	// English ones:
	//
	//	Strings: map[string]updater.Strings{
	//		"en": {Install: "Update Now"},
	//		"sv": {Title: "Programuppdatering", ...},
	//	}
	Strings map[string]Strings
}

Options configure the plugin.

type Strings

type Strings struct {
	// Title of the window: "Software Update".
	Title string
	// MenuItem is the label of MenuItem: "Check for Updates…".
	MenuItem string

	Checking string // "Checking for updates…"
	Cancel   string
	OK       string

	UpToDate string // "You’re up to date!"
	// UpToDateMessage: the app's name and version.
	UpToDateMessage string

	Unavailable string // "Updates Unavailable"
	// UnavailableMessage explains that the app cannot write where it is
	// installed: the app's name.
	UnavailableMessage string
	// DevelopmentBuild explains that development builds do not update.
	DevelopmentBuild string

	Error        string // "Update Error!"
	CheckError   string // "An error occurred while checking for updates…"
	InstallError string // "An error occurred while installing the update…"

	// Available: the app's name.
	Available string
	// AvailableMessage: the app's name, the new version and the running
	// one.
	AvailableMessage   string
	ReleaseNotes       string // "Release Notes:"
	AutomaticDownloads string // the checkbox
	Skip               string // "Skip This Version"
	RemindLater        string // "Remind Me Later"
	Install            string // "Install Update"

	Downloading string // "Downloading update…"
	// Progress: the size downloaded and the whole size, as Megabytes.
	Progress string
	// Megabytes: a number, such as 12.3, with the decimal mark of the
	// language.
	Megabytes  string
	Installing string // "Installing update…"

	Ready string // "Ready to Relaunch"
	// ReadyMessage: the app's name and the new version.
	ReadyMessage string
	Later        string
	Relaunch     string // "Relaunch Now"
}

Strings are the texts of the update window in one language. The plugin has them in English, Chinese (zh-Hans, zh-Hant), Dutch, French, German, Italian, Japanese, Korean, Polish, Portuguese (pt-BR), Russian, Spanish, Turkish and Ukrainian, and Options.Strings changes them or adds languages.

Some are formats, whose arguments are listed: indexed verbs such as %[2]s let a language order them as it needs.