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