Difference between revisions of "Lazarus Resources"

From Free Pascal wiki
Jump to navigationJump to search
(add direct support for fpc resources)
(→‎See also: Added related entries)
(24 intermediate revisions by 9 users not shown)
Line 2: Line 2:
  
 
==Introduction==
 
==Introduction==
 +
 
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.
 
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.
  
Before FPC 2.4 it was not possible to use "normal" resource files (*.res) in Lazarus because they were Win32 specific. Please see [[#Lazarus resources]] below.
+
Before FPC 2.4 it was not possible to use standard Delphi-compatible [[#FPC_resources|resource files]] (*.res) in Lazarus because they were Win32 specific. Please see [[#Lazarus_resources|Lazarus resources]] (*.lrs) below.
  
Normal resources are now recommended for current FPC '''(including all recent Lazarus versions)'''. Please see [[#FPC resources]] below.
+
Standard Delphi-compatible resources are now recommended for current FPC '''(including all recent Lazarus versions)'''. Please see [[#FPC_resources|FPC resources]] below.  
  
==Lazarus resources==
+
Alternatively, you can include resources in your application from within the Lazarus IDE by using the [[IDE_Window:_Project_Options#Resources|IDE Resources Dialog]].
{{Warning|As mentioned above, using "normal"/Windows resources. The current development (trunk) version of Lazarus has also switched to this format; see [[Lazarus_1.4.0_release_notes]] }}
 
In order to use your files as Lazarus resources, you had to recreate them with lazres. Lazres can be found in the "Tools" directory (C:\Lazarus\Tools\ - you first have to compile the lazres.lpi project) of your Lazarus installation folder.
 
  
Then you can compile Lazarus resource files (*.lrs) via the command line. The syntax for lazres is:
+
== FPC resources ==
:<pre><nowiki>lazres <filename of resource file> <files to include (file1 file2 file3 ...)></nowiki></pre>
 
Example:
 
<syntaxhighlight lang="dos">lazres mylazarusresource.lrs image.jpg</syntaxhighlight>
 
 
 
To use a Lazarus resource file in your project, include the file with the $I compiler directive in the '''initialization''' section of your unit.
 
 
 
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.
 
 
 
Example:
 
<syntaxhighlight>
 
uses ...LResources...;
 
  
...
 
procedure exampleproc;
 
var
 
  Image: TImage
 
begin
 
  Image := TImage.Create;
 
  Image.Picture.LoadFromLazarusResource('image'); // note that there is no need for the extension
 
end;
 
 
initialization
 
  {$I mylazarusresource.lrs}
 
</syntaxhighlight>
 
 
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.
 
 
Every class that is derived from TGraphic contains the LoadFromLazarusResource procedure.
 
 
=== Lazarus Resource Form File ===
 
Lazarus generates .LRS files from .LFM form files.
 
 
When a LRS form file is missing, FPC reports the following error:
 
<code>ERROR: unit1.pas(193,4) Fatal: Can't open include file "unit1.lrs"</code>
 
 
To solve it you can either:
 
* use lazres: c:\lazarus\tools\lazres.exe unit1.lrs unit1.lfm
 
* (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.
 
 
===Getting the raw data of an lrs resource===
 
 
You can retrieve the data of the resource with:
 
 
<syntaxhighlight>
 
uses ...LResources...;
 
 
...
 
procedure TForm1.FormCreate(Sender: TObject);
 
var
 
  r: TLResource;
 
  Data: String;
 
begin
 
  r:=LazarusResources.Find('datafile1');
 
  if r=nil then raise Exception.Create('resource datafile1 is missing');
 
  Data:=r.Value;
 
  ...do something with the data...
 
end;
 
</syntaxhighlight>
 
 
== FPC resources ==
 
 
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.
 
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: [http://www.freepascal.org/docs-html/prog/progch13.html FPC Programmer's guide, chapter 13 "Using Windows resources"]
 
For more details, see: [http://www.freepascal.org/docs-html/prog/progch13.html FPC Programmer's guide, chapter 13 "Using Windows resources"]
Line 96: Line 36:
 
* UnlockResource
 
* UnlockResource
 
* FreeResource
 
* FreeResource
 +
 
They are compatible with the Windows API functions: [http://msdn.microsoft.com/en-us/library/ff468902(VS.85).aspx]
 
They are compatible with the Windows API functions: [http://msdn.microsoft.com/en-us/library/ff468902(VS.85).aspx]
  
Line 101: Line 42:
  
 
=== Adding resources to your program ===
 
=== Adding resources to your program ===
 +
 
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.
 
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.
  
 
First we need to tell the compiler what files to include in the resource. We do this in a .rc (resource script) file:
 
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:  
 
mydata.rc file:  
:<pre><nowiki>MYDATA        RCDATA "mydata.dat"</nowiki></pre>  
+
 
 +
<syntaxhighlight lang="pascal">
 +
MYDATA        RCDATA "mydata.dat"
 +
</syntaxhighlight>  
 +
 
 
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.  
 
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.  
  
 
Let's instruct the compiler to include the resource into your project:
 
Let's instruct the compiler to include the resource into your project:
<syntaxhighlight>program mydata;
+
 
 +
<syntaxhighlight lang="pascal">
 +
program mydata;
  
 
{$R mydata.rc}
 
{$R mydata.rc}
 
begin
 
begin
end.</syntaxhighlight>
+
end.
 +
</syntaxhighlight>
  
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 <syntaxhighlight>{$R mydata.rc}</syntaxhighlight> you'd use <syntaxhighlight>{$R mydata.res}</syntaxhighlight>.
+
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 <syntaxhighlight lang="pascal" inline>{$R mydata.rc}</syntaxhighlight> you'd use <syntaxhighlight lang="pascal" inline>{$R mydata.res}</syntaxhighlight>.
  
 
=== Checking you have windres ===
 
=== Checking you have windres ===
On Linux/OSX, you might need to make sure you have the windres resource compiler, which is provided by the mingw32 tools.
+
 
E.g. on Debian you could run:
+
On Linux/FreeBSD/macOS, you might need to make sure you have the ''windres'' resource compiler, which is part of the GNU binutils project.
 +
 
 +
==== Linux ====
 +
 
 +
On Debian systems you could run (FIXME : this work for a 64B version, for 32B systems you will must probably change w64 to w32) :
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
aptitude install mingw32-binutils
+
sudo apt install mingw-w64 mingw-w64-tools
# this installs e.g. /usr/bin/i586-mingw32msvc-windres
+
</syntaxhighlight>
# but FPC expects just windres, so:
+
or, if you do not need full mingw :
ln -s /usr/bin/i586-mingw32msvc-windres /usr/bin/windres
+
<syntaxhighlight lang="bash">
# alternatively (and probably more "official") use -FCi586-mingw32msvc-windres in your calls to fpc or
+
sudo apt install binutils-mingw-w64-x86-64
# add -FCi586-mingw32msvc-windres to your fpc.cfg
+
</syntaxhighlight>
 +
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")
 +
<syntaxhighlight lang="c">
 +
# MS Windows .rc resource compiler
 +
#IFDEF CPUAMD64
 +
-FCx86_64-w64-mingw32-windres
 +
#ENDIF
 +
#IFDEF cpui386
 +
-FCi386-w64-mingw32-windres
 +
#ENDIF
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
==== FreeBSD ====
 +
 +
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.
 +
 +
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:
 +
 +
1. From the /usr/ports/devel/binutils directory, cd work/binutils-2.xx/binutils
 +
 +
2. Copy the ''windres'' binary into your /usr/local/bin/ directory, or into your $HOME/bin/ directory.
 +
 +
'''Note:''' The ''windres'' utility is hardcoded to use ''gcc'' but [https://www.freebsd.org/releases/10.0R/relnotes.html#userland FreeBSD 10.0] (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.
 +
 +
==== macOS ====
 +
 +
===== Using binutils source =====
 +
 +
As of June 2020, the latest version is binutils-2.34 but it may change. Substitute the latest version in any command below.
 +
 +
* Download the latest binutils source from https://mirror.freedif.org/GNU/binutils/
 +
* Uncompress the binutils-2.34.tar.xz archive (I used ''The Unarchiver'' free utility from the Mac App Store)
 +
* Open an Applications > Utilities > Terminal and type the following commands:
 +
 +
cd binutils-2.34
 +
./configure
 +
make
 +
cd binutils
 +
make windres
 +
sudo cp windres /usr/local/bin/
 +
cd doc
 +
gzip windres.1
 +
sudo cp windres.1.gz /usr/local/share/man/man1/
 +
 +
If you execute <tt>windres</tt> you will get a disappointing error message:
 +
 +
windres: Can't detect architecture.
 +
 +
To fix this you should be able to pass the <tt>--target=mach-o-x86-64</tt> argument to <tt>windres</tt> on the command line, but this still gives the same error message. My ultimate fix was to change the <tt>windres.c</tt> file as follows:
 +
 +
$ diff  ~/tmp/windres.c windres.c
 +
1100c1100,1101
 +
<  def_target_arch = NULL;
 +
---
 +
>  //def_target_arch = NULL;
 +
>  def_target_arch = "mach-o-x86-64";
 +
 +
The above diff indicates I changed line 1100 in the <tt>windres.c</tt> 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:
 +
 +
make windres
 +
sudo cp windres /usr/local/bin/
 +
 +
For detailed help you can consult the man page by opening an Applications > Utilities > Terminal and typing the following command:
 +
 +
man windres
 +
 +
Alternatively, you can display a usage summary by opening an Applications > Utilities > Terminal and typing the following command:
 +
 +
windres --help
 +
 +
==== Windows ====
  
 
On Windows, windres and the gorc resource compiler should be provided by the FPC and Lazarus installers.
 
On Windows, windres and the gorc resource compiler should be provided by the FPC and Lazarus installers.
Line 133: Line 156:
 
=== Using resources in your program ===
 
=== Using resources in your program ===
 
Now let's extract the stored resource into a file, e.g. mydata.dat:
 
Now let's extract the stored resource into a file, e.g. mydata.dat:
<syntaxhighlight>program mydata;
+
 
 +
<syntaxhighlight lang="pascal">
 +
program mydata;
 
uses
 
uses
   SysUtils, Windows {needed for RT_RCDATA, could be omitted};
+
   SysUtils, Classes, Windows {needed for RT_RCDATA, could be omitted};
 
{$R mydata.res}
 
{$R mydata.res}
 
var
 
var
Line 160: Line 185:
  
 
Many classes (at least in Lazarus trunk/development version) also support loading directly from FPC resources, e.g.
 
Many classes (at least in Lazarus trunk/development version) also support loading directly from FPC resources, e.g.
<syntaxhighlight>
+
 
 +
<syntaxhighlight lang="pascal">
 
procedure exampleproc;
 
procedure exampleproc;
 
var
 
var
Line 169: Line 195:
 
end;
 
end;
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
 +
==Lazarus resources==
 +
 +
{{Warning|As mentioned above, using "normal"/Windows resources. Lazarus has also switched to this format since ver. 1.4; see [[Lazarus_1.4.0_release_notes]] }}
 +
 +
In order to use your files as Lazarus resources, they must be included as a resource file.
 +
 +
You can create LRS files with [https://sourceforge.net/projects/lrsexplorer/ LRS explorer] or using ''lazres'' with the command line.
 +
 +
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.
 +
 +
Then you can compile Lazarus resource files (*.lrs) via the command line. The syntax for lazres is:
 +
 +
<pre><nowiki>lazres <filename of resource file> <files to include (file1 file2 file3 ...)></nowiki></pre>
 +
 +
Example:
 +
<syntaxhighlight lang="dos">lazres mylazarusresource.lrs image.jpg</syntaxhighlight>
 +
 +
Alternatively you can compile and execute glazres (C:\Lazarus\Tools\glazres) for a GUI version of lazres.
 +
 +
To use a Lazarus resource file in your project, include the file with the $I compiler directive in the '''initialization''' section of your unit.
 +
 +
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.
 +
 +
Example:
 +
 +
<syntaxhighlight lang="pascal">
 +
uses ...LResources...;
 +
 +
...
 +
procedure exampleproc;
 +
var
 +
  Image: TImage
 +
begin
 +
  Image := TImage.Create;
 +
  Image.Picture.LoadFromLazarusResource('image'); // note that there is no need for the extension
 +
end;
 +
 +
initialization
 +
  {$I mylazarusresource.lrs}
 +
</syntaxhighlight>
 +
 +
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.
 +
 +
Every class that is derived from [[TGraphic]] contains the [[LoadFromLazarusResource]] procedure.
 +
 +
=== Lazarus Resource Form File ===
 +
 +
Lazarus generates .LRS files from .LFM form files.
 +
 +
When a LRS form file is missing, FPC reports the following error:
 +
<code>ERROR: unit1.pas(193,4) Fatal: Can't open include file "unit1.lrs"</code>
 +
 +
To solve it you can either:
 +
* use lazres: c:\lazarus\tools\lazres.exe unit1.lrs unit1.lfm
 +
* (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.
 +
 +
===Getting the raw data of an lrs resource===
 +
 +
You can retrieve the data of the resource with:
 +
 +
<syntaxhighlight lang="pascal">
 +
uses ...LResources...;
 +
 +
...
 +
procedure TForm1.FormCreate(Sender: TObject);
 +
var
 +
  r: TLResource;
 +
  Data: String;
 +
begin
 +
  r:=LazarusResources.Find('datafile1');
 +
  if r=nil then raise Exception.Create('resource datafile1 is missing');
 +
  Data:=r.Value;
 +
  ...do something with the data...
 +
end;
 +
</syntaxhighlight>
 +
 +
== See also ==
 +
 +
* [[fcl-res|FCL resource units]]
 +
* [[lazres|Lazarus Resource compiler]]
 +
* [[IDE_Window:_Project_Options#Resources|IDE Project Options > Resources]]
 +
 +
== External links ==
 +
 +
* [https://www.freepascal.org/docs-html/prog/progch13.html Free Pascal Programmer's Guide, Chapter 13 "Using Windows resources"].
 +
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]
 
[[Category:Lazarus]]
 
[[Category:Lazarus]]
 
[[Category:FPC]]
 
[[Category:FPC]]

Revision as of 02:59, 13 August 2020

Deutsch (de) English (en) español (es) français (fr) 한국어 (ko) русский (ru)

Introduction

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.

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.

Standard Delphi-compatible resources are now recommended for current FPC (including all recent Lazarus versions). Please see FPC resources below.

Alternatively, you can include resources in your application from within the Lazarus IDE by using the IDE Resources Dialog.

FPC resources

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"

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.

Use

  • {$R filename.rc} to compile a resource script and include the resulting resource file or
  • {$R filename.res} directive to include a compiled resource file

into the executable.

FPC RTL provides both low-level functions as well as high-level classes to access resources.

The low-level functions are:

  • EnumResourceTypes
  • EnumResourceNames
  • EnumResourceLanguages
  • FindResource
  • FindResourceEx
  • LoadResource
  • SizeofResource
  • LockResource
  • UnlockResource
  • FreeResource

They are compatible with the Windows API functions: [1]

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.

Adding resources to your program

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.

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:

MYDATA         RCDATA "mydata.dat"

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.

Let's instruct the compiler to include the resource into your project:

program mydata;

{$R mydata.rc}
begin
end.

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

Checking you have windres

On Linux/FreeBSD/macOS, you might need to make sure you have the windres resource compiler, which is part of the GNU binutils project.

Linux

On Debian systems you could run (FIXME : this work for a 64B version, for 32B systems you will must probably change w64 to w32) :

sudo apt install mingw-w64 mingw-w64-tools

or, if you do not need full mingw :

sudo apt install binutils-mingw-w64-x86-64

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")

# MS Windows .rc resource compiler
#IFDEF CPUAMD64
-FCx86_64-w64-mingw32-windres
#ENDIF
#IFDEF cpui386
-FCi386-w64-mingw32-windres
#ENDIF

FreeBSD

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.

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:

1. From the /usr/ports/devel/binutils directory, cd work/binutils-2.xx/binutils

2. Copy the windres binary into your /usr/local/bin/ directory, or into your $HOME/bin/ directory.

Note: The windres utility is hardcoded to use gcc but FreeBSD 10.0 (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.

macOS

Using binutils source

As of June 2020, the latest version is binutils-2.34 but it may change. Substitute the latest version in any command below.

  • Download the latest binutils source from https://mirror.freedif.org/GNU/binutils/
  • Uncompress the binutils-2.34.tar.xz archive (I used The Unarchiver free utility from the Mac App Store)
  • Open an Applications > Utilities > Terminal and type the following commands:
cd binutils-2.34
./configure
make
cd binutils
make windres
sudo cp windres /usr/local/bin/
cd doc
gzip windres.1
sudo cp windres.1.gz /usr/local/share/man/man1/

If you execute windres you will get a disappointing error message:

windres: Can't detect architecture.

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:

$ diff  ~/tmp/windres.c windres.c
1100c1100,1101
<   def_target_arch = NULL;
---
>   //def_target_arch = NULL;
>   def_target_arch = "mach-o-x86-64";

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:

make windres
sudo cp windres /usr/local/bin/

For detailed help you can consult the man page by opening an Applications > Utilities > Terminal and typing the following command:

man windres

Alternatively, you can display a usage summary by opening an Applications > Utilities > Terminal and typing the following command:

windres --help

Windows

On Windows, windres and the gorc resource compiler should be provided by the FPC and Lazarus installers.

Using resources in your program

Now let's extract the stored resource into a file, e.g. mydata.dat:

program mydata;
uses
  SysUtils, Classes, Windows {needed for RT_RCDATA, could be omitted};
{$R mydata.res}
var
  S: TResourceStream;
  F: TFileStream;
begin
  // create a resource stream which points to our resource
  S := TResourceStream.Create(HInstance, 'MYDATA', RT_RCDATA);
  // Replace RT_RCDATA with ??? with what?
  // Please ensure you write the enclosing apostrophes around MYDATA, 
  // otherwise no data will be extracted.
  try
    // create a file mydata.dat in the application directory
    F := TFileStream.Create(ExtractFilePath(ParamStr(0)) + 'mydata.dat', fmCreate); 
    try
      F.CopyFrom(S, S.Size); // copy data from the resource stream to file stream
    finally
      F.Free; // destroy the file stream
    end;
  finally
    S.Free; // destroy the resource stream
  end;
end.

Many classes (at least in Lazarus trunk/development version) also support loading directly from FPC resources, e.g.

procedure exampleproc;
var
  Image: TImage
begin
  Image := TImage.Create;
  Image.Picture.LoadFromResourceName(HInstance,'image'); // note that there is no need for the extension
end;


Lazarus resources

Warning-icon.png

Warning: As mentioned above, using "normal"/Windows resources. Lazarus has also switched to this format since ver. 1.4; see Lazarus_1.4.0_release_notes

In order to use your files as Lazarus resources, they must be included as a resource file.

You can create LRS files with LRS explorer or using lazres with the command line.

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.

Then you can compile Lazarus resource files (*.lrs) via the command line. The syntax for lazres is:

lazres <filename of resource file> <files to include (file1 file2 file3 ...)>

Example:

lazres mylazarusresource.lrs image.jpg

Alternatively you can compile and execute glazres (C:\Lazarus\Tools\glazres) for a GUI version of lazres.

To use a Lazarus resource file in your project, include the file with the $I compiler directive in the initialization section of your unit.

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.

Example:

uses ...LResources...;

...
procedure exampleproc;
var
  Image: TImage
begin
  Image := TImage.Create;
  Image.Picture.LoadFromLazarusResource('image'); // note that there is no need for the extension
end;

initialization
  {$I mylazarusresource.lrs}

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.

Every class that is derived from TGraphic contains the LoadFromLazarusResource procedure.

Lazarus Resource Form File

Lazarus generates .LRS files from .LFM form files.

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"

To solve it you can either:

  • use lazres: c:\lazarus\tools\lazres.exe unit1.lrs unit1.lfm
  • (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.

Getting the raw data of an lrs resource

You can retrieve the data of the resource with:

uses ...LResources...;

...
procedure TForm1.FormCreate(Sender: TObject);
var
  r: TLResource;
  Data: String;
begin
  r:=LazarusResources.Find('datafile1');
  if r=nil then raise Exception.Create('resource datafile1 is missing');
  Data:=r.Value;
  ...do something with the data...
end;

See also

External links