Difference between revisions of "LazAutoUpdater"
From Free Pascal wiki
Jump to navigationJump to searchMinesadorada (talk | contribs) m (Minor tweaks) |
Minesadorada (talk | contribs) (Update) |
||
Line 1: | Line 1: | ||
==Lazarus Auto-Updater== | ==Lazarus Auto-Updater== | ||
===Summary=== | ===Summary=== | ||
− | *LazAutoUpdater is a visual drop-in component for the Lazarus/FPC IDE to make updating your application easier and | + | *LazAutoUpdater is a visual drop-in component for the Lazarus/FPC IDE to make updating your application easier and smarter. |
− | *It is aimed at Lazarus Windows and Linux developers who host their project in SourceForge. | + | *It is aimed at Lazarus Windows and Linux developers who host their project in SourceForge or GitHub. |
− | *Drop-in the component, set one property (your sourceforge project name) and call | + | *Drop-in the component, set one property (your sourceforge project name, ot GitHub properties) and call one simple method: |
− | + | **LazAutoUpdate.AutoUpdate | |
− | |||
− | |||
− | |||
− | **LazAutoUpdate. | ||
*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 | ||
− | *Tested and developed in Windows | + | *Tested and developed in Windows 10 64/32-bit and Linux Mint 64/32-bit |
<br> | <br> | ||
− | [[File: | + | [[File:lauobjinsp1.jpg]] |
− | [[File: | + | [[File:lauobjinsp2.jpg]] |
<br> | <br> | ||
---- | ---- | ||
Line 23: | Line 19: | ||
---- | ---- | ||
===Installation=== | ===Installation=== | ||
− | *Download the | + | * Download the Windows setup file or the linuxbinaries zip |
− | * | + | * Windows: Install, Linux: Unbzip in a spare folder |
− | * | + | * Use the UpdatePack to make and distribute your update files |
− | * | + | * Use the LazAutoUpdate component to add update functionality to your Lazarus app |
− | **'''You will need to distribute updatehm(.exe) with your application for LazAutoUpdate to work correctly''' | + | **'''You will need to distribute updatehm<os>(.exe) with your application for LazAutoUpdate to work correctly''' |
<br> | <br> | ||
---- | ---- | ||
Line 33: | Line 29: | ||
*Drop the component onto the main form of your application | *Drop the component onto the main form of your application | ||
*Set the SFProjectName property to your SourceForge project name (the same text as appears in the URL for your project page) | *Set the SFProjectName property to your SourceForge project name (the same text as appears in the URL for your project page) | ||
+ | *or.. Set the GitHub properties | ||
*Decide if you want your app to check for updates on startup. If so, in your form.activate handler: | *Decide if you want your app to check for updates on startup. If so, in your form.activate handler: | ||
<syntaxhighlight> | <syntaxhighlight> | ||
Line 64: | Line 61: | ||
End; | End; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | * | + | *'''Or let the component do all this for you - just use''' |
<syntaxhighlight> | <syntaxhighlight> | ||
LazAutoUpdate1.AutoUpdate; | LazAutoUpdate1.AutoUpdate; | ||
</syntaxhighlight> | </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. | *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=== | ===Deploying your Application with LazAutoUpdate=== | ||
− | # | + | # Use UpdatePack to manage the process |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<br> | <br> | ||
− | + | [[File:updatepack1.png]] | |
− | |||
− | |||
− | |||
− | |||
− | [[File: | ||
<br> | <br> | ||
+ | [[File:updatepack2.png]] | ||
---- | ---- | ||
===Using auOtherSourceFilename and auOtherSourceURL=== | ===Using auOtherSourceFilename and auOtherSourceURL=== | ||
Line 100: | Line 85: | ||
**AppFileWithPath | **AppFileWithPath | ||
**AppVersion | **AppVersion | ||
− | *By setting these properties dynamically (perhaps via a menu) you can enable the user to update multiple applications hosted on a SourceForge project site (or any site using auOther settings - see above) | + | *By setting these properties dynamically (perhaps via a menu) you can enable the user to update multiple applications hosted on a SourceForge/GitHub project site (or any site using auOther settings - see above) |
*Here's example code to use LazAutoUpdate to download then run an application. | *Here's example code to use LazAutoUpdate to download then run an application. | ||
Line 140: | Line 125: | ||
---- | ---- | ||
===Deploying multiple updates in a single project=== | ===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 | + | * By default, the ZipFilename is the same as your application, but you can set it to a unique value, and deploy it to your Online Files/updates irectory |
* Each application to be updated should have a unique name for the versions.ini file. Set the VersionsINIFilename property. | * Each application to be updated should have a unique name for the versions.ini file. Set the VersionsINIFilename property. | ||
<br> | <br> | ||
Line 167: | Line 152: | ||
The Laz AutoUpdater workflow for updating a running application is as follows: | 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 downloads a small 'version.ini' file from sourceforge or github with version info (it can do this at start-up) |
*App compares with its own internal version | *App compares with its own internal version | ||
*If new version available | *If new version available | ||
**App deletes any contents of local /updates folder | **App deletes any contents of local /updates folder | ||
− | **App downloads then unzips it from | + | **App downloads then unzips it from the web 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 | *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 | *updater.exe copies a downloaded 'whatsnew.txt' into the App folder and enters Sleep for a few seconds |
Revision as of 15:48, 18 January 2017
Lazarus Auto-Updater
Summary
- LazAutoUpdater is a visual drop-in component for the Lazarus/FPC IDE to make updating your application easier and smarter.
- It is aimed at Lazarus Windows and Linux developers who host their project in SourceForge or GitHub.
- Drop-in the component, set one property (your sourceforge project name, ot GitHub properties) and call one simple method:
- LazAutoUpdate.AutoUpdate
- 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
- Tested and developed in Windows 10 64/32-bit and Linux Mint 64/32-bit
Download
- LazAutoUpdate source code can be downloaded from the SourceForge project site
- The Lazarus OnlinePackager also contains LazAutoUpdate
Installation
- Download the Windows setup file or the linuxbinaries zip
- Windows: Install, Linux: Unbzip in a spare folder
- Use the UpdatePack to make and distribute your update files
- Use the LazAutoUpdate component to add update functionality to your Lazarus app
- You will need to distribute updatehm<os>(.exe) with your application for LazAutoUpdate to work correctly
Use
- Drop the component onto the main form of your application
- Set the SFProjectName property to your SourceForge project name (the same text as appears in the URL for your project page)
- or.. Set the GitHub properties
- 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;
- Or let the component do all this for you - just use
LazAutoUpdate1.AutoUpdate;
- 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
- Use UpdatePack to manage the process
File:updatepack1.png
File:updatepack2.png
Using auOtherSourceFilename and auOtherSourceURL
- When ProjectType is set to auOther, LazAutoUpdate will use these properties for all the Methods. See example application in the SVN archive.
Making a generic installer/updater
- Once a LazAutoUpdate component has been dropped onto a form, it can be used for multiple updates, downloads etc.
- For a generic installer/updater you need to set:
- VersionsINIFilename
- ZipFilename
- AppFileWithPath
- AppVersion
- By setting these properties dynamically (perhaps via a menu) you can enable the user to update multiple applications hosted on a SourceForge/GitHub project site (or any site using auOther settings - see above)
- Here's example code to use LazAutoUpdate to download then run an application.
- The zipped files for the application (including 'whatsnew.txt') and the file 'mywizzyapp.ini' are located in the /updates subdirectory of the SourceForge project 'mywizzy'
- The executable 'updatehm.exe' is in the same directory as your updater app
- The user would download a small InnoSetup installer with just the online installer/updater, which in turn would download the main application and supporting files.
procedure TForm1.Button1Click(Sender: TObject);
begin
Application.Title:='My whizzy app';
LazAutoUpdate1.SFProjectname:='mywizzy';
LazAutoUpdate1.VersionsININame:='mywizzyapp.ini';
LazAutoUpdate1.ZipfileName:='mywizzyapp.zip';
LazAutoUpdate1.AppFileWithPath:='mywizzyapp.exe';
LazAutoUpdate1.Appversion:='0.0.0.0';
If LazAutoUpdate1.DownloadNewVersion then
LazAutoUpdate1.UpdateToNewVersion;
end;
Public Methods List
- Function NewVersionAvailable: Boolean;
- Function DownloadNewVersion: Boolean;
- Function UpdateToNewVersion: Boolean;
- Procedure ShowWhatsNewIfAvailable;
- Procedure AutoUpdate;
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 Online 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 or github 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 the web 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