Report Manager on macOS (Lazarus, Cocoa)
The Lazarus packages of Report Manager (engine with PDF export, LCL
preview and printing, and the embeddable designer), their examples and the Report Manager Designer
build on macOS with Lazarus and the native Cocoa widgetset. They use the same
.rep report files as Windows and Linux.
Tested on macOS 11 Big Sur (Intel, x86_64) with Lazarus 4.8 and Free Pascal 3.2.2: the designer test suite, the preview against the PDF output, the examples and the database drivers against real PostgreSQL, MySQL, Firebird and SQLite servers. On macOS 15, on Intel and on Apple Silicon (arm64), the Lazarus packages, the designer test suite, the PDF tests and the installation package are built and tested automatically (GitHub Actions).
Download: the Report Manager Designer for Intel Macs (macOS 10.15 or later) and Apple
Silicon Macs (macOS 11 or later) is in the
macOS folder of the release on
SourceForge (reportman-designer-<version>-macos-universal.dmg, one universal
application for both, see
Installation package). It can also be built from the source code as shown
below.
Requirements
- The Xcode Command Line Tools:
xcode-select --install(Free Pascal needs the Apple linker). - Lazarus with Free Pascal 3.2.2 (tested with Lazarus 4.8), or the toolchain the script
build/macos/setup-toolchain.shinstalls, see below. - At run time, to measure and shape the text: FreeType, fontconfig and HarfBuzz. With
Homebrew:
or without Homebrew,brew install fontconfig harfbuzzbuild/macos/build-deps.shbuilds them from their sources in your user folder (nosudo) and links them in~/lib. ICU is the one of macOS. - For HTTPS (the AI assistants and the Reportman DB Agent driver): OpenSSL 3,
brew install openssl@3, orbuild/macos/build-deps.sh, which also builds OpenSSL 3.5. The OpenSSL 0.9.8 that macOS keeps for compatibility is never used: it cannot verify certificates. An application can shiplibssl.3.dylibandlibcrypto.3.dylibinContents/Frameworksof its bundle instead, as the installation package does.
Applications started from the Finder do not receive DYLD_LIBRARY_PATH. The engine
looks for each library in Contents/Frameworks of the application, next to the
executable, in ~/lib, /usr/local/lib and the Homebrew and MacPorts
folders.
The Lazarus packages
Install them as on the other platforms, from the source code (GitHub, SourceForge) or from the Online Package Manager (the changes for macOS are in the source code and reach the Online Package Manager with its next update). From a terminal, in the folder of the source code:
LAZBUILD=lazbuild sh packages/fpc/build_fpc.sh
Examples
The three examples of examples/lazarus (see
Lazarus examples) build and run on macOS:
lazbuild examples/lazarus/pdfconsole/pdfconsole.lpi
lazbuild examples/lazarus/preview/preview.lpi
lazbuild examples/lazarus/designer/designer.lpi
examples/lazarus/pdfconsole/pdfconsole # writes sales.pdf
open examples/lazarus/preview/preview.app
open examples/lazarus/designer/designer.app
Lazarus writes the LCL examples as application bundles (preview.app,
designer.app) next to their projects: open them from the Finder or with
open.
Example with a database: PostgreSQL
examples/lazarus/postgresql has two reports that open their own connection and SQL
query on a sample database, one with each direct driver: sales_sqldb.rep (a FireDAC
connection, opened with SQLdb) and sales_zeos.rep (Zeos). The console program
pgreport writes both as PDF. With PostgreSQL from Homebrew:
brew install postgresql@16
brew services start postgresql@16
export PATH="$(brew --prefix postgresql@16)/bin:$PATH" # psql
cd examples/lazarus/postgresql
./createdb.sh # user and database rpsample, with the sample data
lazbuild pgreport.lpi
./pgreport # sales_sqldb.pdf and sales_zeos.pdf
With Postgres.app, put /Applications/Postgres.app/Contents/Versions/latest/bin in the
PATH instead. The connections are in dbxconnections.ini of the folder; to
open the reports in the designer, copy its two sections to the connections file of the designer:
~/.borland/dbxconnections when that file exists, otherwise
~/.dbxconnections in your home folder (the designer creates it).
OpenSSL in your application
Only HTTPS needs OpenSSL: the Reportman DB Agent driver and, in an application with the embedded
designer, the login and the AI assistants. Reports printed from your own data or to PDF never load
it. On your Mac, brew install openssl@3 or build/macos/build-deps.sh is
enough. To distribute your application to Macs without them, copy OpenSSL 3 into its bundle:
build/macos/bundle-openssl.sh YourApp.app
It copies libssl.3.dylib and libcrypto.3.dylib (from
build-deps.sh, Homebrew or MacPorts, or the folder given as the second parameter) to
Contents/Frameworks, where the engine looks first, makes them find each other inside the
bundle, adds the OpenSSL license and signs the application again (ad hoc, or with
RM_CODESIGN_IDENTITY). The libraries must have the architecture of your executable:
Homebrew on Apple Silicon gives arm64 ones. For a universal application (Intel and Apple Silicon),
give one folder of each architecture and the script joins them:
build/macos/bundle-openssl.sh YourApp.app <x86_64 libraries> <arm64 libraries>
The root certificates are the ones of macOS.
Build the Report Manager Designer
Two scripts of the source code prepare everything in your user folder (~/dev), without
sudo and without touching /usr/local:
build/macos/setup-toolchain.sh # Free Pascal 3.2.2, Lazarus 4.8 and ZeosDBO in ~/dev
build/macos/build-deps.sh # FreeType, HarfBuzz and fontconfig
. ~/dev/env.sh # lazbuild and fpc in the PATH
LAZBUILD=lazbuild sh packages/fpc/build_fpc.sh
build/macos/build-designer.sh # repman/repmandesigner_lcl.app
open repman/repmandesigner_lcl.app
The designer uses the language of macOS (System Preferences > Language & Region), also when
it is opened from the Finder, which gives applications no LANG variable.
build-designer.sh adds the Lazarus translations of the standard dialogs and buttons to
the bundle.
The scripts work on Intel and on Apple Silicon: they use the Lazarus archive and build the
libraries for the architecture of the Mac (macOS 10.15 or later on Intel, 11 or later on Apple
Silicon). Free Pascal 3.2.2 predates the tools of Xcode 15: with them, its Intel assembler output
and its executables need two workarounds, which setup-toolchain.sh detects and
configures (see docs/macos.md).
setup-toolchain.sh uses the official Free Pascal disk image without installing it and
the official Lazarus 4.8 archive. It also applies three corrections to the Cocoa widgetset and the
Cocoa printer of Lazarus (build/macos/patches):
- Printing produced blank sheets: the page margins were left undefined and macOS placed the page outside the paper.
- An application could stop when a window with scroll bars is closed right after its layout changes. That happens with the classic scroll bars of a mouse; a trackpad uses overlay scroll bars.
- Every row of a list box lost a little memory.
Apply them to your own Lazarus as well:
patch -d <lazarus folder> -p1 < build/macos/patches/<file>.patch, then
rebuild the IDE or your project.
Installation package
build-designer.sh makes an application for the machine that builds it (the bundle
links the executable and the libraries of ~/dev). To install the designer on other Macs,
build/macos/make-package.sh builds a self-contained application and its disk image:
build/macos/make-package.sh
# build/macos/out/<version>/Report Manager Designer.app
# build/macos/out/<version>/reportman-designer-<version>-macos-x86_64.dmg (or -arm64.dmg)
It builds for the architecture of the Mac. build/macos/make-universal.sh joins an
Intel and an Apple Silicon application into a universal one and its disk image
(-macos-universal.dmg). The published disk image is built that way by the
.github/workflows/macos.yml workflow of the source code, which builds and tests on both
kinds of Mac.
The application carries FreeType, HarfBuzz and fontconfig with its configuration, the translations
and the sample reports with their SQLite database: open the disk image, drag the
application to Applications and open it. It requires macOS 10.15 or later on Intel and macOS 11
or later on Apple Silicon (declared in its Info.plist; tested on macOS 11 and 15). The .rep files
open with the designer from the Finder: double click, drop them on its icon or Open With. The
welcome window, shown at startup and from Help → Sample reports…, lists the
samples; they are inside the application, so the designer opens a copy in
~/Documents/Report Manager/Samples, where they can be changed and saved. A data file of TClientDataSet (.cds) must be saved as XML
to be read on macOS: the binary format of Windows is not supported. It also carries
OpenSSL 3.5 for HTTPS (the login, the AI assistants and the Reportman DB Agent driver), with the root
certificates of macOS, and the licenses of those libraries. It does not include the client libraries
of the database servers. repmandesigner_lcl --check-https (the executable is in
Contents/MacOS) tests the HTTPS connection of the login without opening the
designer.
Since version 4.0.21 the application is signed with an Apple Developer ID certificate and notarized by Apple: it opens with a double click, like any application downloaded from the internet. Earlier versions were signed ad hoc, and the first time macOS only opened them from the Finder with right click > Open.
Databases
Both direct database drivers of the engine work on macOS (see the PostgreSQL example):
- FireDAC connections, opened with SQLdb: PostgreSQL, MySQL or MariaDB, Firebird, SQLite and ODBC. Free Pascal has no SQL Server connector for macOS: use ODBC with the FreeTDS ODBC driver.
- Zeos connections, with the same databases.
- The Reportman DB Agent driver (through the Hub) needs OpenSSL 3, see the requirements.
The client library of each database is looked for in this order:
- The one of the connection:
VendorLib(FireDAC connections) orLibraryLocation(Zeos), with the full path of the.dylib. - The library search of macOS (
~/lib,/usr/local/lib). - The folders of the usual installers:
| Database | Client library found in |
|---|---|
| PostgreSQL | Homebrew (libpq, postgresql@N), Postgres.app,
the EnterpriseDB installer (/Library/PostgreSQL/N), MacPorts |
| MySQL | the MySQL package (/usr/local/mysql), Homebrew
(mysql-client, mysql), MacPorts |
| MariaDB | Homebrew (mariadb-connector-c) |
| Firebird | the Firebird package
(/Library/Frameworks/Firebird.framework) |
| ODBC | unixODBC of Homebrew or MacPorts, and the iODBC of macOS |
| SQLite | the one of macOS |
Do not put the lib folder of a database server in DYLD_LIBRARY_PATH: those
folders carry their own libiconv, libssl and others, which hide the ones of
macOS and break other libraries.
Differences and limitations
- The SQL editor of the designer is Monaco, as on Windows, in the system WKWebView. Without the web view or its assets it falls back to the native editor with schema completion and the AI inline suggestion, as on Linux.
- Text is measured, laid out and painted with Core Text, the text engine of macOS, so the preview, the printed page and the PDF show the same glyphs.
- Printing: Lazarus 4.8 printed blank sheets on macOS (its Cocoa printer leaves the page margins undefined); Report Manager sets them itself, so printing works with an unpatched Lazarus too. Tested through the macOS printing system with a printer that writes each job to PDF. On Apple Silicon only the automatic tests have run so far.
The technical notes of the port are in docs/macos.md of the source code.