FlexCel Lazarus Guide
At the current moment, FlexCel provides experimental support for Lazarus. So what does "experimental" mean in this context?
- It has been reasonably tested, and while it has some known bugs, it primarily works fine. But it is not yet at the quality standards of FlexCel for Delphi.
- We require a Trunk version of Lazarus and fpc from at least December 1, 2023. If you do not have Trunk installed, we can recommend fpcupdeluxe to install them.
Note
We've tested this release with the following git hashes:
- FPC: 7ecb19f906
- Lazarus: 25c7f3c141
If you are having trouble with newer versions in the Trunk, you can try to use this specific releases. If using fpcupdeluxe, you can click in the button "Setup+" and at the top-right, "Branch and revision" box, specify the hashes above for FPC and Lazarus.
Requisites and limitations
- As mentioned above, FlexCel needs Lazarus Trunk. Unfortunately, we use anonymous methods, and those aren't yet in stable.
- We support Windows (32 and 64 bits), macOS (intel 64 and arm 64), and Linux (intel 64 bits). There aren't plans for other platforms at the moment. FlexCel uses GDI+ in Windows, CoreGraphics in macOS, and SKIA in Linux (it does not use LCL), and to support other platforms, we need to write a graphics adapter for it.
- Due to the limited RTTI in fpc, reports will only work from TDataSets, not from TList<object>
- Printing is currently not supported on any platform.
We plan to move from experimental to stable once we conclude more in-depth testing and when Lazarus moves the functionality we need to their stable branch.
Installing FlexCel in Lazarus
Note
If you have manually installed FlexCel in Lazarus before, make sure to uninstall it first.
To install FlexCel in Lazarus, you need to use TMS Smart Setup.
Download Smart Setup, open a command window, go to the folder where you want to install it, and type:
tms credentials
Then enter your registration data. After that type
tms config
And search for "compiler paths:". Make sure you specify the path to the fpc compiler.
Finally, type
tms install tms.flexcel.vcl
At the time of this writing, TMS Smart Setup was only available in Windows, so you need to install it manually for other OSs. To install manually, you can type
tms fetch tms.flexcel.vcl
in a Windows command prompt, and then unzip the zip that gets downloaded to the "Downloads" folder into the machine you want.
Then, for each one of the packages below (and in that order):
- flexcel_core_lazarus.lpk
- flexcel_xlsadapter_lazarus.lpk
- flexcel_pdf_lazarus.lpk
- flexcel_render_lazarus.lpk
- flexcel_report_lazarus.lpk
You need to go to Menu->Package->Open Package File, and press the "Compile" button:
There is no need to add the packages to the IDE.
Creating a Lazarus app using FlexCel
Once you have all packages compiled, you need to add them to your app. In the project inspector, right click in "Required Packages" and click add:
In the dialog that opens, select the FlexCel packages that you want:
And they should then show as required packages for your app:
Next step now is to add FlexCel to the uses. The units to use are the same as the ones mentioned in Getting started:
- FlexCel.LCLSupport (you might use FlexCel.VCLSupport or FlexCel.SKIASupport if you want a single codebase with Delphi)
- FlexCel.Core
- FlexCel.XlsAdapter
- FlexCel.Report
- FlexCel.Pdf
- FlexCel.Render
The only difference with a regular Delphi app is that you must use FlexCel.LCLSupport once in your app.
Tip
For Linux apps, you can also use FlexCel.SKIASupport and it will also work. For Windows apps, you can use FlexCel.VCLSupport. This way, you can keep more compatibility with a Delphi version of your app. But for macOS, you need FlexCel.LCLSupport
After that, you can write code as usual.
Special considerations for different Operating Systems
All OSs
The main issue is always fonts. The fonts that your document uses must be installed in the operating system. You can check the PDF Exporting Guide, and Running FlexCel inside Docker containers for more information about fonts.
Linux
Linux is a little more complex than the others. Because you need to deploy an SKIA shared library with your app, making sure it is available to the final users. Almost everything in our Linux Guide also applies here, so we can recommend you take a quick look at it.
Important
In particular, you must ensure fontconfig is installed in the machines where you will deploy your application.
Deploying SKIA
The first thing in order to compile is to let Lazarus know where the SKIA libraries are. FlexCel comes with 2 libraries which are located at <FlexCel install dir>/ThirdParty/Skia/Linux64
:
- libflx_skia_draw.a : Proxy library to access SKIA from your app. This library will be linked with your app and doesn't have to be deployed with your 2. libflexskia.so.5 : Shared object (the equivalent of a dll in Windows) with SKIA itself. You need to have this .so in a place the app can find it. app.
Accessing libflx_skia_draw.a
The simplest way to have Lazarus find libflx_skia_draw.a is to add it to the linker path. In Lazarus, go to "Project -> Project Options", then select "Compiler Options->Paths":
Then add the path <FlexCel install dir>/ThirdParty/Skia/Linux64
in there.
Accessing libflexskia.so.5
With the previous step, your app should compile, but it will crash at start. For it to actually work, you need to make libflexskia.so.5 accessible to the application, at run time. There are two ways to do so:
- You can deploy libflexskia.so.5 to a shared folder like
/usr/local/lib
- You can deploy libflexskia.so.5 in the same folder as your app (or in a subfolder). But it works differently from Windows, because Linux apps won't find a .so library in the same folder as the app automatically. For it to work, you need to modify the RPATH of your app. You can modify it by going to "Project -> Project Options -> Compiler Options -> Compilation and Linking"
There, you can write "--rpath=$ORIGIN" in the box to have the app load the dll from its folder, or something like "--rpath=$ORIGIN/SharedObjects" to have the app load the so from a subfolder:
Warning
Don't forget to check the checkbox in the image above! Just writing the text isn't enough.
Once you do this, copy libflexskia.so.5 to the place where you set it, and the app should be able to run.