LazAutoUpdater: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Summary
2	2
3	3		- LazAutoUpdate is a visual drop-in component for the Lazarus/FPC IDE to make updating your application from an online source easier and smarter.
4	4		- When making an app for distribution, coding an update process for users can be a bother, yet users appreciate the facility (so long as it's not forced on them!) and support is easier if you know that the user always has the most up-to-date version of your app. LazAutoUpdate is designed to integrate well with your SourceForge or GitHub version control ensuring a trouble-free experience for you and your users.
5	5		- LazAutoUpdate downloads via a background thread so the user can continue using your app without interruption
6	6		- This means for example, your app can 'check for updates' at startup without the app becoming unresponsive.
7	7		- It is aimed at Lazarus Windows and Linux developers who host their project in SourceForge or GitHub.
8	8		- Drop-in the component, set a couple of properties (your SourceForge project name, or some GitHub properties) and call one simple method:
9	9		- LazAutoUpdate.AutoUpdate
10	10		- You (the developer) have plenty of control over how the component behaves, yet it is simple to use.
11	11		- End-users see the updating process as simple and transparent
12	12		- Tested and developed in Windows 10 64/32-bit and Linux 64/32-bit
13	13
14	14		![](/wiki-images/9/94/Lauobjinsp1.jpg) ![](/wiki-images/1/18/Lauobjinsp2.jpg)
15	15
16	16		------------------------------------------------------------------------
17	17
18	18		## Download
19	19
20	20		- LazAutoUpdate suite installer (Windows) or zip (Linux) can be downloaded from the [SourceForge project site](http://sourceforge.net/projects/lazautoupdate/)
21	21		- The Lazarus OnlinePackager also contains LazAutoUpdate
22	22
23	23		------------------------------------------------------------------------
24	24
25	25		## Installation
26	26
27	27		- Download the Windows setup file or the linuxbinaries zip
28	28		- Windows: Install, Linux: Unzip in a spare folder
29	29		- Use the UpdatePack to make and distribute your update files
30	30		- Use the LazAutoUpdate component to add update functionality to your Lazarus app
31	31		- You will need to distribute updatehm\<os\>(.exe) with your application for LazAutoUpdate to work correctly
32	32		- Don't forget to set VersionInfo numbers in your Lazarus Project options
33	33
34	34		------------------------------------------------------------------------
35	35
36	36		## Example application
37	37
38	38		- In the download package is the project 'TestApp'
39	39		- Compile and run TestApp (remembering to compile+copy the appropriate console updater (updatehm_xxx) to the executable folder)
40	40		- It should update itself 'out-of-the-box'
41	41		- Check out the source code of TestApp to get an idea of how to use LazAutoUpdate to its full potential
42	42
43	43		------------------------------------------------------------------------
44	44
45	45		## Internationalisation
46	46
47	47		- i8n: LazAutoUpdate has a 'locale' folder with all the .po files needed for translation. The base language is English
48	48
49	49		------------------------------------------------------------------------
50	50
51	51		## Use
52	52
53	53		- Set a version number for your app in Project/Options/Versioninfo
54	54		- Drop the component onto the main form of your application
55	55		- Set the SFProjectName property to your SourceForge project name (the same text as appears in the URL for your project page)
56	56		- or.. Set the GitHub properties:
57	57		- GitHubProjectname: Username or Organisation
58	58		- GitHubRepositoryName: Your project/repository
59	59		- GitHubBranchOrTag: 'master' for the root or the GitHub Branch name or Tag name
60	60		- In both cases set the UpdatesFolder to the location of your update files (you can leave it blank)
61	61		- Use the UpdatePack to upload your app to the internet (SourceForge, GitHub etc)
62	62		- Then let the component take care of the details. Just use (perhaps as a Help menu item 'Check for updates')
63	63
64	64		``` pascal
65	65		LazAutoUpdate1.AutoUpdate;
66	66		```
67	67
68	68		- You don't want the user to close your application in the middle of an update! Use this code in the Form.CloseQuery handler:
69	69
70	70		``` pascal
71	71		If LazAutoUpdate1.DownloadInProgress Then
72	72		Begin
73	73		CanClose := False;
74	74		ShowMessage('Please wait. Download is still progress.');
75	75		End;
76	76		```
77	77
78	78		- After an update your app can show 'What's new' automatically. Put this line into your Form's OnShow event:
79	79
80	80		``` pascal
81	81		LazAutoUpdate1.ShowWhatsNewIfAvailable;
82	82		```
83	83
84	84		- This gives you the 'bare bones' of the update code for your application. As you can see, it's all pretty automatic and simple.
85	85
86	86		### More control
87	87
88	88		- Decide if you want your app to check for updates on startup. If so, in your form.activate handler:
89	89
90	90		``` pascal
91	91		If LazAutoUpdate1.NewVersionAvailable Then
92	92		MessageDlg(Application.Title, 'A new version of ' + Application.Title +
93	93		' is available.' + LineEnding +
94	94		'Click ''Check for new version'' in Help menu to update', mtConfirmation,
95	95		[mbOK], 0);
96	96		```
97	97
98	98		- If you do not use the AutoUpdate method, you have control over the update process in stages via the functions:
99	99
100	100		``` pascal
101	101		If LazAutoUpdate1.NewVersionAvailable then ..... else ...
102	102		```
103	103
104	104		``` pascal
105	105		If LazAutoUpdate1.DownloadNewVersion then ..... else ...
106	106		```
107	107
108	108		``` pascal
109	109		If LazAutoUpdate1.UpdateToNewVersion then ..... else ...
110	110		```
111	111
112	112		### Debugging
113	113
114	114		- If you set
115	115
116	116		``` pascal
117	117		LazAutoUpdate1.DebugMode:=TRUE;
118	118		```
119	119
120	120		then you can use the built-in OnDebugEvent method to log activity:
121	121
122	122		``` pascal
123	123		procedure TForm1.LazAutoUpdate1DebugEvent(Sender: TObject; lauMethodName,
124	124		lauMessage: string);
125	125		begin
126	126		// Use TEventLog
127	127		Logger.Info('('+lauMethodName+') - ' + lauMessage);
128	128		end;
129	129		```
130	130
131	131		There are also events fired: OnDownloaded and OnNewVersionAvailable and the property LastError with info that you might use for debugging.
132	132
133	133		------------------------------------------------------------------------
134	134
135	135		## Support
136	136
137	137		- LazAutoUpdate is supported via the Lazarus forum [here](http://forum.lazarus.freepascal.org/index.php/topic,25444.0.html).
138	138
139	139		------------------------------------------------------------------------
140	140
141	141		## License
142	142
143	143		- LazaAutoUpdate: LGPLv2 (same as Lazarus components)
144	144		- Update Pack: GPLv2
145	145
146	146		------------------------------------------------------------------------
147	147
148	148		## Deploying your Application with LazAutoUpdate
149	149
150	150		- Use UpdatePack to manage the process.
151	151		- UpdatePack is a GUI application that makes the update files accurately and quickly, and even gives you the corresponding LazAutoUpdate code for your app.
152	152		- It uses 'profiles' that enable you to deploy future updates by simply updating the version number and clicking 'Create Update Pack'.
153	153		- Your app users will benefit from having the latest version of your software always available
154	154		- When testing, remember your testing app should be a lower version number than your 'update' app stored online :)
155	155		- If you want to make up (or add to) the update zip yourself, it should contain the App and the text file 'whatsnew.txt' as a minimum.
156	156
157	157		![](/wiki-images/d/d4/Updatepack1.jpg)
158	158
159	159		![](/wiki-images/3/30/Updatepack2.jpg)
160	160
161	161		------------------------------------------------------------------------
162	162
163	163		## Using auOtherSourceFilename and auOtherSourceURL
164	164
165	165		- When ProjectType is set to auOther, LazAutoUpdate will use these properties for all the Methods. See example application in the SVN archive.
166	166
167	167		------------------------------------------------------------------------
168	168
169	169		## LazAutoUpdate Systray Application
170	170
171	171		- This can be found in the /trayicon folder of the source.
172	172		- When this is run, it sits in the system tray area and silently checks for updates via a schedule (developer and user configurable)
173	173		- If it finds a new version it pops up a notification to the user to update:
174	174		- If the app not running, the update is done silently in the background
175	175		- If the app is running it closes it and then does the update. The app will then restart
176	176		- Systray updater has a right-click menu:
177	177		- Configure:
178	178		- The user can edit the schedule - each app has a 'profile'
179	179		- Runs at startup (Windows):
180	180		- The systray loads silently at each Windows boot
181	181		- Systray (lautraynotify) picks up entries from apps that use LazAutoupdate automatically, so it never needs to be configured - simply installed once and forgotten.
182	182		- The schedule is flexible, from once every day to once every month
183	183		- The UpdatePack takes care of producing the systray configuration file for your app. The default is to check every Monday at 9am.
184	184		- The systray app works in both Windows and Linux - all you need to do is deploy it.
185	185
186	186		------------------------------------------------------------------------
187	187
188	188		## Making a generic online installer/updater
189	189
190	190		- Once a LazAutoUpdate component has been dropped onto a form, it can be used for multiple updates, downloads etc. (see '/testinstaller' in package source)
191	191		- For a generic installer/updater you need to set:
192	192		- VersionsINIFilename
193	193		- ZipFilename
194	194		- AppFileWithPath
195	195		- AppVersion
196	196		- 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)
197	197
198	198		- Here's example code to use LazAutoUpdate to download then run an application.
199	199		- 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'
200	200		- The executable 'updatehm(ostype)(.exe)' is in the same directory as your updater app
201	201		- ostype=\[win32\\|win64\\|linux32\\|linux64\]
202	202		- Windows ext=(.exe)
203	203		- The user would download a small InnoSetup installer with just the online installer/updater, which in turn would download application(s) and supporting files.
204	204		- Of course, the "installer" could be your main application, with sister applications installable via a menu or some such.
205	205
206	206		``` pascal
207	207		procedure TForm1.Button1Click(Sender: TObject);
208	208		// Uses SysUtils,LazFileUtils,ulazautoupdate etc..
209	209		Var sDirectoryToInstallTo: string;
210	210		begin
211	211		sDirectoryToInstallTo := ProgramDirectory + 'installed';
212	212		Application.Title:='My whizzy app'
213	213		LazAutoUpdate1.WorkingMode := lauInstall;
214	214		LazAutoUpdate1.ProjectType := auSourceForge;
215	215		LazAutoUpdate1.SFProjectname:='mywizzy';
216	216		LazAutoUpdate1.VersionsININame:='mywizzyapp.ini';
217	217		LazAutoUpdate1.ZipfileName:='mywizzyapp.zip';
218	218		LazAutoUpdate1.AppFileWithPath := sDirectoryToInstallTo + DirectorySeparator + 'mywizzyapp.exe';
219	219		// Our responsibility to make the folder
220	220		if not DirectoryExistsUTF8(sDirectoryToInstallTo) then ForceDirectoriesUTF8(sDirectoryToInstallTo);
221	221		LazAutoUpdate1.Appversion:='0.0.0.0';
222	222		If LazAutoUpdate1.DownloadNewVersion then
223	223		begin
224	224		If LazAutoUpdate1.UpdateToNewVersion then
225	225		begin
226	226		LazAutoUpdate1.ShortCut.Category := scUtility;
227	227		LazAutoUpdate1.ShortCut.Target := LazAutoUpdate1.AppFileWithPath;
228	228		LazAutoUpdate1.ShortCut.ShortcutName := Application.Title;
229	229		LazAutoUpdate1.MakeShortCut; // makes a desktop shortcut and a Start menu entry in Windows
230	230		end;
231	231		end;
232	232		end;
233	233		```
234	234
235	235		- You can then programatically run the installed app easily enough:
236	236
237	237		``` pascal
238	238		// Uses asyncprocess
239	239		procedure TForm1.RunInstalledApp;
240	240		var
241	241		AProcess: TAsyncProcess;
242	242		begin
243	243		if not FileExistsUTF8(LazAutoUpdate1.AppFileWithPath) then
244	244		begin
245	245		ShowMessageFmt('%s does not exist! Install it first.',
246	246		[LazAutoUpdate1.AppFileWithPath]);
247	247		Exit;
248	248		end;
249	249		AProcess := TAsyncProcess.Create(nil);
250	250		try
251	251		AProcess.Executable := LazAutoUpdate1.AppFileWithPath;
252	252		AProcess.Execute;
253	253		finally
254	254		Aprocess.Free;
255	255		end;
256	256		end;
257	257		```
258	258
259	259		------------------------------------------------------------------------
260	260
261	261		## Public Methods List
262	262
263	263		- Function NewVersionAvailable: Boolean;
264	264		- Function DownloadNewVersion: Boolean;
265	265		- Function UpdateToNewVersion: Boolean;
266	266		- Procedure ShowWhatsNewIfAvailable;
267	267		- Procedure AutoUpdate;
268	268		- function AppIsActive
269	269		- procedure ResetAppVersion;
270	270
271	271		------------------------------------------------------------------------
272	272
273	273		## Non-published Properties list
274	274
275	275		- GUIOnlineVersion: String
276	276		- ReturnCode: Integer
277	277		- DownloadInprogress: Boolean
278	278		- AppFileWithPath: String
279	279		- AppVersion: String
280	280		- LastError: String;
281	281		- DebugMode: boolean
282	282		- LCLVersion: string
283	283		- WidgetSet: string
284	284		- FPCVersion: string
285	285		- LastCompiled: string
286	286		- TargetOS: string
287	287		- WindowsAdminCheck: boolean
288	288
289	289		------------------------------------------------------------------------
290	290
291	291		## Deploying multiple updates in a single project
292	292
293	293		- 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
294	294		- Each application to be updated should have a unique name for the versions.ini file. Set the VersionsINIFilename property.
295	295
296	296		------------------------------------------------------------------------
297	297
298	298		## In case the download takes to long
299	299
300	300		- VersionCountLimit property determines how long LazAutoUpdate will check for a new version before timing out.
301	301		- DownloadCountLimit property determines how long LazAutoUpdate will try downloading the new version before timing out.
302	302
303	303		------------------------------------------------------------------------
304	304
305	305		## Versions.ini
306	306
307	307		The format is as follows:
308	308
309		-	~~`;LazAutoUpdate versions file`\~~
310		-	~~`[versions]`\~~
311		-	~~`GUI=0.0.2`~~
	309	+	```text
	310	+	;LazAutoUpdate versions file
	311	+	[versions]
	312	+	GUI=0.0.2
	313	+	```
312	314
313	315		- The file is small so that it is very quick to download
314	316
315	317		------------------------------------------------------------------------
316	318
317	319		## Source Code and latest versions
318	320
319	321		- [Project Page](https://sourceforge.net/projects/lazautoupdate/)
320	322		- [SVN HTTP Checkout](https://svn.code.sf.net/p/lazarus-ccr/svn/components/lazautoupdate/latest_stable)
321	323
322	324		------------------------------------------------------------------------
323	325
324	326		## Security
325	327
326	328		### Windows 10
327	329
328	330		- Windows 10 security will not allow a non-admin user to update applications from the internet (unless it's a Windows Store App). This is a sensible policy in my opinion, and LazAutoUpdate adheres to it.
329	331		- If an 'ordinary user' tries to update an app using LazAutoUpdate, all will go smoothly until the final 'Update app' phase. At that point LazAutoUpdate will pop up a dialog informing the user that an administrator account is needed for the actual update.
330	332		- For an 'admin user', LazAutoUpdate will pop up a UAC dialog (the same as any installer) and proceed upon clicking 'yes' to do the update.
331	333		- If you wish to circumvent this (perhaps with a manifest) LazAutoUpdate has the public property 'WindowsAdminCheck' which you can set to FALSE and avoid the dialog.
332	334
333	335		### Linux
334	336
335	337		- Linux will do the update without even showing the update console, and the user gets a seamless experience.
336	338
337	339		------------------------------------------------------------------------
338	340
339	341		## Workflow
340	342
341	343		(Technical explanation)
342	344
343	345		The Lazarus Auto-Updater workflow for updating a running application is as follows:
344	346
345	347		- App downloads a small 'version.ini' file from sourceforge or github with version info (it can do this at start-up)
346	348		- App compares with its own internal version
347	349		- If new version available
348	350		- App deletes any contents of local /updates folder
349	351		- App downloads then unzips it from the web into a local /updates folder
350	352		- App uses TAsyncProcess to start the console updater.exe, passing it the name of the file to be updated in the command line
351	353		- updater.exe copies a downloaded 'whatsnew.txt' into the App folder and enters Sleep for a few seconds
352	354		- Meanwhile App has entered loop checking whether a 'whatsnew.txt' file has been copied into it's directory
353	355		- App detects 'whatsnew.txt' and Closes. (in other words the TProcess has started successfully)
354	356		- Updater copies /updates/UpdatedApp to App directory.
355	357		- Updater uses TProcess to start the updated app
356	358		- On Form.Show, App displays 'whatsnew.txt' then deletes it
357	359
358	360		The User sees:
359	361
360	362		- Dialog: 'There's a new version of xxx available. Would you like to download it?' Yes/No
361	363		- If Yes clicked:
362	364		- Download happens in the background (via a background thread) Optional 'download counter' is shown to indicate progress.
363	365		- User is prevented from closing the app whilst the download is in progress (in Form.CloseQuery)
364	366		- Dialog: 'The update is downloaded. Click OK to install it and restart xxx now' OK
365	367		- User clicks OK
366	368		- A console (DOS window in Windows) opens automatically and the Application closes. The console says 'Please wait updating xxx'
367	369		- After a couple of seconds the console disappears, and the new version of the App starts
368	370		- As soon as the main window is shown, a 'What's New' info box is shown with an OK button
369	371		- User clicks OK button, and never sees the info again
370	372
371	373		------------------------------------------------------------------------
372	374
373	375		Minesadorada
374	376
375	377		---
376	378		From the Free Pascal wiki, page "LazAutoUpdater", as it stood on 2022-01-07 after a change by FTurtle, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history