annotate README.MacOSX @ 53:25dfe480c75e

Added MacOS X Project Builder projects
author Sam Lantinga <slouken@lokigames.com>
date Sun, 10 Jun 2001 18:20:23 +0000
parents 45b1c4303f87
children 37e3ca9254c7
rev   line source
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
1 ==============================================================================
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
2 Using the Simple DirectMedia Layer with Mac OS X
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
3 ==============================================================================
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
4
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
5 These instructions are for people using Apple's Mac OS X (pronounced
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
6 "ten").
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
7
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
8 From the developer's point of view, OS X is a sort of hybrid Mac and
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
9 Unix system, and you have the option of using either traditional
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
10 command line tools or Apple's IDE ProjectBuilder (PB).
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
11
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
12 To build using the command line, use the standard configure and make
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
13 process:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
14
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
15 ./configure
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
16 make
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
17 make install
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
18
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
19 (You may need to create the subdirs of /usr/local manually.)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
21 For some reason, libtool doesn't run ranlib properly, so do this
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22 manually:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
23
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
24 ranlib /usr/local/lib/libSDL.a
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
25
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
26 To use the library once it's built, you need to use the "Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
27 framework", which is the port of the old Mac Toolbox to OS X.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
28 To do this, use the -F and -framework arguments for compiling
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
29 and linking, respectively:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
30
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31 cc -c myprog.c -I/usr/local/include/SDL -F/System/Library/Frameworks/Carbon.framework
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
32 cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
33
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
34 sdl-config knows about the linking path and -framework, so it's
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
35 recommended to use it to fill in your Makefile variables.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
36
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
37 ==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
38 Using the Simple DirectMedia Layer with Project Builder
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
39 ==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
40
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
41 These instructions are for using Apple's Project Builder IDE to build SDL applications.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
42
53
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
43 - First steps
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
44
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
45 The first thing to do is to unpack the PBProjects.tar.gz archive in the
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
46 top level SDL directory (where the PBProjects.tar.gz archive resides).
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
47 Because Stuffit Expander will unpack the archive into a subdirectory,
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
48 you should unpack the archive manually from the command line:
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
49 cd [path_to_SDL_source]
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
50 tar zxf PBProjects.tar.gz
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
51 This will create a new folder called PBProjects, which you can browse
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
52 normally from the Finder.
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
53
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
54 - Building the Framework
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
55
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
56 The SDL Library is packaged as a framework bundle, an organized
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
57 relocatable folder heirarchy of executible code, interface headers,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
58 and additional resources. For practical purposes, you can think of a
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
59 framework as a more user and system-friendly shared library, whose library
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
60 file behaves more or less like a standard UNIX shared library.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
61
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
62 To build the framework, simply open the framework project and build it.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
63 By default, the framework bundle "SDL.framework" is installed in
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
64 ~/Library/Frameworks. Therefore, the testers and project stationary expect
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
65 it to be located there. However, it will function the same in any of the
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
66 following locations:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
67
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
68 ~/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
69 /Local/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
70 /System/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
71
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
72 - Build Options
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
73 There are two "Build Styles" (See the "Targets" tab) for SDL.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
74 "Deployment" should be used if you aren't tweaking the SDL library.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
75 "Development" should be used to debug SDL apps or the library itself.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
76
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
77 - Building the Testers
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
78 Open the SDLTest project and build away!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
79
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
80 - Using the Project Stationary
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
81 Copy the stationary to the indicated folders to access it from
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
82 the "New Project" and "Add target" menus. What could be easier?
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
83
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
84 - Setting up a new project by hand
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
85 Some of you won't want to use the Stationary so I'll give some tips:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
86 * Create a new "Cocoa Application"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
87 * Add src/main/macosx/SDLMain.m , .h and .nib to your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
88 * Remove "main.c" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
89 * Remove "MainMenu.nib" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
90 * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
91 * Add "$(HOME)/Library/Frameworks" to the frameworks search path
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
92 * Add "-framework SDL" to the "OTHER_LDFLAGS" variable
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
93 * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
94 * Add your files
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
95 * Clean and build
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
96
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
97 - Building from command line
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
98 Use pbxbuild in the same directory as your .pbproj file
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
99
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
100 - Running your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
101 You can send command line args to your app by either invoking it from
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
102 the command line (in *.app/Contents/MacOS) or by entering them in the
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
103 "Executibles" panel of the target settings.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
104
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
105 - Implementation Notes
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
106 Some things that may be of interest about how it all works...
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
107 * Working directory
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
108 As defined in the SDLMain.m file, the working directory of your SDL app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
109 is by default set to its parent. You may wish to change this to better
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
110 suit your needs.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
111 * You have a Cocoa App!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
112 Your SDL app is essentially a Cocoa application. When your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
113 starts up and the libraries finish loading, a Cocoa procedure is called,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
114 which sets up the working directory and calls your main() method.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
115 You are free to modify your Cocoa app with generally no consequence
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
116 to SDL. You cannot, however, easily change the SDL window itself.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
117 Functionality may be added in the future to help this.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
118 * My development setup:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
119 I am using version 1.0.1 (v63.0) of Project Builder on MacOS X 10.0.3,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
120 from the Developer Tools CD for May 2001.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
121 As of May 31 2001, Apple hasn't released this version of the tools to the public,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
122 but I expect that things will still work on older versions.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
123
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
124 Known bugs are listed in the file "BUGS"