Difference between revisions of "LazAutoUpdater"

From Free Pascal wiki
m (Minor tweaks)
(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 simpler.
+
*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 these simple methods:
+
*Drop-in the component, set one property (your sourceforge project name, ot GitHub properties) and call one simple method:
**If LazAutoUpdate.NewVersionAvailable then...
+
**LazAutoUpdate.AutoUpdate
**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.
 
*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 Vista 32-bit and Linux Mint 64-bit
+
*Tested and developed in Windows 10 64/32-bit and Linux Mint 64/32-bit
 
<br>
 
<br>
[[File:objinsp screenshot.png]]
+
[[File:lauobjinsp1.jpg]]
[[File:lazautoupdate_2.png]]
+
[[File:lauobjinsp2.jpg]]
 
<br>
 
<br>
 
----
 
----
Line 23: Line 19:
 
----
 
----
 
===Installation===
 
===Installation===
*Download the package source files from the SourceForge Project site (link below)
+
* Download the Windows setup file or the linuxbinaries zip
*If not already done, compile the laz_synapse package (no need for installation). It is included in LazAutoUpdater for your convenience.
+
* Windows: Install, Linux: Unbzip in a spare folder
*Install the lazautoupate package (it will be in your 'System' tab)
+
* Use the UpdatePack to make and distribute your update files
*Compile updatehm.lpi for your system architecture (or download a compiled version from the SourceForge site)
+
* 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>
*(from v0.0.9) Or let the component do all this for you - just use
+
*'''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===
#Make a folder in your SourceForge project files called 'updates' (from the Files root)
+
# Use UpdatePack to manage the process
#Make a ZIP file containing the latest version of the executable and a 'whatsnew.txt' (which will be shown to the user)
 
##Important: If there is no 'whatsnew.txt' in the Zip then LazAutoUpdate will not work!
 
##If the CopyTree property=true then the zip file can contain folders and their contents, which will be unzipped and copied en masse to the application directory (with folder structure intact)
 
#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>
 
<br>
----
+
[[File:updatepack1.png]]
===Deploying subsequent updates===
 
*Simply repeat items (2-5) in the list above every time you have a new version for your users.
 
*A GUI is available on the SourceForge site to create and manage this process:
 
 
 
[[File:laupdatepack1.png]]
 
 
<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 SFProject Files/updates irectory
+
* 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 Sourceforge into a 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
 
*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


lauobjinsp1.jpg lauobjinsp2.jpg


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

  1. 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



Minesadorada