Lazarus Resources: what changed

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

Old	New		Line
1	1		## Introduction
2	2
3	3		Resource files contain data which should be compiled into the executable file. That data could consist of images, string tables, version info, ... even a Windows XP manifest and forms. This includes data that the programmer can retrieve in his code (accessing them as files). Using resources can be handy if you want to distribute self-contained executables.
4	4
5	5		Before FPC 2.4 it was not possible to use standard Delphi-compatible resource files (.res) in Lazarus because they were Win32 specific. Please see Lazarus resources (.lrs) below.
6	6
7	7		Standard Delphi-compatible resources are now recommended for current FPC (including all recent Lazarus versions). Please see FPC resources below.
8	8
9	9		Alternatively, you can include resources in your application from within the Lazarus IDE by using the [[IDE Window: Project Options\|IDE Resources Dialog]].
10	10
11	11		## FPC resources
12	12
13	13		Starting from FPC 2.4 you can use standard .rc (resource script) and .res (compiled resource) files in your project to include resources. To turn a .rc script used in the sources into a binary resource (.res file), FPC runs the appropriate external resource compiler (windres or GoRC). Therefore that resource compiler needs to be installed and present in the PATH environment variable. For more details, see: [FPC Programmer's guide, chapter 13 "Using Windows resources"](http://www.freepascal.org/docs-html/prog/progch13.html)
14	14
15	15		To simplify the compiling process, it is possible to use only the compiled resources in the .res files. You can precompile the resources by any available resource compiler - windres (available both on unixes and windows), GoRC (windows only), Microsoft resource compiler (rc.exe included in Visual Studio), Borland resource compiler (brcc32.exe included in Delphi, C++ Builder or Rad Studio products) or any other.
16	16
17	17		Use
18	18
19	19		- {\$R filename.rc} to compile a resource script and include the resulting resource file or
20	20		- {\$R filename.res} directive to include a compiled resource file
21	21
22	22		into the executable.
23	23
24	24		FPC RTL provides both low-level functions as well as high-level classes to access resources.
25	25
26	26		The low-level functions are:
27	27
28	28		- EnumResourceTypes
29	29		- EnumResourceNames
30	30		- EnumResourceLanguages
31	31		- FindResource
32	32		- FindResourceEx
33	33		- LoadResource
34	34		- SizeofResource
35	35		- LockResource
36	36		- UnlockResource
37	37		- FreeResource
38	38
39	39		They are compatible with the Windows API functions: \[<http://msdn.microsoft.com/en-us/library/ff468902(VS.85>).aspx\]
40	40
41	41		The main class used to work with resources is TResourceStream. LCL uses it to load embedded bitmaps, icons and form streams. Look at TGraphic.LoadFromResourceID or TIcon.LoadFromResourceHandle to see how it is used inside LCL.
42	42
43	43		### Adding resources to your program
44	44
45	45		Let's review the situation when you need to store some data inside your executable and during the program run you want to extract this data from it.
46	46
47	47		First we need to tell the compiler what files to include in the resource. We do this in a .rc (resource script) file: mydata.rc file:
48	48
49	49		``` pascal
50	50		MYDATA RCDATA "mydata.dat"
51	51		```
52	52
53	53		Here MYDATA is the resource name, RCDATA is the type of resource (look here <http://msdn.microsoft.com/en-us/library/ms648009(VS.85>).aspx for explanation of possible types) and "mydata.dat" is your data file.
54	54
55	55		Let's instruct the compiler to include the resource into your project:
56	56
57	57		``` pascal
58	58		program mydata;
59	59
60	60		{$R mydata.rc}
61	61		begin
62	62		end.
63	63		```
64	64
65	65		Behind the scenes, the FPC compiler actually instructs the resource compiler distributed with FPC to follow the .rc script to compile your data files into a binary .res resource file. The linker will then include this into the executable. Though this is transparent to the programmer, you can, if you want to, create your own .res file with e.g. the Borland resource compiler. Instead of using `{$R mydata.rc}` you'd use `{$R mydata.res}`.
66	66
67	67		### Use the -FF parameter in FPC 3.3.1
68	68
69	69		FPC 3.3.1 can use fpcres instead of windres as RC to RES compiler. To enable it, pass the -FF parameter to the compiler. In that case you won't have to install windres.
70	70
71	71		Edit your fpc.cfg and add lines at the end in order to enable the parameter by default
72	72
73	73		``` c
74	74		# Use fpcres as resource compiler
75	75		-FF
76	76		```
77	77
78	78		### Checking you have windres
79	79
80	80		On Linux/FreeBSD/macOS, you might need to make sure you have the windres resource compiler, which is part of the GNU binutils project.
81	81
82	82		#### Linux
83	83
84	84		On Debian systems you could run (FIXME : this work for a 64B version, for 32B systems you will must probably change w64 to w32) :
85	85
86	86		``` bash
87	87		sudo apt install mingw-w64 mingw-w64-tools
88	88		```
89	89
90	90		or, if you do not need full mingw :
91	91
92	92		``` bash
93	93		sudo apt install binutils-mingw-w64-x86-64
94	94		```
95	95
96	96		Next 2 windres compilers will be installed (in /usr/bin) x86_64-w64-mingw32-windres and i386-w64-mingw32-windres. But FPC search "windres" (worst the path can be "Select manually"). You must edit /etc/fpc.cfg and add lines at the end (delete the old "-FC")
97	97
98	98		``` c
99	99		# MS Windows .rc resource compiler
100	100		#IFDEF CPUAMD64
101	101		-FCx86_64-w64-mingw32-windres
102	102		#ENDIF
103	103		#IFDEF cpui386
104	104		-FCi386-w64-mingw32-windres
105	105		#ENDIF
106	106		```
107	107
108	108		#### FreeBSD
109	109
110	110		Even if you install the binutils package via the ports collection, the windres binary is not installed - it is probably considered too Windows centric. So you have to manually add windres yourself.
111	111
112	112		When you build the binutils package via ports, the windres binary is actually built, but it is not installed by default. So, after building and installing the package:
113	113
114	114		1\. From the /usr/ports/devel/binutils directory, cd work/binutils-2.xx/binutils
115	115
116	116		2\. Copy the windres binary into your /usr/local/bin/ directory, or into your \$HOME/bin/ directory.
117	117
118	118		Note: The windres utility is hardcoded to use gcc but [FreeBSD 10.0](https://www.freebsd.org/releases/10.0R/relnotes.html#userland) (January 2014) replaced gcc with clang, so you will also need to install gcc from ports to be able to use windres if you are using a version of FreeBSD that is not end-of-life.
119	119
120	120		#### macOS
121	121
122	122		##### Using binutils source
123	123
124	124		As of December 2021, the latest version is binutils-2.37 but it changes regularly. Substitute the latest version in any command below.
125	125
126	126		- Download the latest binutils source from <https://ftp.gnu.org/gnu/binutils/>
127	127		- Uncompress the binutils-2.37.tar.gz archive (I used The Unarchiver free utility from the Mac App Store)
128	128		- Open an Applications \> Utilities \> Terminal and type the following commands:
129	129
130		-	~~`cd binutils-2.34`\~~
131		-	~~`./configure`\~~
132		-	~~`make`\~~
133		-	~~`cd binutils`\~~
134		-	~~`make windres`\~~
135		-	~~`sudo cp windres /usr/local/bin/`\~~
136		-	~~`cd doc`\~~
137		-	~~`gzip windres.1`\~~
138		-	~~`sudo cp windres.1.gz /usr/local/share/man/man1/`~~
	130	+	```text
	131	+	cd binutils-2.34
	132	+	./configure
	133	+	make
	134	+	cd binutils
	135	+	make windres
	136	+	sudo cp windres /usr/local/bin/
	137	+	cd doc
	138	+	gzip windres.1
	139	+	sudo cp windres.1.gz /usr/local/share/man/man1/
	140	+	```
139	141
140	142		If you execute `windres` you will get a disappointing error message:
141	143
142		-	~~`windres: Can't detect architecture.`~~
	144	+	```text
	145	+	windres: Can't detect architecture.
	146	+	```
143	147
144	148		To fix this you should be able to pass the `--target=mach-o-x86-64` argument to `windres` on the command line, but this still gives the same error message. My ultimate fix was to change the `windres.c` file as follows:
145	149
146		-	~~`$ diff ~/tmp/windres.c windres.c`\~~
147		-	~~`1100c1100,1101`\~~
148		-	~~`< def_target_arch = NULL;`\~~
149		-	~~`---`\~~
150		-	~~`> //def_target_arch = NULL;`\~~
151		-	~~`> def_target_arch = "mach-o-x86-64";`~~
	150	+	```text
	151	+	$ diff ~/tmp/windres.c windres.c
	152	+	1100c1100,1101
	153	+	< def_target_arch = NULL;
	154	+	---
	155	+	> //def_target_arch = NULL;
	156	+	> def_target_arch = "mach-o-x86-64";
	157	+	```
152	158
153	159		The above diff indicates I changed line 1100 in the `windres.c` file by commenting it out, then added a new line which assigns the correct architecture to the def_target_arch variable. You then need to again:
154	160
155		-	~~`make windres`\~~
156		-	~~`sudo cp windres /usr/local/bin/`~~
	161	+	```text
	162	+	make windres
	163	+	sudo cp windres /usr/local/bin/
	164	+	```
157	165
158	166		For detailed help you can consult the man page by opening an Applications \> Utilities \> Terminal and typing the following command:
159	167
160		-	~~`man windres`~~
	168	+	```text
	169	+	man windres
	170	+	```
161	171
162	172		Alternatively, you can display a usage summary by opening an Applications \> Utilities \> Terminal and typing the following command:
163	173
164		-	~~`windres --help`~~
	174	+	```text
	175	+	windres --help
	176	+	```
165	177
166	178		#### Windows
167	179
168	180		On Windows, windres and the gorc resource compiler should be provided by the FPC and Lazarus installers.
169	181
170	182		### Using resources in your program
171	183
172	184		Now let's extract the stored resource into a file, e.g. mydata.dat:
173	185
174	186		``` pascal
175	187		program mydata;
176	188		uses
177	189		SysUtils, Classes, LCLType;
178	190		{$R mydata.res}
179	191		var
180	192		S: TResourceStream;
181	193		F: TFileStream;
182	194		begin
183	195		// create a resource stream which points to our resource
184	196		S := TResourceStream.Create(HInstance, 'MYDATA', RT_RCDATA);
185	197		// Please ensure you write the enclosing apostrophes around MYDATA,
186	198		// otherwise no data will be extracted.
187	199		try
188	200		// create a file mydata.dat in the application directory
189	201		F := TFileStream.Create(ExtractFilePath(ParamStr(0)) + 'mydata.dat', fmCreate);
190	202		try
191	203		F.CopyFrom(S, S.Size); // copy data from the resource stream to file stream
192	204		finally
193	205		F.Free; // destroy the file stream
194	206		end;
195	207		finally
196	208		S.Free; // destroy the resource stream
197	209		end;
198	210		end.
199	211		```
200	212
201	213		Many classes (at least in Lazarus trunk/development version) also support loading directly from FPC resources, e.g.
202	214
203	215		``` pascal
204	216		procedure exampleproc;
205	217		var
206	218		Image: TImage
207	219		begin
208	220		Image := TImage.Create;
209	221		Image.Picture.LoadFromResourceName(HInstance,'image'); // note that there is no need for the extension
210	222		end;
211	223		```
212	224
213	225		## Lazarus resources
214	226
215	227		> Warning: As mentioned above, using "normal"/Windows resources is now possible. Lazarus has also switched to this format since ver. 1.4; see [[Lazarus 1.4.0 release notes]]
216	228
217	229		In order to use your files as Lazarus resources, they must be included as a resource file.
218	230
219	231		You can create LRS files with [LRS explorer](https://sourceforge.net/projects/lrsexplorer/) or using lazres with the command line.
220	232
221	233		Lazres can be found in the "Tools" directory (C:\Lazarus\Tools\\ - you may need to compile it from lazres.lpi project) of your Lazarus installation folder.
222	234
223	235		Then you can compile Lazarus resource files (*.lrs) via the command line. The syntax for lazres is:
224	236
225	237		<nowiki>lazres <filename of resource file> <files to include (file1 file2 file3 ...)></nowiki>
226	238
227	239		Example:
228	240
229	241		```dos
230	242		lazres mylazarusresource.lrs image.jpg
231	243		```
232	244
233	245		Alternatively you can compile and execute glazres (C:\Lazarus\Tools\glazres) for a GUI version of lazres.
234	246
235	247		To use a Lazarus resource file in your project, include the file with the \$I compiler directive in the initialization section of your unit.
236	248
237	249		You can access the data in the resources directly or with the LoadFromLazarusResource method of the variables which will hold the file contents afterwards. LoadFromLazarusResource requires a string parameter that indicates which object should be loaded from the resource file.
238	250
239	251		Example:
240	252
241	253		``` pascal
242	254		uses ...LResources...;
243	255
244	256		...
245	257		procedure exampleproc;
246	258		var
247	259		Image: TImage
248	260		begin
249	261		Image := TImage.Create;
250	262		Image.Picture.LoadFromLazarusResource('image'); // note that there is no need for the extension
251	263		end;
252	264
253	265		initialization
254	266		{$I mylazarusresource.lrs}
255	267		```
256	268
257	269		This code includes the file mylazarusresource.lrs into the project. In the procedure exampleproc an icon object is created and loaded from the object "image" out of the resource. The file which was compiled into the resource was probably named image.jpg.
258	270
259	271		Every class that is derived from [[TGraphic]] contains the [[LoadFromLazarusResource]] procedure.
260	272
261	273		### Lazarus Resource Form File
262	274
263	275		Lazarus generates .LRS files from .LFM form files.
264	276
265	277		When a LRS form file is missing, FPC reports the following error: `ERROR: unit1.pas(193,4) Fatal: Can't open include file "unit1.lrs"`
266	278
267	279		To solve it you can either:
268	280
269	281		- use lazres: c:\lazarus\tools\lazres.exe unit1.lrs unit1.lfm
270	282		- (easier): make a trivial change in the form design, revert it and save the form; this will recreate the .lrs file without needing to run lazres.
271	283
272	284		### Getting the raw data of an lrs resource
273	285
274	286		You can retrieve the data of the resource with:
275	287
276	288		``` pascal
277	289		uses ...LResources...;
278	290
279	291		...
280	292		procedure TForm1.FormCreate(Sender: TObject);
281	293		var
282	294		r: TLResource;
283	295		Data: String;
284	296		begin
285	297		r:=LazarusResources.Find('datafile1');
286	298		if r=nil then raise Exception.Create('resource datafile1 is missing');
287	299		Data:=r.Value;
288	300		...do something with the data...
289	301		end;
290	302		```
291	303
292	304		## See also
293	305
294	306		- [[fcl-res\|FCL resource units]]
295	307		- [[lazres\|Lazarus Resource compiler]]
296	308		- [[IDE Window: Project Options\|IDE Project Options > Resources]]
297	309
298	310		## External links
299	311
300	312		- [Free Pascal Programmer's Guide, Chapter 13 "Using Windows resources"](https://www.freepascal.org/docs-html/prog/progch13.html).
301	313
302	314		---
303	315		From the Free Pascal wiki, page "Lazarus Resources", as it stood on 2023-12-13 after a change by Coz, 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).
304	316		Category: FPC
305	317		Category: Lazarus
306	318		Category: Tutorials

Back to history