README.MacOSX
author Sam Lantinga <slouken@libsdl.org>
Sun, 23 Sep 2001 21:09:08 +0000
changeset 194 ba9e0fcc2ae2
parent 191 c151cfc43c07
child 199 2ad0957f6265
permissions -rw-r--r--
Oops, back out that SDL_main -> SDLMain conversion
slouken@0
     1
==============================================================================
slouken@0
     2
Using the Simple DirectMedia Layer with Mac OS X
slouken@0
     3
==============================================================================
slouken@0
     4
slouken@0
     5
These instructions are for people using Apple's Mac OS X (pronounced
slouken@0
     6
"ten").
slouken@0
     7
slouken@0
     8
From the developer's point of view, OS X is a sort of hybrid Mac and
slouken@0
     9
Unix system, and you have the option of using either traditional
slouken@0
    10
command line tools or Apple's IDE ProjectBuilder (PB).
slouken@0
    11
slouken@0
    12
To build using the command line, use the standard configure and make
slouken@0
    13
process:
slouken@0
    14
slouken@0
    15
	./configure
slouken@0
    16
	make
slouken@0
    17
	make install
slouken@0
    18
slouken@0
    19
(You may need to create the subdirs of /usr/local manually.)
slouken@0
    20
slouken@172
    21
/*
slouken@0
    22
To use the library once it's built, you need to use the "Carbon
slouken@0
    23
framework", which is the port of the old Mac Toolbox to OS X.
slouken@0
    24
To do this, use the -F and -framework arguments for compiling
slouken@0
    25
and linking, respectively:
slouken@0
    26
slouken@0
    27
	cc -c myprog.c -I/usr/local/include/SDL -F/System/Library/Frameworks/Carbon.framework
slouken@0
    28
	cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
slouken@0
    29
slouken@0
    30
sdl-config knows about the linking path and -framework, so it's
slouken@0
    31
recommended to use it to fill in your Makefile variables.
slouken@172
    32
*/
slouken@172
    33
slouken@172
    34
To use the library once it's built, you essential have two possibilities:
slouken@172
    35
use the traditional autoconf/automake/make method, or use Apple's Project Builder.
slouken@172
    36
slouken@172
    37
==============================================================================
slouken@172
    38
Using the Simple DirectMedia Layer with a traditional Makefile
slouken@172
    39
==============================================================================
slouken@172
    40
slouken@172
    41
In the following, it will be mostly assumed that you are using autoconf and
slouken@172
    42
automake to setup your SDL project, and furthermore that you use the AM_PATH_SDL
slouken@172
    43
macro provided by SDL in sdl.m4. If you are not using these tools, you can
slouken@172
    44
still use SDL but it will be somewhat hard to get running.
slouken@172
    45
slouken@172
    46
Only step 1) is really required to get started, but for full OS X support you
slouken@172
    47
will want to do the other steps, too.
slouken@172
    48
slouken@172
    49
1) Update your acinclude.m4 file in case you have copied an older version of
slouken@172
    50
   sdl.m4 into it. This is essential as AM_PATH_SDL now performs some additional
slouken@172
    51
   tasks when used on MacOS X
slouken@172
    52
slouken@172
    53
   Rationale: AM_PATH_SDL copies /usr/local/share/sdl/Info.plist and the folder
slouken@191
    54
   /usr/local/share/sdl/SDL_main.nib/ into the directory where configure is invoked.
slouken@172
    55
   This is essential for the configure script to be able to run the test code
slouken@172
    56
   that detects SDL.
slouken@172
    57
slouken@172
    58
2) Copy SDL's Info.plist.in file (from src/main/macosx) into your project's main
slouken@172
    59
   folder (the same spot that your configure.in sits), and edit it to suite your
slouken@172
    60
   needs. Then add it to your AC_OUTPUT list in configure.in
slouken@172
    61
slouken@172
    62
   Rationale: The Info.plist file can be used to specify an icon file for
slouken@172
    63
   your app, and also to provide a human readable version/copyright string
slouken@172
    64
   and other meta-information to the user via the Finder's Get Info dialog.
slouken@172
    65
slouken@172
    66
3) Add something like the following rule to your Makefile.am:
slouken@172
    67
slouken@172
    68
APP_NAME.app: EXE_NAME
slouken@172
    69
	mkdir -p $@/Contents/MacOS
slouken@172
    70
	mkdir -p $@/Contents/Resources
slouken@191
    71
	mkdir -p $@/Contents/Resources/SDL_main.nib
slouken@172
    72
	echo "APPL????" > $@/Contents/PkgInfo
slouken@172
    73
	$(INSTALL_DATA) Info.plist $@/Contents/
slouken@191
    74
	$(INSTALL_DATA) SDL_main.nib/*.nib $@/Contents/Resources/
slouken@172
    75
	$(INSTALL_PROGRAM) $< $@/Contents/MacOS/
slouken@172
    76
slouken@172
    77
   You should replace EXE_NAME with the name of the executable. APP_NAME is what
slouken@172
    78
   will be visible to the user in the Finder. Usually it will be the same
slouken@172
    79
   as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
slouken@172
    80
   usually is "TestGame"
slouken@172
    81
slouken@172
    82
   If your project builds more than one application, you will have to do a bit more.
slouken@172
    83
   For each of your target applications, you need a seperate rule. Furthermore, each
slouken@172
    84
   needs its own Info.plist file, since that has to contain the exact name of the 
slouken@172
    85
   executable (i.e. EXE_NAME above). One way to do that is to use sed in your make rules
slouken@172
    86
   and modify a single master Info.plist.
slouken@172
    87
slouken@172
    88
   Rationale: on Mac OS X, executables have to be put into so-called "bundles".
slouken@172
    89
   The make rule given above will construct such a bundle around the executable
slouken@172
    90
   for you. You need to make a copy of it for each target application.
slouken@172
    91
slouken@172
    92
4) If you want the create bundles to be installed, you may want to add this
slouken@172
    93
   rule to your Makefile.am:
slouken@172
    94
slouken@172
    95
install-exec-local: Exult.app
slouken@172
    96
	mkdir -p /Applications/
slouken@172
    97
	cp -r $< /Applications/
slouken@172
    98
slouken@172
    99
   This rule takes the Bundle created by the rule from step 3 and installs them
slouken@172
   100
   into /Applications/. An alternate installation place would be $HOME/Applications/
slouken@172
   101
slouken@172
   102
   Again, if you want to install multiple applications, you will have to augment
slouken@172
   103
   the make rule accordingly.
slouken@172
   104
slouken@0
   105
slouken@47
   106
==============================================================================
slouken@47
   107
Using the Simple DirectMedia Layer with Project Builder
slouken@47
   108
==============================================================================
slouken@0
   109
slouken@47
   110
These instructions are for using Apple's Project Builder IDE to build SDL applications.
slouken@0
   111
slouken@53
   112
- First steps
slouken@53
   113
slouken@53
   114
The first thing to do is to unpack the PBProjects.tar.gz archive in the
slouken@53
   115
top level SDL directory (where the PBProjects.tar.gz archive resides).
slouken@53
   116
Because Stuffit Expander will unpack the archive into a subdirectory,
slouken@53
   117
you should unpack the archive manually from the command line:
slouken@53
   118
	cd [path_to_SDL_source]
slouken@53
   119
	tar zxf PBProjects.tar.gz
slouken@53
   120
This will create a new folder called PBProjects, which you can browse
slouken@53
   121
normally from the Finder.
slouken@53
   122
slouken@47
   123
- Building the Framework
slouken@47
   124
slouken@47
   125
The SDL Library is packaged as a framework bundle, an organized
slouken@47
   126
relocatable folder heirarchy of executible code, interface headers, 
slouken@47
   127
and additional resources. For practical purposes, you can think of a 
slouken@47
   128
framework as a more user and system-friendly shared library, whose library
slouken@47
   129
file behaves more or less like a standard UNIX shared library.
slouken@47
   130
slouken@47
   131
To build the framework, simply open the framework project and build it. 
slouken@47
   132
By default, the framework bundle "SDL.framework" is installed in 
slouken@47
   133
~/Library/Frameworks. Therefore, the testers and project stationary expect
slouken@47
   134
it to be located there. However, it will function the same in any of the
slouken@47
   135
following locations:
slouken@47
   136
slouken@47
   137
    ~/Library/Frameworks
slouken@47
   138
    /Local/Library/Frameworks
slouken@47
   139
    /System/Library/Frameworks
slouken@47
   140
slouken@47
   141
- Build Options
slouken@47
   142
    There are two "Build Styles" (See the "Targets" tab) for SDL.
slouken@47
   143
    "Deployment" should be used if you aren't tweaking the SDL library.
slouken@47
   144
    "Development" should be used to debug SDL apps or the library itself.
slouken@47
   145
slouken@47
   146
- Building the Testers
slouken@47
   147
    Open the SDLTest project and build away!
slouken@47
   148
slouken@47
   149
- Using the Project Stationary
slouken@47
   150
    Copy the stationary to the indicated folders to access it from
slouken@47
   151
    the "New Project" and "Add target" menus. What could be easier?
slouken@47
   152
slouken@47
   153
- Setting up a new project by hand
slouken@47
   154
    Some of you won't want to use the Stationary so I'll give some tips:
slouken@47
   155
    * Create a new "Cocoa Application"
slouken@191
   156
    * Add src/main/macosx/SDL_main.m , .h and .nib to your project
slouken@47
   157
    * Remove "main.c" from your project
slouken@47
   158
    * Remove "MainMenu.nib" from your project
slouken@47
   159
    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
slouken@47
   160
    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
slouken@47
   161
    * Add "-framework SDL" to the "OTHER_LDFLAGS" variable
slouken@191
   162
    * Set the "Main Nib File" under "Application Settings" to "SDL_main.nib"
slouken@47
   163
    * Add your files
slouken@47
   164
    * Clean and build
slouken@47
   165
slouken@47
   166
- Building from command line
slouken@47
   167
    Use pbxbuild in the same directory as your .pbproj file
slouken@47
   168
         
slouken@47
   169
- Running your app
slouken@47
   170
    You can send command line args to your app by either invoking it from
slouken@47
   171
    the command line (in *.app/Contents/MacOS) or by entering them in the
slouken@47
   172
    "Executibles" panel of the target settings.
slouken@47
   173
    
slouken@47
   174
- Implementation Notes
slouken@47
   175
    Some things that may be of interest about how it all works...
slouken@47
   176
    * Working directory
slouken@191
   177
        As defined in the SDL_main.m file, the working directory of your SDL app
slouken@47
   178
        is by default set to its parent. You may wish to change this to better
slouken@47
   179
        suit your needs.
slouken@47
   180
    * You have a Cocoa App!
slouken@47
   181
        Your SDL app is essentially a Cocoa application. When your app
slouken@47
   182
        starts up and the libraries finish loading, a Cocoa procedure is called,
slouken@47
   183
        which sets up the working directory and calls your main() method.
slouken@47
   184
        You are free to modify your Cocoa app with generally no consequence 
slouken@47
   185
        to SDL. You cannot, however, easily change the SDL window itself.
slouken@47
   186
        Functionality may be added in the future to help this.
slouken@47
   187
    * My development setup:
slouken@47
   188
        I am using version 1.0.1 (v63.0) of Project Builder on MacOS X 10.0.3,
slouken@47
   189
        from the Developer Tools CD for May 2001.
slouken@47
   190
        As of May 31 2001, Apple hasn't released this version of the tools to the public, 
slouken@47
   191
        but I expect that things will still work on older versions.
slouken@47
   192
        
slouken@0
   193
Known bugs are listed in the file "BUGS"
slouken@172
   194
 LocalWords:  Stuffit