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