The [alphaUpdate] command.

Introduction

The alphaUpdate command manages Alpha's software updates. It can query Alpha's download area to detect if a newer version is available and it can transfer the latest distribution to the user's machine.
This command needs a valid internet connection to transfer the data.
Typically, you would use the [alphaUpdate version] command to get the version of the latest release or download all the information available about this release using the [alphaUpdate info] command, then download the released archive using the [alphaUpdate download] command.

Synopsis

The formal syntax of the [alphaUpdate] command is:

alphaUpdate subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

AlphaUpdate subcommands

The [download] subcommand

This subcommand lets you download the latest released version of Alpha. The complete syntax is:

    alphaUpdate download ?-command completionProc? ?-dest dir? \
	   ?-progress progressProc? ?-timeout num? ?-url url? ?-version vers?

The command runs asynchronously and terminates immediately, returning an empty string. If a download is already in progress, the command does nothing.
The download is performed, by default, in the user's Downloads folder. Another destination may be specified using the -dest option.
The -command option lets you specify a Tcl proc to invoke when the download has completed. The completionProc proc takes a single argument which is empty in case of success or contains a description of the error otherwise.
The -timeout option lets you specify a timeout in seconds. By default, there is a 3600 seconds timeout.
The -progress option lets you specify a Tcl proc which is invoked repeatedly during the download. The progressProc proc takes two arguments corresponding to the number of bytes already written and the total number of bytes expected respectively.
The -version option lets you specify the version number of the latest release. This can be obtained with the [alphaUpdate version] command. If this option is not specified, Alpha will attempt to get it automatically.
The -url option lets you specify the URL of the distribution. By default, Alpha knows where to find it and you should not have to use this option.

The [getInfo] subcommand

This subcommand retrieves, over the network, the information related to the latest released version of Alpha. The complete syntax is:

    alphaUpdate getInfo ?-command completionProc? ?-dest dir? ?-timeout num? ?-url url?

The command runs asynchronously and terminates immediately, returning an empty string. It downloads a file called release_info.json containing informations related to the latest release of Alpha. This file is in JSON format and has keys such as version, size, date, md5 and sha1 checksums, etc.
If a download is already in progress, this command does nothing.
The -command option lets you specify a Tcl proc to invoke when the task has completed. This proc takes a single argument which is empty in case of success or contains a description of the error otherwise.
The -dest option lets you specify a destination folder where the file will be copied. By default, it is the user's Downloads folder. Note that if a file called release_info.json already exists there, it will be replaced by the new one.
The -timeout option lets you specify a timeout in seconds. By default, there is a 30 seconds timeout.
The -url option lets you specify the URL of the release info file. By default, Alpha knows where to find the file and you should not have to use this option.

The [install] subcommand

This subcommand installs a new version of Alpha. The complete syntax is:

    alphaUpdate install ?-r? ?-d dest? file

It attempts to install an archive containing a distribution of Alpha. This archive is a file with a .dmg or .dmg.zip extension which may have been obtained with the [alphaUpdate download] command or by a direct download.
The -r option tells to restart the application after the installation.
The -d option specifies a destination folder where to install the application. The default is /Applications. If the destination folder is the parent folder of the currently running Alpha, the command tells it to quit before attempting to install the distribution. Otherwise, if the destination folder already contains an application Alpha, the installation occurs only if this application is not running.

The [stop] subcommand

This subcommand cancels a download operation. The complete syntax is:

    alphaUpdate stop ?(application|info)?

The third argument specifies if you want to cancel a download started with the [alphaUpdate download] or the [alphaUpdate info] command respectively (the default is application). This immediately stops the download.

The [version] subcommand

This subcommand retrieves, over the network, the version number of the latest released version of Alpha. The complete syntax is:

    alphaUpdate version ?-timeout num?

The command operates synchronously. There is, by default, a 30 seconds timeout but another value may be specified (in seconds) using the -timeout option. A negative value is interpreted as an infinite timeout but this is unwise as it can freeze the application.

Examples

Here are a few basic examples which can be executed one by one in the Tcl Shell (⌘Y) in Alpha:

Welcome to Alpha's AlphaTcl shell.
«» set lastvers [alphaUpdate version]
«» alphaUpdate getInfo
«» alphaUpdate download -version $lastvers

One may define a completion proc to be invoked when the download is complete:

proc infoCompProc {{error ""}} {
    if {$error eq ""} {
        alertnote "Download of release info completed"
    } else {
        alertnote "Download error: $error"
    } 
}
alphaUpdate getInfo -dest [file normalize ~/Desktop] -command infoCompProc

Last updated 2020-10-21 07:12:07