Dependencies of our programs on Mac OS X
We did it by using the LCL backend of CastleWindow. This uses Lazarus LCL under the hood, wrapping Lazarus TForm and TOpenGLControl inside a TCastleWindow. Although it still has some issues (see below), it gives us native look and a lot of stuff "for free".
Developers: If you want to use these features, you have to 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. We hope to make it easier in the future by using the "Provides" option of Lazarus packages, but right now it doesn't do what we want — it can not "pull" extra depencies present in alternative package but not present in original.
This change allows CastleWindow-based programs, like view3dscene, to have native look on Mac OS X. Of course in your own programs you can also use Lazarus forms directly (with our TCastleControl) — this was always possible, and gives you the same native look through Lazarus.
On Mac OS X, the default LCL widgetset is Carbon right now.
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 Mac OS X application. Lazarus compiles it into a bundle like view3dscene.app that can be easily installed by dragging to your Applications directory.
Good: no extra dependencies, Carbon is already part of every Mac OS X installation. (No dependencies on X11, GTK, GTKGlExt etc.)
Bad: Unfortunately, Carbon is deprecated by Apple (although there are many applications using it, including Lazarus IDE itself). It is available only for 32-bit applications.
In time, this will be resolved in LCL when Cocoa widgetset will be more complete. Right now, Carbon implementation is just more complete than Cocoa in LCL, see also Choice of Lazarus LCL widgetsets (for Mac OS X).
It may also be resolved on our side if we ever make direct CastleWindow backend based on Cocoa (without using Lazarus LCL):
- It's a matter of creating and implementing a file castle_game_engine/src/window/castlewindow_cocoa.inc, based on castle_game_engine/src/window/castlewindow_backend_template.inc. See engine sources. See at other "backends" (like GTK, WinAPI, Xlib, LCL) for examples how to implement such thing, everything is inside src/window/ dir.
- 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.
- See e.g. FPC "OS_X Programming Tips" for pointers. If you're a developer familiar with Mac OS X native toolkit and FreePascal, your help will be much appreciated.
Bad: There are issues with LCL event loop. Some of them (not being able to get Update events continously) 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 TCastleWindow backends is much smoother).
For the above reasons:
- If you make normal game (that doesn't need
any menu or dialog boxes) consider using
the (default) CASTLE_WINDOW_XLIB backend on Mac OS X.
Using X11 (Xlib) is not a problem on Mac OS X.
And this way you get a perfect speed and smoothly working event loop
(with smooth mouse look).
Although full-screen is ugly on Xlib, there's no way to hide dock over fullscreen application in this situation... Easiest solution in this case is to keep your game windowed on Mac OS X.
- Only if you make tool-like program (that needs menu and dialog boxes) then CASTLE_WINDOW_LCL is a good choice. It will look perfectly native. Although at the cost of not perfect mouse look. Alternatively, you can use CASTLE_WINDOW_GTK_2 on Mac OS X, that has both nice menu/dialogs and a smooth mouse look, but it requires installation of some special libraries (GTK etc. from fink).
- If you make normal game (that doesn't need any menu or dialog boxes) consider using the (default) CASTLE_WINDOW_XLIB backend on Mac OS X. Using X11 (Xlib) is not a problem on Mac OS X. And this way you get a perfect speed and smoothly working event loop (with smooth mouse look).
view3dscene uses a standard OS console for some stuff (e.g. for Console -> Print Current Camera...). You will not see this console if you run the program using the bundle (by double-clicking on the app in Finder, or in dock...).
To see the console output, run view3dscene from terminal:
cd directory-where-you-installed-view3dscene/ ./view3dscene.app/Contents/MacOS/view3dscene
Before you run our programs on Mac OS X, you may need to install some additional software:
For OpenGL programs, X11 is needed (may be found on Mac OS X install CD). Install it, and run before executing our programs.
Our programs will appear as part of "X11 server" on your desktop. If you start our program outside of X11 (like by double-clicking the application in the Finder), the window may not be "focused" (receiving key events) at start. Just click the window to make it focused.
Somewhat internal notes: if you start our program from within X11 xterm, it will be focused at the start. When you start us outside of X11, and we detect that the default X display doesn't work, we automatically use display name :0 under Mac OS X. This way we attach to the running X server, even if you execute us from some other application. You can also explicitly start with command-line option --display=:0, or always run us from X11 xterm, to use given X display.
libpng (may be installed by fink), if you want to be able to open any images/textures etc. stored in PNG images.
When CastleWindow uses GTK backend (view3dscene compiled by default script does use GTK, "The Castle" compiled by default script doesn't use GTK): GTK and GtkGLExt are required. They should be installed using fink. Follow fink installation instructions, then simple command "fink install gtkglext1" should install all the libraries we require (if in trouble, look for packages by "fink list xxx").
Note that binary fink packages are usually too old (if available at all...). So just go with the "source" installation. Don't be afraid if you're not a programmer — the process goes smoothly, just follow the instructions and be patient.
It is not necessary to use any fink packages from unstable branch.
vorbisfile (may be installed by fink). Without this, all our programs will still work fine, but you will not hear OggVorbis music.
For Mac OS X older than Tiger (that is, 10.3 or older): get OpenAL for game sound. It may be downloaded from Creative, see download links from openal.org downloads. For Mac OS X since Tiger, OpenAL comes already preinstalled. Even without OpenAL installed, all our programs will still work fine, you just will not get any sound.
For libs installed by fink, you may have to add them to your libs path by command like
export LD_LIBRARY_PATH=/sw/lib:"$LD_LIBRARY_PATH"before executing programs. (you can add this to your .bashrc or similar file for comfort).
To actually compile our programs on Mac OS X, developers may need to install a little more stuff. Of course FreePascal Compiler is required. For comfortable RAD development, you may also consider Lazarus (FPC is already included inside Lazarus installations, if you choose normal packages).
As of fink 0.29.21 (on Mac OS X 10.6.7), 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.
The linker must know the location of fink and X11 libraries. If you have installed fink and X11 in standard locations, you can simply add these lines to your /etc/fpc.cfg file:
A bunch of information about packaging your programs for Mac OS X follows.
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 (see script create_macosx_bundle.sh in our SVN repository), example usage is inside view3dscene sources.
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.
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.