Difference between revisions of "LazAutoUpdater"
From Lazarus wiki
Jump to navigationJump to searchMinesadorada (talk | contribs) (Added summary section) |
Minesadorada (talk | contribs) (Added sections on how to use and deploy the component) |
||
Line 11: | Line 11: | ||
*You (the developer) have plenty of control over how the component behaves, yet it is simple to use. | *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 | *End-users see the updating process as simple and transparent | ||
− | + | <br> | |
+ | ---- | ||
+ | ===Installation=== | ||
+ | *Download the package source files from the SourceForge Project site (link below) | ||
+ | *If not already installed on your system, install the laz_synapse package (included) | ||
+ | *Install the lazautoupate package (it will be in your 'System' tab) | ||
+ | <br> | ||
+ | ---- | ||
+ | ===Use=== | ||
+ | *Drop the component onto the main form of your application | ||
+ | *Set the SFProjectName property, or in your form.create use code like this: | ||
+ | <syntaxhighlight> | ||
+ | With LazAutoUpdate1 Do | ||
+ | Begin | ||
+ | AppVersion := GetFileVersion; | ||
+ | AppFileWithPath := ParamStrUTF8(0); | ||
+ | SFProjectName := 'lazautoupdate'; | ||
+ | End; | ||
+ | </syntaxhighlight> | ||
+ | *Decide if you want your app to check for updates on startup. If so, in your form.activate handler: | ||
+ | <syntaxhighlight> | ||
+ | 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); | ||
+ | </syntaxhighlight> | ||
+ | *Give the user a chance to update the application. Here's some sample code: | ||
+ | <syntaxhighlight> | ||
+ | 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'); | ||
+ | </syntaxhighlight> | ||
+ | *You don't want the user to close your application in the middle of an update! Use this code in the Form.CloseQuery handler: | ||
+ | <syntaxhighlight> | ||
+ | If LazAutoUpdate1.DownloadInProgress Then | ||
+ | Begin | ||
+ | CanClose := False; | ||
+ | ShowMessage('Please wait. Download is still progress.'); | ||
+ | End; | ||
+ | </syntaxhighlight> | ||
+ | *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) | ||
+ | #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 | ||
+ | <br> | ||
+ | ---- | ||
+ | ===Deploying subsequent updates=== | ||
+ | *Simply repeat items (1-5) in the list above every time you have a new version for your users. | ||
+ | <br> | ||
+ | ---- | ||
=== SourceForge Project=== | === SourceForge Project=== | ||
*[https://sourceforge.net/projects/lazautoupdate/ Project Page] | *[https://sourceforge.net/projects/lazautoupdate/ Project Page] | ||
Line 67: | Line 131: | ||
===In-Application Code=== | ===In-Application Code=== | ||
*Here's what a typical 'Check for Updates' handler would look like: | *Here's what a typical 'Check for Updates' handler would look like: | ||
+ | <syntaxhighlight> | ||
if LazAutoUpdater.NewVersionAvailable then | if LazAutoUpdater.NewVersionAvailable then | ||
begin | begin | ||
Line 85: | Line 150: | ||
[mbOK], 0); | [mbOK], 0); | ||
end; | end; | ||
+ | </syntaxhighlight> | ||
<br> | <br> | ||
---- | ---- |
Revision as of 11:47, 10 August 2014
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 installed on your system, install the laz_synapse package (included)
- 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)
- 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 (1-5) in the list above every time you have a new version for your users.
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
Versions.ini
The format is as follows:
- LazAutoUpdate versions file
[versions] GUI=0.0.2 Module=1.0.0.0
Deploying an update
- In the SourceForge project Files section, make a folder called 'updates'
- Upload 'versions.ini' into it
- Upload the zip file containing your updated EXE and the file 'whatsnew.txt'
- The application installer (Inno Setup?) goes into your Files section as normal
- The Users should only have to download the installer once. All the subsequent versions will go into the /updates folder as above
In-Application Code
- Here's what a typical 'Check for Updates' handler would look like:
if LazAutoUpdater.NewVersionAvailable then
begin
if MessageDlg(Application.Title, 'A new version of ' + Application.Title +
' is available.' + LineEnding + 'Would you like to download it?',
mtConfirmation, [mbYes, mbNo], 0) = mrYes then
if LazAutoUpdater.DownloadNewVersion then
LazAutoUpdater.UpdateToNewVersion
else
MessageDlg(Application.Title,
'Update cancelled', mtInformation, [mbOK], 0);
end
else
begin
MessageDlg(Application.Title,
'Your current version is fully up-to-date',
mtInformation,
[mbOK], 0);
end;
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
- Enable (Console) update.exe to deal with updates to subdirectories of the application
- Write full documentation so that the process is as painless as possible for developers
- Make the LazAutoUpdate itself auto-updateable via SourceForge
...work-in-progress