LazAutoUpdater
From Lazarus wiki
Revision as of 00:02, 21 August 2014 by Minesadorada (talk | contribs) (→Deploying your Application with LazAutoUpdate)
Lazarus Auto-Updater
Summary
- LazAutoUpdater is a visual drop-in component for the Lazarus/FPC IDE to make updating your application easier and simpler.
- It is aimed at Lazarus Windows developers who host their project in SourceForge.
- Drop-in the component, set one property (your sourceforge project name) and call these simple methods:
- If LazAutoUpdate.NewVersionAvailable then...
- LazAutoUpdate.DownloadNewVersion
- LazAutoUpdate.UpdateToNewVersion
..and in your form.activate code:
- LazAutoUpdate.ShowWhatsNewIfAvailable
- You (the developer) have plenty of control over how the component behaves, yet it is simple to use.
- End-users see the updating process as simple and transparent
Installation
- Download the package source files from the SourceForge Project site (link below)
- If not already done, compile the laz_synapse package (no need for installation). It is included in LazAutoUpdater for your convenience.
- Install the lazautoupate package (it will be in your 'System' tab)
Use
- Drop the component onto the main form of your application
- Set the SFProjectName property, or in your form.create use code like this:
With LazAutoUpdate1 Do
Begin
AppVersion := GetFileVersion;
AppFileWithPath := ParamStrUTF8(0);
SFProjectName := 'lazautoupdate';
End;
- Decide if you want your app to check for updates on startup. If so, in your form.activate handler:
If LazAutoUpdate1.NewVersionAvailable Then
MessageDlg(Application.Title, 'A new version of ' + Application.Title +
' is available.' + LineEnding +
'Click ''Check for new version'' in Help menu to update', mtConfirmation,
[mbOK], 0);
- Give the user a chance to update the application. Here's some sample code:
LazAutoUpdate1.SFProjectName := 'lazautoupdate';
If LazAutoUpdate1.NewVersionAvailable Then
If LazAutoUpdate1.DownloadNewVersion Then
Begin
If MessageDlg(Application.Title, 'Download Succeeded. Click OK to update',
mtInformation, [mbOK], 0) = 1 Then
LazAutoUpdate1.UpdateToNewVersion;
End
Else
ShowMessage('Sorry, download of new version failed')
Else
ShowMessage('Sorry, no new version is available');
- You don't want the user to close your application in the middle of an update! Use this code in the Form.CloseQuery handler:
If LazAutoUpdate1.DownloadInProgress Then
Begin
CanClose := False;
ShowMessage('Please wait. Download is still progress.');
End;
- This gives you the 'bare bones' of the update code for your application. As you can see, it's all pretty automatic and simple.
Deploying your Application with LazAutoUpdate
- Make a folder in your SourceForge project files called 'updates' (from the Files root)
- Make a ZIP file containing the latest version of the executable and a 'whatsnew.txt' (which will be shown to the user)
- If the CopyTree property=true then the zip file can contain folders and their contents, which will be unzipped and copied en massse to the application directory
- Upload the ZIP file to the SourceForge /updates folder
- Make a 'versions.ini' file with the GUI='n.n.n.n' version number that matches the version number in your updated executable
- Upload the versions.ini to your SourceForge /updates folder
- In your installer, be sure that it makes a local /updates folder (relative to the installation destination). This is important for permissions in Windows.
- In your installer, be sure to include the file 'updatehm.exe'. It should install to the same folder as your application
Deploying subsequent updates
- Simply repeat items (2-5) in the list above every time you have a new version for your users.
Public Methods List
- Function NewVersionAvailable: Boolean;
- Function DownloadNewVersion: Boolean;
- Function UpdateToNewVersion: Boolean;
- Procedure ShowWhatsNewIfAvailable;
Non-published Properties list
- GUIOnlineVersion: String
- ModuleOnlineVersion: String
- ReturnCode: Integer
- DownloadInprogress: Boolean
- AppFileWithPath: String
- AppVersion: String
- LastError: String;
Deploying multiple updates in a single project
- By default, the ZipFilename is the same as your application, but you can set it to a unique value, and deploy it to your SFProject Files/updates irectory
- Each application to be updated should have a unique name for the versions.ini file. Set the VersionsINIFilename property.
In case the download takes to long
- VersionCountLimit property determines how long LazAutoUpdate will check for a new version before timing out.
- DownloadCountLimit property determines how long LazAutoUpdate will try downloading the new version before timing out.
Versions.ini
The format is as follows:
;LazAutoUpdate versions file [versions] GUI=0.0.2
- The file is small so that it is very quick to download
SourceForge Project
Workflow
(Technical explanation)
The Laz AutoUpdater workflow for updating a running application is as follows:
- App downloads a small 'version.ini' file from sourceforge with version info (it can do this at start-up)
- App compares with its own internal version
- If new version available
- App deletes any contents of local /updates folder
- App downloads then unzips it from Sourceforge into a local /updates folder
- App uses TAsyncProcess to start the console updater.exe, passing it the name of the file to be updated in the command line
- updater.exe copies a downloaded 'whatsnew.txt' into the App folder and enters Sleep for a few seconds
- Meanwhile App has entered loop checking whether a 'whatsnew.txt' file has been copied into it's directory
- App detects 'whatsnew.txt' and Closes. (in other words the TProcess has started successfully)
- Updater copies /updates/UpdatedApp to App directory.
- Updater uses TProcess to start the updated app
- On Form.Show, App displays 'whatsnew.txt' then deletes it
The User sees:
- Dialog: 'There's a new version of xxx available. Would you like to download it?' Yes/No
- If Yes clicked:
- Download happens in the background (via a background thread) Optional 'download counter' is shown to indicate progress.
- User is prevented from closing the app whilst the download is in progress (in Form.CloseQuery)
- Dialog: 'The update is downloaded. Click OK to install it and restart xxx now' OK
- User clicks OK
- A console (DOS window in Windows) opens automatically and the Application closes. The console says 'Please wait updating xxx'
- After a couple of seconds the console disappears, and the new version of the App starts
- As soon as the main window is shown, a 'What's New' info box is shown with an OK button
- User clicks OK button, and never sees the info again
Roadmap
- Wrap as much as possible into a single visual component that a developer can drop onto their form, and set properties ...Done
- Enable (Console) update.exe to deal with multiple files to update ...Done (CopyTree property)
- Enable (Console) update.exe to deal with updates to subdirectories of the application ...Done (CopyTree property)
- Write full documentation so that the process is as painless as possible for developers ...underway
- Linux testing/implementation ...Done