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