README-macosx.txt
author Sam Lantinga <slouken@libsdl.org>
Mon, 11 Nov 2013 22:43:05 -0800
changeset 7965 d3cbe8ecb1af
parent 7801 f00cc0a8cd5d
child 8191 b50f4ae6d5f2
permissions -rw-r--r--
Fixed assertion when quickly toggling from fullscreen back to fullscreen:
"Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'backgroundWindows not nil in enterFullScreenTransitionWithOptions:animated:activatingIt:'"

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