| 1 | ============================================================================== |
| 2 | Using the Simple DirectMedia Layer with Mac OS X |
| 3 | ============================================================================== |
| 4 | |
| 5 | These instructions are for people using Apple's Mac OS X (pronounced |
| 6 | "ten"). |
| 7 | |
| 8 | From the developer's point of view, OS X is a sort of hybrid Mac and |
| 9 | Unix system, and you have the option of using either traditional |
| 10 | command line tools or Apple's IDE Xcode. |
| 11 | |
| 12 | To build SDL using the command line, use the standard configure and make |
| 13 | process: |
| 14 | |
| 15 | ./configure |
| 16 | make |
| 17 | sudo make install |
| 18 | |
| 19 | You can also build SDL as a Universal library (a single binary for both |
| 20 | PowerPC and Intel architectures), on Mac OS X 10.4 and newer, by using |
| 21 | the fatbuild.sh script in build-scripts: |
| 22 | sh build-scripts/fatbuild.sh |
| 23 | sudo build-scripts/fatbuild.sh install |
| 24 | This script builds SDL with 10.2 ABI compatibility on PowerPC and 10.4 |
| 25 | ABI compatibility on Intel architectures. For best compatibility you |
| 26 | should compile your application the same way. A script which wraps |
| 27 | gcc to make this easy is provided in test/gcc-fat.sh |
| 28 | |
| 29 | To use the library once it's built, you essential have two possibilities: |
| 30 | use the traditional autoconf/automake/make method, or use Xcode. |
| 31 | |
| 32 | ============================================================================== |
| 33 | Using the Simple DirectMedia Layer with a traditional Makefile |
| 34 | ============================================================================== |
| 35 | |
| 36 | An existing autoconf/automake build system for your SDL app has good chances |
| 37 | to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary |
| 38 | that you can distribute to users, you need to put the generated binary into a |
| 39 | so called "bundle", which basically is a fancy folder with a name like |
| 40 | "MyCoolGame.app". |
| 41 | |
| 42 | To get this build automatically, add something like the following rule to |
| 43 | your Makefile.am: |
| 44 | |
| 45 | bundle_contents = APP_NAME.app/Contents |
| 46 | APP_NAME_bundle: EXE_NAME |
| 47 | mkdir -p $(bundle_contents)/MacOS |
| 48 | mkdir -p $(bundle_contents)/Resources |
| 49 | echo "APPL????" > $(bundle_contents)/PkgInfo |
| 50 | $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/ |
| 51 | |
| 52 | You should replace EXE_NAME with the name of the executable. APP_NAME is what |
| 53 | will be visible to the user in the Finder. Usually it will be the same |
| 54 | as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME |
| 55 | usually is "TestGame". You might also want to use @PACKAGE@ to use the package |
| 56 | name as specified in your configure.in file. |
| 57 | |
| 58 | If your project builds more than one application, you will have to do a bit |
| 59 | more. For each of your target applications, you need a seperate rule. |
| 60 | |
| 61 | If you want the created bundles to be installed, you may want to add this |
| 62 | rule to your Makefile.am: |
| 63 | |
| 64 | install-exec-hook: APP_NAME_bundle |
| 65 | rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app |
| 66 | mkdir -p $(DESTDIR)$(prefix)/Applications/ |
| 67 | cp -r $< /$(DESTDIR)$(prefix)Applications/ |
| 68 | |
| 69 | This rule takes the Bundle created by the rule from step 3 and installs them |
| 70 | into $(DESTDIR)$(prefix)/Applications/. |
| 71 | |
| 72 | Again, if you want to install multiple applications, you will have to augment |
| 73 | the make rule accordingly. |
| 74 | |
| 75 | |
| 76 | But beware! That is only part of the story! With the above, you end up with |
| 77 | a bare bone .app bundle, which is double clickable from the Finder. But |
| 78 | there are some more things you should do before shipping yor product... |
| 79 | |
| 80 | 1) The bundle right now probably is dynamically linked against SDL. That |
| 81 | means that when you copy it to another computer, *it will not run*, |
| 82 | unless you also install SDL on that other computer. A good solution |
| 83 | for this dilemma is to static link against SDL. On OS X, you can |
| 84 | achieve that by linkinag against the libraries listed by |
| 85 | sdl-config --static-libs |
| 86 | instead of those listed by |
| 87 | sdl-config --libs |
| 88 | Depending on how exactly SDL is integrated into your build systems, the |
| 89 | way to achieve that varies, so I won't describe it here in detail |
| 90 | 2) Add an 'Info.plist' to your application. That is a special XML file which |
| 91 | contains some meta-information about your application (like some copyright |
| 92 | information, the version of your app, the name of an optional icon file, |
| 93 | and other things). Part of that information is displayed by the Finder |
| 94 | when you click on the .app, or if you look at the "Get Info" window. |
| 95 | More information about Info.plist files can be found on Apple's homepage. |
| 96 | |
| 97 | |
| 98 | As a final remark, let me add that I use some of the techniques (and some |
| 99 | variations of them) in Exult and ScummVM; both are available in source on |
| 100 | the net, so feel free to take a peek at them for inspiration! |
| 101 | |
| 102 | |
| 103 | ============================================================================== |
| 104 | Using the Simple DirectMedia Layer with Xcode |
| 105 | ============================================================================== |
| 106 | |
| 107 | These instructions are for using Apple's Xcode IDE to build SDL applications. |
| 108 | |
| 109 | - First steps |
| 110 | |
| 111 | The first thing to do is to unpack the Xcode.tar.gz archive in the |
| 112 | top level SDL directory (where the Xcode.tar.gz archive resides). |
| 113 | Because Stuffit Expander will unpack the archive into a subdirectory, |
| 114 | you should unpack the archive manually from the command line: |
| 115 | cd [path_to_SDL_source] |
| 116 | tar zxf Xcode.tar.gz |
| 117 | This will create a new folder called Xcode, which you can browse |
| 118 | normally from the Finder. |
| 119 | |
| 120 | - Building the Framework |
| 121 | |
| 122 | The SDL Library is packaged as a framework bundle, an organized |
| 123 | relocatable folder heirarchy of executible code, interface headers, |
| 124 | and additional resources. For practical purposes, you can think of a |
| 125 | framework as a more user and system-friendly shared library, whose library |
| 126 | file behaves more or less like a standard UNIX shared library. |
| 127 | |
| 128 | To build the framework, simply open the framework project and build it. |
| 129 | By default, the framework bundle "SDL.framework" is installed in |
| 130 | /Library/Frameworks. Therefore, the testers and project stationary expect |
| 131 | it to be located there. However, it will function the same in any of the |
| 132 | following locations: |
| 133 | |
| 134 | ~/Library/Frameworks |
| 135 | /Local/Library/Frameworks |
| 136 | /System/Library/Frameworks |
| 137 | |
| 138 | - Build Options |
| 139 | There are two "Build Styles" (See the "Targets" tab) for SDL. |
| 140 | "Deployment" should be used if you aren't tweaking the SDL library. |
| 141 | "Development" should be used to debug SDL apps or the library itself. |
| 142 | |
| 143 | - Building the Testers |
| 144 | Open the SDLTest project and build away! |
| 145 | |
| 146 | - Using the Project Stationary |
| 147 | Copy the stationary to the indicated folders to access it from |
| 148 | the "New Project" and "Add target" menus. What could be easier? |
| 149 | |
| 150 | - Setting up a new project by hand |
| 151 | Some of you won't want to use the Stationary so I'll give some tips: |
| 152 | * Create a new "Cocoa Application" |
| 153 | * Add src/main/macosx/SDLMain.m , .h and .nib to your project |
| 154 | * Remove "main.c" from your project |
| 155 | * Remove "MainMenu.nib" from your project |
| 156 | * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path |
| 157 | * Add "$(HOME)/Library/Frameworks" to the frameworks search path |
| 158 | * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS" |
| 159 | * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib" |
| 160 | * Add your files |
| 161 | * Clean and build |
| 162 | |
| 163 | - Building from command line |
| 164 | Use pbxbuild in the same directory as your .pbproj file |
| 165 | |
| 166 | - Running your app |
| 167 | You can send command line args to your app by either invoking it from |
| 168 | the command line (in *.app/Contents/MacOS) or by entering them in the |
| 169 | "Executibles" panel of the target settings. |
| 170 | |
| 171 | - Implementation Notes |
| 172 | Some things that may be of interest about how it all works... |
| 173 | * Working directory |
| 174 | As defined in the SDL_main.m file, the working directory of your SDL app |
| 175 | is by default set to its parent. You may wish to change this to better |
| 176 | suit your needs. |
| 177 | * You have a Cocoa App! |
| 178 | Your SDL app is essentially a Cocoa application. When your app |
| 179 | starts up and the libraries finish loading, a Cocoa procedure is called, |
| 180 | which sets up the working directory and calls your main() method. |
| 181 | You are free to modify your Cocoa app with generally no consequence |
| 182 | to SDL. You cannot, however, easily change the SDL window itself. |
| 183 | Functionality may be added in the future to help this. |
| 184 | |
| 185 | |
| 186 | Known bugs are listed in the file "BUGS" |