Mac OS X notes and requirements


1. Compiling on Mac OS X

The FPC compiler needs the XCode command-line developer tools installed. In short, open /Applications/Utilities/Terminal and execute xcode-select --install.

This is covered in more details in the FPC / Lazarus documentation:

Also, it seems that the latest Mac OS X 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.

2. GUI libraries: Carbon/Cocoa? X11? X11 + GTK?

You can create your Mac OS X applications in two ways:

  1. You can use Lazarus forms, and LCL (Lazarus Component Library). To use the engine, simply drop a TCastleControl component on a Lazarus form.

    This, in practice, means that your applications will use Carbon or Cocoa. These are built-in native libraries on Mac OS X. So, your programs don't require anything extra to distribute.

  2. Alternatively, you can create your windows using our own TCastleWindow class. Our TCastleWindow can use various backends under the hood:

    • The default backend on Mac OS X is CASTLE_WINDOW_XLIB. It's easiest to setup, although it does not look pretty, and does not show a menu bar (TCastleWindowCustom.MainMenu).

      It requires installing XQuartz. (On older Mac OS X versions, install instead X11 Server from your Mac OS X install CD. For newer Mac OS X, XQuartz is the way to go.)

      Our programs will appear as part of "X11 server" on your desktop.

      To compile, you also need to add this line to your fpc.cfg file (see FPC documentation "Configuration file" to know where you can find your fpc.cfg file):


      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/
    • Alternatively, you can switch the backend to CASTLE_WINDOW_GTK_2. Do this by adding this line to your fpc.cfg file (see FPC documentation "Configuration file" to know where you can find your fpc.cfg file):


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

      In addition to X11 (see above), your application will use GTK libraries. Install them using MacPorts, Homebrew or Fink. Yes, all three options are tested and OK. Look for packages called gtk2.

    • Alternatively, you can switch the backend of TCastleWindow to CASTLE_WINDOW_LCL. This uses Lazarus under the hood, and this way we will use Carbon or Cocoa instead. This means that TCastleWindow will actually use Lazarus TForm and TOpenGLControl internally.

      This looks nice and native.

      To do this, use the package alternative_castle_window_based_on_lcl.lpk instead of castle_window.lpk. 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 to use alternative_castle_window_based_on_lcl instead of castle_window.

3. Advantages and disadvantages of using LCL (Carbon/Cocoa)

On Mac OS X, the default LCL widgetset is Carbon right now.

4. Other libraries that may be required

5. Notes specific to particular Mac OS X package managers

5.1. Consider installing FPC and Lazarus through them too

To actually compile our programs on Mac OS X, 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).

You can install them by downloading from their respective webpages, or you can install them by a Mac OS X package manager like MacPorts, Homebrew or Fink.

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 Mac OS X versions, you usually just want to install x86_64 libraries, and the FPC compiler for Darwin+x86_64.

5.2. MacPorts

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:

5.3. Homebrew

To install FPC with Homebrew, you simply do

brew install fpc

The fpc is already on $PATH, so it's comfortable out-of-the-box.

Installing additional libraries, like GTK, is equally trivial.

5.4. Fink

6. Creating Mac OS X applications

A bunch of information about packaging your programs for Mac OS X follows.

  1. Make "Mac OS X bundle". It's basically a directory pretending to be an application.

    You can use Lazarus to create Mac OS X bundle. Or you can use our script. The example usage is inside view3dscene and castle-view-image sources.

  2. Optionally, add libraries (like libpng and vorbisfile) to the bundle. If you link to them dynamically (e.g. using our TDynLib.Load), you should load them from a path relative to BundlePath, like BundlePath + 'Contents/MacOS/libpng.dylib'.

    See Mac OS X Libraries on FPC wiki for general instructions how to include library inside a bundle.

  3. Pack into a nice .dmg file. See Building Fancy DMG Images on Mac OS X 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 folder.

    Alternative method of distribution Mac OS X applications is the package manager (.pkg). For normal applications (like games) the simpler .dmg is a better choice.