From The Cataclysm: Dark Days Ahead Wiki
Jump to: navigation, search


[edit] Howto Build Cataclysm DDA under OSX Mavericks

Please feel free to contribute to this document - that is the point of a wiki

This is a 'translation' of a markdown document I created when figuring out how to compile Cataclysm under OSX. As such, the formatting is crap right now, I will fix it as I have time. Additionally, this doesn't include my Xcode or CMake experiments and I also only tested this under OSX versions 10.8 & 10.9.

This document also contains notes from this wiki, the forum, and various sites around the net to create application bundles and distribution images. Nothing here is original to me - this is simply my notes describing the processes I have found to be successful at creating Cataclysm DDA on OSX.

Interestingly, I have not been successful at building static binaries with Xcode; nor an application bundle that launches. :( I have been successful at building all dependancies in Xcode something I have not been able to do at the command line. I would love help if you know either how to build the dependancies at the command line or you know how to get Xcode to build a launchable application bundle.

[edit] Set up the development environment.

Likely the most difficult part of getting things working under OSX is set up of the development enviornment. While some open source developers have no problems, many do. This is because Apple frequently changes things with system, security and bug updates. This often breaks 'non' Apple development enviornments which depend on its libraries. So it forces you to use Apple and compiler chain or to constantly 'fix' things that used to work - largely by trial and error. For this reason, while many 'package management systems' exist under OSX for installing and managing third party and open source software, for this article, I have choosen those which have over time been least effected by the regular system updates.

This however, comes at a price; namely the systems must install their own dependencies often duplicating existing system libraries. This is undesirable to some people, and an aceptable trade off for stability to others. Further, this is also an issue since if we develop dependancies on those libraries - they are by definition not part of a default Apple install, and must be packaged up in the application bundle for distrobution if we expect the application to run anywhere besides the development machine.

[edit] First install iTerm2, the de facto terminal for OSX.

While Cataclysm DDA maybe played with a single color, the best experience is with 256 colers. only supports 16 colors, where as iTerm2 is 256 colors. Additionally, redraw is very slow. This impact game play signifacntly when traveling left or right in the game. iTerm2 can be downloaded from the iTerm2 website, and has a drag and drop installer.

[edit] Install Xcode and the command line tools

To bootstrap the development enviornment we have to install a compiler. On OSX, Apple would like you to build everything in the Xcode IDE. However, our interests are not in the XCode IDE, but only in the 'command line tools' fortuntately, you do not even need to fire up the XCode IDE in order to install the 'command line tools.' All that is required is to invoke the following proprietary incantation at the command line to get the necessary tools to begin development.

xcode-select —install

[edit] Shared Libraries

A number of shared libraries (libsdl, libsdl\_image, libsdl\_ttf) or frameworks are required to build and run Cataclysm DDA. They can be installed via a package manager, you can download and installed binaries directly to your system or they can compiled and installed from source. Ideally we would download the source dependancies and compile them in the same directory as Cataclysm. However, I have been unsuccessful doing this at the command line as it requires rewriting the current Makefile. I have been successful doing this however with the Xcode IDE. Short of this I recommend that they be Installed with a package manager such as pkgsrc, MacPorts. Homebrew and Fink are both very popular OSX packaging systems, however in my experience are re-inventing the errors of the 1980's package system for unix system, so I personally choose not to relive the headaches of the 1980's all over again. Your opinions and experiences may vary, and you are more than welcome to use any package management system you choose.

[edit] pkgsrc

Is from NetBSD, and was ported to OSX in 2001, and has over 8k packages.

sudo ln -s /usr/bin/tar /usr/bin/gnutar

curl | sudo gnutar -zxpf - -C /


sudo pkgin -y update

[edit] Macports

Macports was started in 2002, and has over 17k ports for OSX.

Use the [ Macports installer] for Mavericks.

sudo port -v selfupdate

[edit] Install Pre-Compiled Libraries

[edit] gettext
[edit] SDL

SDL, SDL\_image, and SDL\_ttf are needed for the tiles build.

Option (1): [**SDL framework**](

[**SDL\_image framework**](

[**SDL\_ttf framework**](

Copy `SDL.framework`, `SDL_image.framework`, and `SDL_ttf.framework` to `/Library/Frameworks` or `/Users/name/Library/Frameworks`.

[edit] Compile Cataclysm


[edit] How to make

## 1. Install the SDL

SDL, SDL\_image, and SDL\_ttf are needed for the tiles build.

[**SDL framework**](

[**SDL\_image framework**](

[**SDL\_ttf framework**](

Copy 'SDL.framework', 'SDL_image.framework', and 'SDL_ttf.framework'

to '/Library/Frameworks' or '/Users/name/Library/Frameworks'.

Alternately, shared libraries (libsdl, libsdl\_image, libsdl\_ttf) can be used

instead of frameworks. Install with a package manager (Fink, MacPorts,

Homebrew, pkgsrc) or build and install from source.

### MacPorts

I used MacPorts for this build. I have used the disk images above, and the libraries are in my system folders where they would be found by my compile. However, they are not default on all systems and I did not want the application to assume they are there. Also, I did not want to build an application bundle that required people to install additional software to use it.

### Xcode

It is possible to build all the libraries from source with Xcode, both as static libraries and as frameworks, going forward this seems to be the preferred method, since the resulting 'products' can be easily, bundled with the Cataclysm compile.

Indeed, I think it would be best to create a 'mac' repo with the Xcode project, and use git 'submodules' for each of the SDL's and Cataclysm. This way we can pull pristine sources and build the 

* * *

## 2. Build Cataclysm from Source

### Pull from github

### Update Makefile

Change line 131 of the Makefile, this adds header padding for the dynamic linking later when we build the application bundle.

    LDFLAGS += -lintl -headerpad_max_install_names

### Make the application

Find the MacPorts SDL's in /opt/local when we compile

    export CXXFLAGS="-I/opt/local/include" 


I tried appending both of the above lines to the make command that follows; however, the builds fail when I do this. Unfortunately, I don't do enough development to understand why it works as an environment variable but not as an explicit argument passed to gcc via make.

    make clean


Always start with a clean slate. :-)

### Make Cataclysm-tiles

OSX users think everything should be graphical, so we make the tiles version because it can do both tiles and classic ascii depending on the settings in the options.

    make NATIVE=osx OSX_MIN=10.6 TILES=1 LOCALIZE=0

FYI: to make terminal only version do this:

    make NATIVE=osx RELEASE=1 OSX_MIN=10.6

    (make NATIVE=osx RELEASE=1 OSX_MIN=10.6 SDL=1)

This is according to the documentation

[edit] Building Cataclysm-DDA on Mac OS X

To build Cataclysm on Mac you'll have to get XCode with command line tools (or just download them separately from and Homebrew package manager.

      1. SDL

SDL, SDL\_image, and SDL\_ttf are needed for the tiles build.

Option (1): [**SDL framework**](

[**SDL\_image framework**](

[**SDL\_ttf framework**](

Copy `SDL.framework`, `SDL_image.framework`, and `SDL_ttf.framework` to `/Library/Frameworks` or `/Users/name/Library/Frameworks`.

Option (2): Alternately, shared libraries (libsdl, libsdl\_image, libsdl\_ttf) can be used instead of frameworks. Install with a package manager (Fink, MacPorts, Homebrew, pkgsrc) or build and install from source.

For Homebrew: `brew install sdl sdl_image sdl_ttf`

      1. ncurses, gettext

ncurses and gettext are needed for localization. Install with a package manager, or build from source and install.

 * ncurses needs wide character support enabled.

For Homebrew: `brew tap homebrew/dupes` `brew install gettext ncurses` `brew link --force gettext ncurses`

 * After you build Cataclysm remember to unlink gettext and ncurses with `brew unlink gettext ncurses` if you build other software, it might conflict with OSX versions. 
      1. Example builds:

Build a release version with SDL graphical tiles:


Build SDL version with shared libraries:


Build a release console version without localization:


Build a debug version with SDL ASCII:


    1. Run
   $ ./cataclysm


   $ ./cataclysm-tiles
      1. Make Options

`FRAMEWORK=1` use frameworks; omit to use libsdl, libsdl\_image, libsdl\_ttf.

`LOCALIZED=0` disable localization; enabled by default (requires gettext and ncurses with wide character support).

`NATIVE=osx` build for OS X.

`OSX_MIN=version` set `-mmacosx-version-min=` (for OS X > 10.5 set it to 10.6 or higher); omit for 10.5.

`RELEASE=1` build an optimized 'release' version.

`SDL=1` build the SDL version with ASCII characters.

`TILES=1` build the SDL version with graphical tiles.

      1. Application bundle packaging:

Create new folder and name it ``.

Put compiled binaries (`./cataclysm-tiles` and/or `./cataclysm`) with `./gfx/` and `./data/` folders inside `/`.

To bundle SDL libs copy `SDL.framework`, `SDL_image.framework`, and `SDL_ttf.framework` to `/` or shared libs homebrew installed from `/usr/local/Cellar/sdl*/version/lib/`.

Create folder `/` and file ./Cataclysm within it with this content:

  1. !/bin/sh

PWD=`dirname "${0}"` OSREV=`uname -r | cut -d. -f1` if [ "$OSREV" -ge 11 ] ; then

  export DYLD_LIBRARY_PATH=${PWD}/../Resources/libs
  export DYLD_FRAMEWORK_PATH=${PWD}/../Resources/libs


  export DYLD_FALLBACK_LIBRARY_PATH=${PWD}/../Resources/libs
  export DYLD_FALLBACK_FRAMEWORK_PATH=${PWD}/../Resources/libs

fi cd "${PWD}/../Resources/"; ./cataclysm-tiles

[edit] compile console

[edit] compile tiles

[edit] Create an Application Bundle

Based on instructions from First thing you should know is that an app bundle is just a directory. Let's examine the structure of a hypothetical







Info.plist is a plain XML file. You can edit it with a text editor or the Property List Editor app that comes bundled with XCode. (It's in /Developer/Applications/Utilities/ directory).

  1. The key things you need to include are:
    • **CFBundleName** - The name of the app.
    • **CFBundleIcon** - An Icon file assumed to be in Contents/Resources dir. Use the Icon Composer app to create the icon. (It's also in the /Developer/Applications/Utilities/ directory) You can just drag and drop a png onto it's window and should automatically generate the mip-levels for you.
    • **CFBundleExecutable** - Name of the executable file assumed to be in Contents/MacOS/ sub-folder.

There are lots more options, the ones listed above are only the bare minimum. Here's some Apple documentation on the Info.plist file and App bundle structure.

    1. Here's a sample Info.plist.

    <?xml version="1.0" encoding="UTF-8"?>

    !DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "">

    <plist version="1.0">
























  1. In a perfect world you could just drop your executable into the Contents/MacOS/ dir and be done. However, if your app has any non-standard dylib dependencies it won't work. Like Windows, MacOS comes with it's own special kind of DLL Hell.
    If you're using MacPorts to build libraries that you link against, the locations of the the dylibs will be hard-coded into your executable. If you run the app on a machine that has the dylibs in the exact same location, it will run fine. However, most users won't have them installed; when they double-click your app it will just crash.
    Before you distribute you executable you'll need to collect all the dylibs it loads and copy them into the app bundle. You will also need to edit the executable so that it will look for the dylibs in the correct place. i.e. where you copied them to.
    Hand editing an executable sounds dangerous right? Luckily there are command line tools to help.

otool -L executable_name

  1. This command will list all the dylibs that your app depends on. If you see any that are NOT in the System/Library or usr/lib folder, those are the ones you'll need to copy into the app bundle. Copy them into the /Contents/MacOS/ folder. Next you'll need to edit the executable to use the new dylibs.
    First, you need to make sure that you link using the -headerpad_max_install_names flag. This just makes sure that if the new dylib path is longer then the previous one, there will be room for it.
    1. Second, use the install_name_tool to change each dylib path.

install_name_tool -change existing_path_to_dylib @executable_path/blah.dylib executable_name

  1. As a practical example, Let's say your app uses libSDL, and otool lists it's location as "/opt/local/lib/libSDL-1.2.0.dylib".
    1. First copy it into the app bundle.

cp /opt/local/lib/libSDL-1.2.0.dylib

    1. Then edit the executable to use the new location (NOTE: make sure you built it with the -headerpad_max_install_names flag)

install_name_tool -change /opt/local/lib/libSDL-1.2.0.dylib @executable_path/libSDL-1.2.0.dylib

  1. Whew, we're almost done. Now there's a small issue with the current working directory.

When you start your app the current directory will be the directory above where the application is located. For example: If you place the in the /Applcations folder then the current directory when you launch the app will be the /Applications folder. Not the /Applications/ as you might expect.

    1. You can alter your app to account for this, or you can use this magic little launcher script that will change the current directory and launch your app.

#!/bin/bash cd "${0%/*}" ./foo

  1. Make sure you adjust the Info.plist file so that CFBundleExecutable points to the launch script and not to the previous executable.
    Ok, all done now. Luckily, once you know all this stuff you bury it in a build script.
  1. ## Copy tiles to the application bundle

The reason why we change the name is so that we can use the dataclysm-launcher script unmodified. If we did not do this, we would need to change the script. Either way it works, However, my goal is to alter as little as possible...

cp cataclysm-tiles

    1. Copy the launcher to the application bundle

cp cataclysm-launcher

  1. ## Add the libraries to the bundle

Incidentally, [dylibbuilder]( automates this, however, it can be done manually as described above with "otool -L binary_name" and "install_name_tool". Frankly, I am way to lazy to rebuild the wheel when it is already invented. :-)

./dylibbundler-0.4.4/dylibbundler -b -x ./Cataclysm-DDA-template/Contents/MacOS/cataclysm -d ./Cataclysm-DDA-template/Contents/Resources

    1. Copy game resources to the application bundle
      The result should look similar to this:

    └── Contents

        ├── Info.plist

        ├── MacOS

        │   ├──

        │   ├── cataclysm

        │   ├── cataclysm-launcher

        │   ├── data

        │   │   ├── FONTDATA

        │   │   ├── LAB_NOTES

        │   │   ├── NPC_HINTS

        │   │   ├── auto_pickup.txt

        │   │   ├── cataicon.ico

        │   │   ├── changelog.txt

        │   │   ├── credits

        │   │   ├── font

        │   │   │   ├── fixedsys.ttf

        │   │   │   └── terminus.fon

        │   │   ├── fontlist.txt

        │   │   ├── gfx.txt

        │   │   ├── json

        │   │   │   ├── bionics.json

        │   │   │   ├── dreams.json

        │   │   │   ├── item_groups.json

        │   │   │   ├── materials.json

        │   │   │   ├── mutations.json

        │   │   │   ├── professions.json

        │   │   │   ├── recipes.json

        │   │   │   ├── skills.json

        │   │   │   └── snippets.json

        │   │   ├── keymap.txt

        │   │   ├── motd

        │   │   ├── options.txt

        │   │   └── raw

        │   │       ├── items

        │   │       │   ├── ammo.json

        │   │       │   ├── archery.json

        │   │       │   ├── armor.json

        │   │       │   ├── books.json

        │   │       │   ├── comestibles.json

        │   │       │   ├── containers.json

        │   │       │   ├── instruments.json

        │   │       │   ├── melee.json

        │   │       │   ├── mods.json

        │   │       │   ├── ranged.json

        │   │       │   └── tools.json

        │   │       ├── monstergroups.json

        │   │       ├── names.json

        │   │       ├── parrot.json

        │   │       ├── sokoban.txt

        │   │       ├── vehicle_parts.json

        │   │       └── vehicles.json

        │   ├── gfx

        │   │   ├── DeonTileset

        │   │   │   ├── deontiles.png

        │   │   │   └── tile_config.json

        │   │   ├── HoderTileset

        │   │   │   ├── hodertiles.png

        │   │   │   └── tile_config.json

        │   │   ├── tile.png

        │   │   ├── tile_config.json

        │   │   ├── tile_config_template.json

        │   │   └── tinytile.png

        │   ├── logg.txt

        │   └── save

        └── Resources

            ├── ccda.icns

            ├── libSDL-1.2.0.dylib

            ├── libSDL_image-1.2.0.dylib

            ├── libSDL_ttf-2.0.0.dylib

            ├── libX11.6.dylib

            ├── libXau.6.dylib

            ├── libXdmcp.6.dylib

            ├── libXext.6.dylib

            ├── libXrandr.2.dylib

            ├── libXrender.1.dylib

            ├── libbz2.1.0.dylib

            ├── libfreetype.6.dylib

            ├── libpng15.15.dylib

            ├── libtiff.5.dylib

            ├── libxcb.1.dylib

            └── libz.1.dylib

[edit] Create a drag-and-drop installer

  1. (

The installer is a disk image which, when opened, displays a window with the game icon and a shortcut to the Applications folder on top of a background image which contains a simple message instructing the user on how to install the game.


    1. Creating a Writable Disk Image
      1. Open the **Disk Utility** app from `**/Applications/Utilities**` and click the **New Image** button in the toolbar.
        1. ![DU_newimage.jpg](DU_newimage.jpg)
      2. This will open a panel with properties of the new image. Enter the name, select a size big enough for your game, and select _Single partition - Apple Partition Map_ from **Partitions** dropbox. Then click the **Create** button.
        1. ![DU_properties.jpg](DU_properties.jpg)
      3. Disk Utility will now create and mount your new disk image.
    2. Install the Background Image
      1. Open the newly mounted volume in **Finder** and create a folder named `**Background**` in it. Then, copy your background image to this Background folder.
        1. ![backgroundimage.jpg](backgroundimage.jpg)
      2. Now, make sure the window with mounted volume is selected in **Finder** and is using icon view, then press **Command + J** to open the window's properties.
        1. ![backgroundproperties.jpg](backgroundproperties.jpg)
      3. In the **Background** section of the window select _Picture_, then drag your background image to the image area. The main window should now correctly show your background picture.
      4. To hide the Background folder, you need to open the **Terminal** app and use the following command:
        1. /Developer/Tools/SetFile -a V /Volumes/Your_Volume_Name/background

In our case that would be:

        1. /Developer/Tools/SetFile -a V /Volumes/UDKGame/background
    1. Game and Applications icons
      1. Drag your game to your installer's mounted volume.
        1. Then open your startup disk in **Finder** and create an alias to `**Applications**` folder:
        2. Select the folder.
        3. Choose **Make Alias** from the **File** menu. This will create "Applications alias" file.
        4. Drag this file to installer's volume and rename to "Applications".
          1. ![backgroundsample.jpg](backgroundsample.png)
      2. Now open window's properties once more (**Command + J**) and adjust **Icons Size** if desired and adjust the icons' positions and the window's size to fit the background image.
    2. Creat and install the disk image icon
      1. To change the icon of the disk image, select it's mounted volume icon on your desktop and press **Command + I** to open the info window. Do the same with your game's icon.
        1. ![UDKGameInfoicon.jpg](UDKGameInfoicon.jpg)
      2. Click the game's icon in the newly opened info window to select it and press **Command + C** to copy it.
      3. Switch to volume's info window, select it's icon in there, and press **Command + V** to paste.
      4. The mounted volume should now have the same icon as the game.
    3. Converting disk image
      1. Back in **Disk Utility**,
        1. unmount the installer's disk image and then, with the disk image selected,
        2. click the **Convert** button. Make sure you select **Compressed Image Format**, then click **Save**.
        3. You may need to confirm replacing old file in case you chose not to use different name for compressed image.
          1. ![DU_convert.jpg](DU_convert.jpg)
      2. And that's it. Once Disk Utility is done converting, you have a nice drag and drop installer ready for distribution.
Personal tools