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