velopack

package
v0.0.1358 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 9, 2025 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package velopack provides a Go interface to the Velopack library for managing software updates and distribution on desktop.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrPlatformNotSupported = errors.New("platform not supported by velopack") // returned when !((windows || linux || darwin) && (arm64 || amd64))
	ErrDisabledCGO          = errors.New("cgo is disabled")                    // returned when cgo is disabled, which is required for velopack.
)

Functions

func DownloadUpdatesInTheBackground

func DownloadUpdatesInTheBackground(source string)

DownloadUpdatesInTheBackground should be called in a separate goroutine to download updates automatically, if there is an update, it will be applied on the next application startup. Uses slog for leveled logging. Calls Run. Only checks for updates once.

func Run

func Run(a App)

Run helps you to handle app activation events correctly. This should be used as early as possible in your application startup code. (eg. the beginning of main() or wherever your entry point is). This function will not return in some cases. Do not call this function more than once in your application.

Types

type App

type App struct {
	AutoApplyOnStartup bool           // sets whether to automatically apply downloaded updates on startup.
	Args               []string       // Overrides the command line arguments used by VelopackApp.
	Locator            *LocatorConfig // Sets the locator configuration to use for the VelopackApp.

	HookFirstRun  func(psz_app_version string) // This hook is triggered when the application is started for the first time after installation.
	HookRestarted func(psz_app_version string) // This hook is triggered when the application is restarted by Velopack after installing updates.

	// WARNING: Windows hooks are run during critical stages of Velopack operations.
	// Your code will be run and then the process will exit.
	// If your code has not completed within 30 seconds, it will be terminated.
	// Only supported on windows; On other operating systems, these callbacks will never be called.
	WindowsHookAfterInstall    func(psz_app_version string)
	WindowsHookBeforeUninstall func(psz_app_version string)
	WindowsHookBeforeUpdate    func(psz_app_version string)
	WindowsHookAfterUpdate     func(psz_app_version string)

	Logger func(psz_level, psz_message string) // Will be called for all log messages generated by the Velopack library.
}

App helps you to handle app activation events correctly. This should be passed to Run as early as possible in your application startup code. (eg. the beginning of main() or wherever your entry point is)

type Asset

type Asset struct {
	PackageID     string    // The name or ID of the package containing this release.
	Version       string    // The version of this release.
	Type          AssetType // The type of asset (eg. "Full" or "Delta").
	Filename      string    // The filename of the update package containing this release.
	SHA1          string    // The SHA1 checksum of the update package containing this release.
	SHA256        string    // The SHA256 checksum of the update package containing this release.
	Size          uint64    // The size in bytes of the update package containing this release.
	NotesMarkdown string    // The release notes in markdown format, as passed to Velopack when packaging the release. This may be an empty string.
	NotesHTML     string    // The release notes in HTML format, transformed from Markdown when packaging the release. This may be an empty string.
	// contains filtered or unexported fields
}

Asset is an individual Velopack asset, could refer to an asset on-disk or in a remote package feed.

type AssetType

type AssetType string

AssetType (eg. "Full" or "Delta").

const (
	AssetTypeFull  AssetType = "Full"
	AssetTypeDelta AssetType = "Delta"
)

type LocatorConfig

type LocatorConfig struct {
	RootAppDir       string // The root directory of the current app.
	UpdateExePath    string // The path to the Update.exe binary.
	PackagesDir      string // The path to the packages' directory.
	ManifestPath     string // The current app manifest.
	CurrentBinaryDir string // The directory containing the application's user binaries.
	IsPortable       bool   //  Whether the current application is portable or installed.
	// contains filtered or unexported fields
}

LocatorConfig for locating the current app important paths (eg. path to packages, update binary, and so forth).

type Restart

type Restart []string

Restart and specify optional command line arguments to pass to the new process when it's restarted (can be passed to [UpdateManager.WaitExitThenApplyUpdates]).

type Silent

type Silent bool

Silent can be passed to [UpdateManager.WaitExitThenApplyUpdates] to attempt to apply the update without showing any UI.

type SourceCustomCallbacks

type SourceCustomCallbacks struct {

	// ReleaseFeedFunc should return the raw JSON string of the release.json feed.
	ReleaseFeedFunc func(psz_releases_name string) json.RawMessage
	/*
	   DownloadAssetFunc is expected to download the provided asset to the provided local file path.
	   Throughout, you can use the progress callback to write progress reports (0-100). The function should
	   return true if the download was successful, false otherwise.
	*/
	DownloadAssetFunc func(asset *Asset, local_path string, progress_callback func(progress int16)) bool
	// contains filtered or unexported fields
}

type UnsafeProcessID

type UnsafeProcessID int

UnsafeProcessID can be passed to [UpdateManager.WaitExitThenApplyUpdates] to specify a process ID to wait for before applying updates. This method is unsafe because it does not necessarily wait for any / the correct process to exit before applying updates. If this is 0, the updater will not wait for any process to exit before applying updates (Not Recommended).

type UpdateInfo

type UpdateInfo struct {
	TargetFullRelease *Asset   // The available version that we are updating to.
	BaseRelease       *Asset   // The base release that this update is based on. This is only available if the update is a delta update.
	DeltasToTarget    []*Asset // The list of delta updates that can be applied to the base version to get to the target version.
	/*
		True if the update is a version downgrade or lateral move (such as when switching channels to the same version number).
		In this case, only full updates are allowed, and any local packages on disk newer than the downloaded version will be
		deleted.
	*/
	IsDowngrade bool
	// contains filtered or unexported fields
}

UpdateInfo holds information about the current version and pending updates, such as how many there are, and access to release notes.

type UpdateManager

type UpdateManager struct {
	// contains filtered or unexported fields
}

UpdateManager is an opaque handle.

func NewUpdateManager

func NewUpdateManager(psz_url_or_path string, options ...updateOptionsAndLocatorConfig) (*UpdateManager, error)

NewUpdateManager creates a new UpdateManager instance from the given update location with optional UpdateOptions and LocatorConfig.

func NewUpdateManagerFromSource

func NewUpdateManagerFromSource(source *UpdateSource, options ...updateOptionsAndLocatorConfig) (*UpdateManager, error)

NewUpdateManagerFromSource creates a new UpdateManager instance using the given UpdateSource.

func (*UpdateManager) AppID

func (up *UpdateManager) AppID() string

AppID returns the currently installed app id.

func (*UpdateManager) ApplyUpdatesAndRestart

func (up *UpdateManager) ApplyUpdatesAndRestart(update either[*UpdateInfo, *Asset], args ...string) error

ApplyUpdatesAndRestart will exit your app immediately, apply updates, and then optionally relaunch the app using the specified restart os.Args. If you need to save state or clean up, you should do that before calling this method. The user may be prompted during the update, if the update requires additional frameworks to be installed etc. You can check if there are pending updates by checking UpdatePendingRestart.

func (*UpdateManager) CheckForUpdates

func (up *UpdateManager) CheckForUpdates() (*UpdateInfo, UpdateStatus, error)

CheckForUpdates Checks for updates. If there are updates available, this method will return an UpdateInfo object containing the latest available release, and any delta updates that can be applied if they are available.

func (*UpdateManager) CurrentlyInstalledVersion

func (up *UpdateManager) CurrentlyInstalledVersion() string

CurrentlyInstalledVersion returns the currently installed version of the app.

func (*UpdateManager) DownloadUpdates

func (up *UpdateManager) DownloadUpdates(update_info *UpdateInfo, progress func(progress uint)) error

DownloadUpdates downloads the specified updates to the local app packages directory. Progress is reported back to the caller via an optional callback. This function will acquire a global update lock so may fail if there is already another update operation in progress.

  • If the update contains delta packages and the delta feature is enabled
  • this method will attempt to unpack and prepare them.
  • If there is no delta update available, or there is an error preparing delta packages, this method will fall back to downloading the full version of the update.

func (*UpdateManager) IsPortable

func (up *UpdateManager) IsPortable() bool

IsPortable returns whether the app is in portable mode. On Windows this can be true or false. On MacOS and Linux this will always be true.

func (*UpdateManager) UpdatePendingRestart

func (up *UpdateManager) UpdatePendingRestart() (*Asset, bool)

UpdatePendingRestart returns an asset if there is an update downloaded which still needs to be applied. You can pass this asset to [UpdateManager.WaitExitThenApplyUpdates] to apply the update.

func (*UpdateManager) WaitForExitThenApplyUpdates

func (up *UpdateManager) WaitForExitThenApplyUpdates(update either[*UpdateInfo, *Asset], options ...upto3[Silent, Restart, UnsafeProcessID]) error

WaitForExitThenApplyUpdates this will launch the Velopack updater and tell it to wait for this program to exit gracefully.

  • You should then clean up any state and exit your app. The updater will apply updates and then
  • (if Restart specified) restart your app. The updater will only wait for 60 seconds before giving up.

type UpdateOptions

type UpdateOptions struct {

	/*
		Allows UpdateManager to update to a version that's lower than the current version (i.e. downgrading).
		This could happen if a release has bugs and was retracted from the release feed, or if you're using
		ExplicitChannel to switch channels to another channel where the latest version on that
		channel is lower than the current version.
	*/
	AllowVersionDowngrade bool
	/*
		This option should usually be left None/NULL**.
		Overrides the default channel used to fetch updates.
		The default channel will be whatever channel was specified on the command line when building this release.
		For example, if the current release was packaged with '--channel beta', then the default channel will be 'beta'.
		This allows users to automatically receive updates from the same channel they installed from. This options
		allows you to explicitly switch channels, for example if the user wished to switch back to the 'stable' channel
		without having to reinstall the application.
	*/
	ExplicitChannel string
	/*
		Sets the maximum number of deltas to consider before falling back to a full update.
		The default is 10. Set to a negative number (eg. -1) to disable deltas.
	*/
	MaximumDeltasBeforeFallback int32
	// contains filtered or unexported fields
}

UpdateOptions to customise the behaviour of UpdateManager.

type UpdateSource

type UpdateSource struct {
	// contains filtered or unexported fields
}

UpdateSource is an opaque handle, to either a FileSource, HTTPSource or _CUSTOM_.

func NewSourceCustomCallback

func NewSourceCustomCallback(callbacks SourceCustomCallbacks) (*UpdateSource, error)

Create a new _CUSTOM_ update source with user-provided callbacks to fetch release feeds and download assets. You can report download progress using [UpdateSource.ReportProgress].

func NewSourceFile

func NewSourceFile(psz_file_path string) (*UpdateSource, error)

NewSourceFile creates a new FileSource update source for the given local directory path containing updates.

func NewSourceHTTP

func NewSourceHTTP(psz_http_url string) (*UpdateSource, error)

NewSourceHTTP creates a new HttpSource update source for the given HTTP URL of a remote update server.

type UpdateStatus

type UpdateStatus int

UpdateStatus represents the result of a call to check for updates.

const (
	UpdateError       UpdateStatus = -1
	UpdateAvailable   UpdateStatus = 0
	NoUpdateAvailable UpdateStatus = 1
	RemoteIsEmpty     UpdateStatus = 2
)