LazAutoUpdater: what changed

Revision 1 to 2. 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		-	~~<figure>~~
158		-	~~<img src="updatepack1.jpg" title="updatepack1.jpg" />~~
159		-	~~<figcaption>updatepack1.jpg</figcaption>~~
160		-	~~</figure>~~
	157	+	![](/wiki-images/d/d4/Updatepack1.jpg)
161	158
162		-	~~<figure>~~
163		-	~~<img src="updatepack2.jpg" title="updatepack2.jpg" />~~
164		-	~~<figcaption>updatepack2.jpg</figcaption>~~
165		-	~~</figure>~~
	159	+	![](/wiki-images/3/30/Updatepack2.jpg)
166	160
167	161		------------------------------------------------------------------------
168	162
169	163		## Using auOtherSourceFilename and auOtherSourceURL
170	164
171	165		- When ProjectType is set to auOther, LazAutoUpdate will use these properties for all the Methods. See example application in the SVN archive.
172	166
173	167		------------------------------------------------------------------------
174	168
175	169		## LazAutoUpdate Systray Application
176	170
177	171		- This can be found in the /trayicon folder of the source.
178	172		- When this is run, it sits in the system tray area and silently checks for updates via a schedule (developer and user configurable)
179	173		- If it finds a new version it pops up a notification to the user to update:
180	174		- If the app not running, the update is done silently in the background
181	175		- If the app is running it closes it and then does the update. The app will then restart
182	176		- Systray updater has a right-click menu:
183	177		- Configure:
184	178		- The user can edit the schedule - each app has a 'profile'
185	179		- Runs at startup (Windows):
186	180		- The systray loads silently at each Windows boot
187	181		- Systray (lautraynotify) picks up entries from apps that use LazAutoupdate automatically, so it never needs to be configured - simply installed once and forgotten.
188	182		- The schedule is flexible, from once every day to once every month
189	183		- The UpdatePack takes care of producing the systray configuration file for your app. The default is to check every Monday at 9am.
190	184		- The systray app works in both Windows and Linux - all you need to do is deploy it.
191	185
192	186		------------------------------------------------------------------------
193	187
194	188		## Making a generic online installer/updater
195	189
196	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)
197	191		- For a generic installer/updater you need to set:
198	192		- VersionsINIFilename
199	193		- ZipFilename
200	194		- AppFileWithPath
201	195		- AppVersion
202	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)
203	197
204	198		- Here's example code to use LazAutoUpdate to download then run an application.
205	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'
206	200		- The executable 'updatehm(ostype)(.exe)' is in the same directory as your updater app
207	201		- ostype=\[win32\\|win64\\|linux32\\|linux64\]
208	202		- Windows ext=(.exe)
209	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.
210	204		- Of course, the "installer" could be your main application, with sister applications installable via a menu or some such.
211	205
212	206		``` pascal
213	207		procedure TForm1.Button1Click(Sender: TObject);
214	208		// Uses SysUtils,LazFileUtils,ulazautoupdate etc..
215	209		Var sDirectoryToInstallTo: string;
216	210		begin
217	211		sDirectoryToInstallTo := ProgramDirectory + 'installed';
218	212		Application.Title:='My whizzy app'
219	213		LazAutoUpdate1.WorkingMode := lauInstall;
220	214		LazAutoUpdate1.ProjectType := auSourceForge;
221	215		LazAutoUpdate1.SFProjectname:='mywizzy';
222	216		LazAutoUpdate1.VersionsININame:='mywizzyapp.ini';
223	217		LazAutoUpdate1.ZipfileName:='mywizzyapp.zip';
224	218		LazAutoUpdate1.AppFileWithPath := sDirectoryToInstallTo + DirectorySeparator + 'mywizzyapp.exe';
225	219		// Our responsibility to make the folder
226	220		if not DirectoryExistsUTF8(sDirectoryToInstallTo) then ForceDirectoriesUTF8(sDirectoryToInstallTo);
227	221		LazAutoUpdate1.Appversion:='0.0.0.0';
228	222		If LazAutoUpdate1.DownloadNewVersion then
229	223		begin
230	224		If LazAutoUpdate1.UpdateToNewVersion then
231	225		begin
232	226		LazAutoUpdate1.ShortCut.Category := scUtility;
233	227		LazAutoUpdate1.ShortCut.Target := LazAutoUpdate1.AppFileWithPath;
234	228		LazAutoUpdate1.ShortCut.ShortcutName := Application.Title;
235	229		LazAutoUpdate1.MakeShortCut; // makes a desktop shortcut and a Start menu entry in Windows
236	230		end;
237	231		end;
238	232		end;
239	233		```
240	234
241	235		- You can then programatically run the installed app easily enough:
242	236
243	237		``` pascal
244	238		// Uses asyncprocess
245	239		procedure TForm1.RunInstalledApp;
246	240		var
247	241		AProcess: TAsyncProcess;
248	242		begin
249	243		if not FileExistsUTF8(LazAutoUpdate1.AppFileWithPath) then
250	244		begin
251	245		ShowMessageFmt('%s does not exist! Install it first.',
252	246		[LazAutoUpdate1.AppFileWithPath]);
253	247		Exit;
254	248		end;
255	249		AProcess := TAsyncProcess.Create(nil);
256	250		try
257	251		AProcess.Executable := LazAutoUpdate1.AppFileWithPath;
258	252		AProcess.Execute;
259	253		finally
260	254		Aprocess.Free;
261	255		end;
262	256		end;
263	257		```
264	258
265	259		------------------------------------------------------------------------
266	260
267	261		## Public Methods List
268	262
269	263		- Function NewVersionAvailable: Boolean;
270	264		- Function DownloadNewVersion: Boolean;
271	265		- Function UpdateToNewVersion: Boolean;
272	266		- Procedure ShowWhatsNewIfAvailable;
273	267		- Procedure AutoUpdate;
274	268		- function AppIsActive
275	269		- procedure ResetAppVersion;
276	270
277	271		------------------------------------------------------------------------
278	272
279	273		## Non-published Properties list
280	274
281	275		- GUIOnlineVersion: String
282	276		- ReturnCode: Integer
283	277		- DownloadInprogress: Boolean
284	278		- AppFileWithPath: String
285	279		- AppVersion: String
286	280		- LastError: String;
287	281		- DebugMode: boolean
288	282		- LCLVersion: string
289	283		- WidgetSet: string
290	284		- FPCVersion: string
291	285		- LastCompiled: string
292	286		- TargetOS: string
293	287		- WindowsAdminCheck: boolean
294	288
295	289		------------------------------------------------------------------------
296	290
297	291		## Deploying multiple updates in a single project
298	292
299	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
300	294		- Each application to be updated should have a unique name for the versions.ini file. Set the VersionsINIFilename property.
301	295
302	296		------------------------------------------------------------------------
303	297
304	298		## In case the download takes to long
305	299
306	300		- VersionCountLimit property determines how long LazAutoUpdate will check for a new version before timing out.
307	301		- DownloadCountLimit property determines how long LazAutoUpdate will try downloading the new version before timing out.
308	302
309	303		------------------------------------------------------------------------
310	304
311	305		## Versions.ini
312	306
313	307		The format is as follows:
314	308
315	309		`;LazAutoUpdate versions file`\
316	310		`[versions]`\
317	311		`GUI=0.0.2`
318	312
319	313		- The file is small so that it is very quick to download
320	314
321	315		------------------------------------------------------------------------
322	316
323	317		## Source Code and latest versions
324	318
325	319		- [Project Page](https://sourceforge.net/projects/lazautoupdate/)
326	320		- [SVN HTTP Checkout](https://svn.code.sf.net/p/lazarus-ccr/svn/components/lazautoupdate/latest_stable)
327	321
328	322		------------------------------------------------------------------------
329	323
330	324		## Security
331	325
332	326		### Windows 10
333	327
334	328		- 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.
335	329		- 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.
336	330		- 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.
337	331		- 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.
338	332
339	333		### Linux
340	334
341	335		- Linux will do the update without even showing the update console, and the user gets a seamless experience.
342	336
343	337		------------------------------------------------------------------------
344	338
345	339		## Workflow
346	340
347	341		(Technical explanation)
348	342
349	343		The Lazarus Auto-Updater workflow for updating a running application is as follows:
350	344
351	345		- App downloads a small 'version.ini' file from sourceforge or github with version info (it can do this at start-up)
352	346		- App compares with its own internal version
353	347		- If new version available
354	348		- App deletes any contents of local /updates folder
355	349		- App downloads then unzips it from the web into a local /updates folder
356	350		- App uses TAsyncProcess to start the console updater.exe, passing it the name of the file to be updated in the command line
357	351		- updater.exe copies a downloaded 'whatsnew.txt' into the App folder and enters Sleep for a few seconds
358	352		- Meanwhile App has entered loop checking whether a 'whatsnew.txt' file has been copied into it's directory
359	353		- App detects 'whatsnew.txt' and Closes. (in other words the TProcess has started successfully)
360	354		- Updater copies /updates/UpdatedApp to App directory.
361	355		- Updater uses TProcess to start the updated app
362	356		- On Form.Show, App displays 'whatsnew.txt' then deletes it
363	357
364	358		The User sees:
365	359
366	360		- Dialog: 'There's a new version of xxx available. Would you like to download it?' Yes/No
367	361		- If Yes clicked:
368	362		- Download happens in the background (via a background thread) Optional 'download counter' is shown to indicate progress.
369	363		- User is prevented from closing the app whilst the download is in progress (in Form.CloseQuery)
370	364		- Dialog: 'The update is downloaded. Click OK to install it and restart xxx now' OK
371	365		- User clicks OK
372	366		- A console (DOS window in Windows) opens automatically and the Application closes. The console says 'Please wait updating xxx'
373	367		- After a couple of seconds the console disappears, and the new version of the App starts
374	368		- As soon as the main window is shown, a 'What's New' info box is shown with an OK button
375	369		- User clicks OK button, and never sees the info again
376	370
377	371		------------------------------------------------------------------------
378	372
379	373		Minesadorada
380	374
381	375		---
382	376		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