Documentation
¶
Overview ¶
Package velopack provides a Go interface to the Velopack library for managing software updates and distribution on desktop.
Index ¶
- Variables
- func DownloadUpdatesInTheBackground(source string)
- func Run(a App)
- type App
- type Asset
- type AssetType
- type LocatorConfig
- type Restart
- type Silent
- type SourceCustomCallbacks
- type UnsafeProcessID
- type UpdateInfo
- type UpdateManager
- func (up *UpdateManager) AppID() string
- func (up *UpdateManager) ApplyUpdatesAndRestart(update either[*UpdateInfo, *Asset], args ...string) error
- func (up *UpdateManager) CheckForUpdates() (*UpdateInfo, UpdateStatus, error)
- func (up *UpdateManager) CurrentlyInstalledVersion() string
- func (up *UpdateManager) DownloadUpdates(update_info *UpdateInfo, progress func(progress uint)) error
- func (up *UpdateManager) IsPortable() bool
- func (up *UpdateManager) UpdatePendingRestart() (*Asset, bool)
- func (up *UpdateManager) WaitForExitThenApplyUpdates(update either[*UpdateInfo, *Asset], ...) error
- type UpdateOptions
- type UpdateSource
- type UpdateStatus
Constants ¶
This section is empty.
Variables ¶
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 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 )