The FPC compiler needs the XCode command-line developer tools installed. In short, open /Applications/Utilities/Terminal and execute
This is covered in more details in the FPC / Lazarus documentation:
Also, it seems that the latest macOS doesn't include gdb (a debugger, user underneath by Lazarus). Lazarus will warn you about this on the 1st run. You can install GDB e.g. using HomeBrew, just execute
brew install gdb. See GDB on OS X.
You can create your macOS applications in two ways:
This, in practice, means that your applications will use Cocoa (ev. deprecated Carbon). These are built-in native libraries on macOS. So, your programs don't require anything extra to distribute.
The default backend on macOS is
It's easiest to setup,
although it does not look pretty, and does not show a menu bar
Our programs will appear as part of "X11 server" on your desktop.
To compile, you also need to add this line to your
(see FPC documentation "Configuration file" to know where you can find your
-k-L/usr/X11/lib/ # Old version: # -Fl/usr/X11/lib/ # Should work equally well as far as I know, but it doesn't, for FPC 3.0.4/3.0.5
If, when running our applications, you get an error
that glX extension not found:
Check do you have a
/usr/X11R6 symlink (e.g. by running
ls /usr/X11R6 in the terminal).
Some versions of XQuartz
seem to not install it (see here).
You can fix it on your system by:
sudo ln -s /usr/X11 /usr/X11R6
Alternative fix (see here):
sudo /usr/libexec/x11-select /opt/X11 sudo chmod a+rX /usr/X11/ /usr/X11R6/
you can switch the backend to
Do this by adding this line to your
fpc.cfg file (see FPC documentation "Configuration file" to know where you can find your
This looks better (the program will still be part of the "X11 server", but it will have a nice menu bar and dialog windows using GTK).
Alternatively, you can switch the backend of
This uses Lazarus under the hood, and this way we will use Cocoa
(ev. deprecated Carbon)
This means that TCastleWindowBase will actually use Lazarus
This looks nice and native.
To do this, use the package
This will give you
CastleWindow unit that uses LCL and requires
the castle_components package.
If you open an existing source code,
like view3dscene, you will have to change the dependencies in Lazarus Project inspector
alternative_castle_window_based_on_lcl instead of
On macOS, the default LCL widgetset is Carbon right now. It changed to Cocoa in Lazarus trunk on 2020-07, but this change did not land in last Lazarus stable release yet, 2.0.10.
Only Cocoa supports 64-bit applications and latest macOS Catalina requires all applications to be 64-bit. So you just have to use Cocoa on new macOS.
Advantages and disadvantages of using LCL (as opposed to X11 / GTK solutions):
Good: native look, application has a normal menu bar,
shows native dialog boxes (to open/save file, choose color and such)
and generally looks and feels like every other macOS application.
Lazarus compiles it into a bundle like
that can be easily installed by dragging to your Applications
Good: no extra dependencies, Carbon and Cocoa are already part of every macOS installation. (No dependencies on X11, GTK.)
Bad: There are issues with LCL event loop. Some of them (not being able to get Update events continuously) are in bare LCL, some of them (the need to call Application.Run, not just loop using Application.ProcessMessages) are specific to LCL-Carbon. The former (Update issues when using mouse look or dragging with mouse) is somewhat workarounded on our side now (to not "stutter" when using mouse look), but the problem is still noticeable (mouse look under other TCastleWindowBase backends is much smoother).
It would be good to implement
CastleWindow backend based on Cocoa (without using Lazarus LCL).
This would provide all above advantages, without disadvantages.
Can you help us with this?
It's a matter of creating and implementing a file
See engine sources.
See at other "backends" (like GTK, WinAPI, Xlib, LCL)
for examples how to implement such thing, everything is inside
Alternatively, send Michalis a simple and clear example of FPC program using Cocoa that 1. creates and shows a window 2. with menu bar 3. and with OpenGL context area covering the window. I should be able to port such example to my "CastleWindow" then.
For macOS older than Tiger (that is, 10.3 or older): install OpenAL to have game sounds. It may be downloaded from Creative, see download links from openal.org downloads. For macOS since Tiger, OpenAL comes already preinstalled. Even without OpenAL installed, all our programs will still work fine, you just will not get any sound.
Without vorbisfile, all our programs will still work fine, but you will not hear OggVorbis music.
If you want to use external libpng implementation in your programs, that you will also need libpng to open and save images and textures in PNG format. It may be installed using MacPorts, Homebrew or Fink.
Note that this is not necessary. If we don't find libpng, we will fallback to reading PNG using FpImage, which works too (but is slower, which may be significant if you load a lot of PNG files).
To actually compile our programs on macOS, you need the Free Pascal Compiler. For comfortable RAD development, install also Lazarus (FPC is already included inside Lazarus installations, if you choose normal packages).
Besides easy upgrades, the advantage of using the package manager to install the compiler is that it's easier then to install the libraries (like GTK2) with the same architecture (32-bit vs 64-bit). Otherwise, be careful to watch for it yourself: your system may host both 32-bit and 64-bit binaries and libraries, but to compile a 64-bit application, you will need a compiler (FPC) that targets 64-bit processors and 64-bit libraries.
On modern macOS versions, you usually just want to install x86_64 libraries, and the FPC compiler for Darwin+x86_64.
To install GTK and FPC, simply do:
sudo port install gtkglext # TODO: update this command to only install gtk2 sudo port install fpc
Then create your local FPC config, and add there macports libraries:
~/.fpc.cfgand paste there
~/.fpc.cfgadd this line:
/opt/local/lib/fpc/bin, so add something like this to your
To install FPC with Homebrew, you simply do
brew install fpc
fpc is already on $PATH, so it's comfortable out-of-the-box.
Installing additional libraries, like GTK, is equally trivial.
To use the libraries installed by fink, you may have to add them to your libraries path. Execute a command like this (in the same shell (terminal), before executing our programs):
You can add this line to your
~/.bashrc to have it automatically
To compile applications using GTK (
you should additionally install
the fink "
pango1-xft2-shlibs" package. Simple "
fink install pango1-xft2-shlibs"
should do the trick. This is necessary for successful linking.
If you use any libraries from fink, the linker must know their locations.
Add this line to your
fpc.cfg file (see FPC documentation "Configuration file" to know where you can find your
A bunch of information about packaging your programs for macOS follows.
Make "macOS bundle". It's basically a directory pretending to be an application.
You can use Lazarus to create macOS bundle. Or you can use our create_macosx_bundle.sh script. The example usage is inside view3dscene and castle-view-image sources.
Optionally, add libraries (like libpng and vorbisfile) to the bundle.
If you link to them dynamically (e.g. using our
you should load them from a path relative to
BundlePath + 'Contents/MacOS/libpng.dylib'.
See macOS Libraries on FPC wiki for general instructions how to include library inside a bundle.
Pack the bundle into a
See Building Fancy DMG Images on macOS
for nice description how to make the directories inside dmg look pretty,
so you can visually suggest user to drag your application in the Applications
Alternatively, you can pack the bundle into a regular zip file. There are convincing arguments that using ZIP is actually more user-friendly than DMG (users can just double-click to unpack, and they have the application; they don't need to understand how "disk image" works). See also here for discussion. And making zip is definitely simpler.
Alternative method of distribution macOS applications is the package manager (.pkg). For normal applications (like games) the simpler .dmg is a better choice.
Behaviour of the data directory (
castle-data: protocol) on macOS:
On macOS, if you run the application through the "application bundle", then we expect the data to be found inside
MyApplication.app/Contents/Resources/data subdirectory. This way user can move around
MyApplication.app to move, install and uninstall the application.
MyApplication.app/Contents/Resources/data subdirectory is not found, we will use the
data subdirectory that is sibling to
MyApplication.app. This feature is intended to be used only during development. This way things works "out of the box" if you run through Lazarus, with checkbox “Use Application Bundle for running and debugging”.
When distributing the application to the end users, you should manually copy the “data” subdirectory inside the bunde (to
In case of compiling and packaging using our build tool we could do it automatically at some point (although it’s not implemented for now)
In case of using Lazarus to create the bundle — you will have to do it manually always.
I recommend writing a simple shell script to create the bundle. Copy the data like this:
rm -Rf MyApplication.app/Contents/Resources/data cp -R data/ MyApplication.app/Contents/Resources
Copyright Michalis Kamburelis and other Castle Game Engine developers.
Thank you to Paweł Wojciechowicz from Cat-astrophe Games for various graphics.
This documentation is also open-source and you can even redistribute it on open-source terms.