docs/README-macosx.md
changeset 9025 d09d4b578e77
parent 9023 276802355854
child 9066 c2af3ff967cc
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/README-macosx.md	Tue Jul 29 08:04:15 2014 -0700
     1.3 @@ -0,0 +1,225 @@
     1.4 +Mac OS X
     1.5 +==============================================================================
     1.6 +
     1.7 +These instructions are for people using Apple's Mac OS X (pronounced
     1.8 +"ten").
     1.9 +
    1.10 +From the developer's point of view, OS X is a sort of hybrid Mac and
    1.11 +Unix system, and you have the option of using either traditional
    1.12 +command line tools or Apple's IDE Xcode.
    1.13 +
    1.14 +To build SDL using the command line, use the standard configure and make
    1.15 +process:
    1.16 +
    1.17 +	./configure
    1.18 +	make
    1.19 +	sudo make install
    1.20 +
    1.21 +You can also build SDL as a Universal library (a single binary for both
    1.22 +32-bit and 64-bit Intel architectures), on Mac OS X 10.7 and newer, by using
    1.23 +the fatbuild.sh script in build-scripts:
    1.24 +	sh build-scripts/fatbuild.sh
    1.25 +	sudo build-scripts/fatbuild.sh install
    1.26 +This script builds SDL with 10.5 ABI compatibility on i386 and 10.6
    1.27 +ABI compatibility on x86_64 architectures.  For best compatibility you
    1.28 +should compile your application the same way.  A script which wraps
    1.29 +gcc to make this easy is provided in test/gcc-fat.sh
    1.30 +
    1.31 +Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK
    1.32 +(even if you target back to 10.5 systems). PowerPC support for Mac OS X has
    1.33 +been officially dropped as of SDL 2.0.2.
    1.34 +
    1.35 +To use the library once it's built, you essential have two possibilities:
    1.36 +use the traditional autoconf/automake/make method, or use Xcode.
    1.37 +
    1.38 +==============================================================================
    1.39 +Caveats for using SDL with Mac OS X
    1.40 +==============================================================================
    1.41 +
    1.42 +Some things you have to be aware of when using SDL on Mac OS X:
    1.43 +
    1.44 +- If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
    1.45 +  SDL will not register its own. This means that SDL will not terminate using
    1.46 +  SDL_Quit if it receives a termination request, it will terminate like a 
    1.47 +  normal app, and it will not send a SDL_DROPFILE when you request to open a
    1.48 +  file with the app. To solve these issues, put the following code in your 
    1.49 +  NSApplicationDelegate implementation:
    1.50 +
    1.51 +  - (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
    1.52 +  {
    1.53 +      if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
    1.54 +          SDL_Event event;
    1.55 +          event.type = SDL_QUIT;
    1.56 +          SDL_PushEvent(&event);
    1.57 +      }
    1.58 +
    1.59 +      return NSTerminateCancel;
    1.60 +  }
    1.61 +
    1.62 +  - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
    1.63 +  {
    1.64 +      if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
    1.65 +          SDL_Event event;
    1.66 +          event.type = SDL_DROPFILE;
    1.67 +          event.drop.file = SDL_strdup([filename UTF8String]);
    1.68 +          return (SDL_PushEvent(&event) > 0);
    1.69 +      }
    1.70 +
    1.71 +      return NO;
    1.72 +  }
    1.73 +
    1.74 +==============================================================================
    1.75 +Using the Simple DirectMedia Layer with a traditional Makefile
    1.76 +==============================================================================
    1.77 +
    1.78 +An existing autoconf/automake build system for your SDL app has good chances
    1.79 +to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
    1.80 +that you can distribute to users, you need to put the generated binary into a
    1.81 +so called "bundle", which basically is a fancy folder with a name like
    1.82 +"MyCoolGame.app".
    1.83 +
    1.84 +To get this build automatically, add something like the following rule to
    1.85 +your Makefile.am:
    1.86 +
    1.87 +bundle_contents = APP_NAME.app/Contents
    1.88 +APP_NAME_bundle: EXE_NAME
    1.89 +	mkdir -p $(bundle_contents)/MacOS
    1.90 +	mkdir -p $(bundle_contents)/Resources
    1.91 +	echo "APPL????" > $(bundle_contents)/PkgInfo
    1.92 +	$(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
    1.93 +
    1.94 +You should replace EXE_NAME with the name of the executable. APP_NAME is what
    1.95 +will be visible to the user in the Finder. Usually it will be the same
    1.96 +as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
    1.97 +usually is "TestGame". You might also want to use @PACKAGE@ to use the package
    1.98 +name as specified in your configure.in file.
    1.99 +
   1.100 +If your project builds more than one application, you will have to do a bit
   1.101 +more. For each of your target applications, you need a separate rule.
   1.102 +
   1.103 +If you want the created bundles to be installed, you may want to add this
   1.104 +rule to your Makefile.am:
   1.105 +
   1.106 +install-exec-hook: APP_NAME_bundle
   1.107 +	rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
   1.108 +	mkdir -p $(DESTDIR)$(prefix)/Applications/
   1.109 +	cp -r $< /$(DESTDIR)$(prefix)Applications/
   1.110 +
   1.111 +This rule takes the Bundle created by the rule from step 3 and installs them
   1.112 +into $(DESTDIR)$(prefix)/Applications/.
   1.113 +
   1.114 +Again, if you want to install multiple applications, you will have to augment
   1.115 +the make rule accordingly.
   1.116 +
   1.117 +
   1.118 +But beware! That is only part of the story! With the above, you end up with
   1.119 +a bare bone .app bundle, which is double clickable from the Finder. But
   1.120 +there are some more things you should do before shipping your product...
   1.121 +
   1.122 +1) The bundle right now probably is dynamically linked against SDL. That 
   1.123 +   means that when you copy it to another computer, *it will not run*,
   1.124 +   unless you also install SDL on that other computer. A good solution
   1.125 +   for this dilemma is to static link against SDL. On OS X, you can
   1.126 +   achieve that by linking against the libraries listed by
   1.127 +     sdl-config --static-libs
   1.128 +   instead of those listed by
   1.129 +     sdl-config --libs
   1.130 +   Depending on how exactly SDL is integrated into your build systems, the
   1.131 +   way to achieve that varies, so I won't describe it here in detail
   1.132 +2) Add an 'Info.plist' to your application. That is a special XML file which
   1.133 +   contains some meta-information about your application (like some copyright
   1.134 +   information, the version of your app, the name of an optional icon file,
   1.135 +   and other things). Part of that information is displayed by the Finder
   1.136 +   when you click on the .app, or if you look at the "Get Info" window.
   1.137 +   More information about Info.plist files can be found on Apple's homepage.
   1.138 +
   1.139 +
   1.140 +As a final remark, let me add that I use some of the techniques (and some
   1.141 +variations of them) in Exult and ScummVM; both are available in source on
   1.142 +the net, so feel free to take a peek at them for inspiration!
   1.143 +
   1.144 +
   1.145 +==============================================================================
   1.146 +Using the Simple DirectMedia Layer with Xcode
   1.147 +==============================================================================
   1.148 +
   1.149 +These instructions are for using Apple's Xcode IDE to build SDL applications.
   1.150 +
   1.151 +- First steps
   1.152 +
   1.153 +The first thing to do is to unpack the Xcode.tar.gz archive in the
   1.154 +top level SDL directory (where the Xcode.tar.gz archive resides).
   1.155 +Because Stuffit Expander will unpack the archive into a subdirectory,
   1.156 +you should unpack the archive manually from the command line:
   1.157 +	cd [path_to_SDL_source]
   1.158 +	tar zxf Xcode.tar.gz
   1.159 +This will create a new folder called Xcode, which you can browse
   1.160 +normally from the Finder.
   1.161 +
   1.162 +- Building the Framework
   1.163 +
   1.164 +The SDL Library is packaged as a framework bundle, an organized
   1.165 +relocatable folder hierarchy of executable code, interface headers,
   1.166 +and additional resources. For practical purposes, you can think of a 
   1.167 +framework as a more user and system-friendly shared library, whose library
   1.168 +file behaves more or less like a standard UNIX shared library.
   1.169 +
   1.170 +To build the framework, simply open the framework project and build it. 
   1.171 +By default, the framework bundle "SDL.framework" is installed in 
   1.172 +/Library/Frameworks. Therefore, the testers and project stationary expect
   1.173 +it to be located there. However, it will function the same in any of the
   1.174 +following locations:
   1.175 +
   1.176 +    ~/Library/Frameworks
   1.177 +    /Local/Library/Frameworks
   1.178 +    /System/Library/Frameworks
   1.179 +
   1.180 +- Build Options
   1.181 +    There are two "Build Styles" (See the "Targets" tab) for SDL.
   1.182 +    "Deployment" should be used if you aren't tweaking the SDL library.
   1.183 +    "Development" should be used to debug SDL apps or the library itself.
   1.184 +
   1.185 +- Building the Testers
   1.186 +    Open the SDLTest project and build away!
   1.187 +
   1.188 +- Using the Project Stationary
   1.189 +    Copy the stationary to the indicated folders to access it from
   1.190 +    the "New Project" and "Add target" menus. What could be easier?
   1.191 +
   1.192 +- Setting up a new project by hand
   1.193 +    Some of you won't want to use the Stationary so I'll give some tips:
   1.194 +    * Create a new "Cocoa Application"
   1.195 +    * Add src/main/macosx/SDLMain.m , .h and .nib to your project
   1.196 +    * Remove "main.c" from your project
   1.197 +    * Remove "MainMenu.nib" from your project
   1.198 +    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
   1.199 +    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
   1.200 +    * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
   1.201 +    * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
   1.202 +    * Add your files
   1.203 +    * Clean and build
   1.204 +
   1.205 +- Building from command line
   1.206 +    Use pbxbuild in the same directory as your .pbproj file
   1.207 +
   1.208 +- Running your app
   1.209 +    You can send command line args to your app by either invoking it from
   1.210 +    the command line (in *.app/Contents/MacOS) or by entering them in the
   1.211 +    "Executables" panel of the target settings.
   1.212 +    
   1.213 +- Implementation Notes
   1.214 +    Some things that may be of interest about how it all works...
   1.215 +    * Working directory
   1.216 +        As defined in the SDL_main.m file, the working directory of your SDL app
   1.217 +        is by default set to its parent. You may wish to change this to better
   1.218 +        suit your needs.
   1.219 +    * You have a Cocoa App!
   1.220 +        Your SDL app is essentially a Cocoa application. When your app
   1.221 +        starts up and the libraries finish loading, a Cocoa procedure is called,
   1.222 +        which sets up the working directory and calls your main() method.
   1.223 +        You are free to modify your Cocoa app with generally no consequence 
   1.224 +        to SDL. You cannot, however, easily change the SDL window itself.
   1.225 +        Functionality may be added in the future to help this.
   1.226 +
   1.227 +
   1.228 +Known bugs are listed in the file "BUGS"