annotate README.MacOSX @ 172:37e3ca9254c7

Date: Sat, 8 Sep 2001 04:42:23 +0200 From: Max Horn <max@quendi.de> Subject: SDL/OSX: Joystick; Better key handling I just finished implementing improved keyhandling for OS X (in fact the code should be easily ported to the "normal" MacOS part of SDL, I just had no chance yet). Works like this: First init the mapping table statically like before. Them, it queries the OS for the "official" key table, then iterates over all 127 scancode and gets the associates ascii code. It ignores everythng below 32 (has to, as it would lead to many problems if we did not... e.g. both ESC and NUM LOCk produce an ascii code 27 on my keyboard), and all stuff above 127 is mapped to SDLK_WORLD_* simply in the order it is encountered. In addition, caps lock is now working, too. The code work flawless for me, but since I only have one keyboard, I may have not encountered some serious problem... but I am pretty confident that it is better than the old code in most cases. The joystick driver works fine for me, too. I think it can be added to CVS already. It would simply be helpful if more people would test it. Hm, I wonder if Maelstrom or GLTron has Joystick support? That would be a wonderful test application :) I also took the liberty of modifying some text files like BUGS, README.CVS, README.MacOSX (which now contains the OS X docs I long promised)
author Sam Lantinga <slouken@libsdl.org>
date Tue, 11 Sep 2001 19:00:18 +0000
parents 25dfe480c75e
children c151cfc43c07
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
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
21 /*
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22 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
23 framework", which is the port of the old Mac Toolbox to OS X.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
24 To do this, use the -F and -framework arguments for compiling
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
25 and linking, respectively:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
26
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
27 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
28 cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
29
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
30 sdl-config knows about the linking path and -framework, so it's
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31 recommended to use it to fill in your Makefile variables.
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
32 */
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
33
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
34 To use the library once it's built, you essential have two possibilities:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
35 use the traditional autoconf/automake/make method, or use Apple's Project Builder.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
36
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
37 ==============================================================================
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
38 Using the Simple DirectMedia Layer with a traditional Makefile
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
39 ==============================================================================
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
40
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
41 In the following, it will be mostly assumed that you are using autoconf and
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
42 automake to setup your SDL project, and furthermore that you use the AM_PATH_SDL
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
43 macro provided by SDL in sdl.m4. If you are not using these tools, you can
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
44 still use SDL but it will be somewhat hard to get running.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
45
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
46 Only step 1) is really required to get started, but for full OS X support you
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
47 will want to do the other steps, too.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
48
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
49 1) Update your acinclude.m4 file in case you have copied an older version of
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
50 sdl.m4 into it. This is essential as AM_PATH_SDL now performs some additional
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
51 tasks when used on MacOS X
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
52
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
53 Rationale: AM_PATH_SDL copies /usr/local/share/sdl/Info.plist and the folder
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
54 /usr/local/share/sdl/SDLMain.nib/ into the directory where configure is invoked.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
55 This is essential for the configure script to be able to run the test code
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
56 that detects SDL.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
57
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
58 2) Copy SDL's Info.plist.in file (from src/main/macosx) into your project's main
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
59 folder (the same spot that your configure.in sits), and edit it to suite your
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
60 needs. Then add it to your AC_OUTPUT list in configure.in
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
61
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
62 Rationale: The Info.plist file can be used to specify an icon file for
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
63 your app, and also to provide a human readable version/copyright string
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
64 and other meta-information to the user via the Finder's Get Info dialog.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
65
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
66 3) Add something like the following rule to your Makefile.am:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
67
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
68 APP_NAME.app: EXE_NAME
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
69 mkdir -p $@/Contents/MacOS
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
70 mkdir -p $@/Contents/Resources
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
71 mkdir -p $@/Contents/Resources/SDLMain.nib
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
72 echo "APPL????" > $@/Contents/PkgInfo
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
73 $(INSTALL_DATA) Info.plist $@/Contents/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
74 $(INSTALL_DATA) SDLMain.nib/*.nib $@/Contents/Resources/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
75 $(INSTALL_PROGRAM) $< $@/Contents/MacOS/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
76
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
77 You should replace EXE_NAME with the name of the executable. APP_NAME is what
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
78 will be visible to the user in the Finder. Usually it will be the same
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
79 as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
80 usually is "TestGame"
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
81
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
82 If your project builds more than one application, you will have to do a bit more.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
83 For each of your target applications, you need a seperate rule. Furthermore, each
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
84 needs its own Info.plist file, since that has to contain the exact name of the
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
85 executable (i.e. EXE_NAME above). One way to do that is to use sed in your make rules
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
86 and modify a single master Info.plist.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
87
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
88 Rationale: on Mac OS X, executables have to be put into so-called "bundles".
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
89 The make rule given above will construct such a bundle around the executable
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
90 for you. You need to make a copy of it for each target application.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
91
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
92 4) If you want the create bundles to be installed, you may want to add this
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
93 rule to your Makefile.am:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
94
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
95 install-exec-local: Exult.app
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
96 mkdir -p /Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
97 cp -r $< /Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
98
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
99 This rule takes the Bundle created by the rule from step 3 and installs them
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
100 into /Applications/. An alternate installation place would be $HOME/Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
101
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
102 Again, if you want to install multiple applications, you will have to augment
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
103 the make rule accordingly.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
104
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
105
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
106 ==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
107 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
108 ==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
109
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
110 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
111
53
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
112 - First steps
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
113
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
114 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
115 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
116 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
117 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
118 cd [path_to_SDL_source]
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
119 tar zxf PBProjects.tar.gz
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
120 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
121 normally from the Finder.
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
122
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
123 - Building the Framework
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
124
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
125 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
126 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
127 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
128 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
129 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
130
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
131 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
132 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
133 ~/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
134 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
135 following locations:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
136
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
137 ~/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
138 /Local/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
139 /System/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
140
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
141 - Build Options
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
142 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
143 "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
144 "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
145
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
146 - Building the Testers
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
147 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
148
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
149 - Using the Project Stationary
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
150 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
151 the "New Project" and "Add target" menus. What could be easier?
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
152
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
153 - 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
154 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
155 * Create a new "Cocoa Application"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
156 * 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
157 * Remove "main.c" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
158 * Remove "MainMenu.nib" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
159 * 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
160 * 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
161 * 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
162 * 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
163 * Add your files
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
164 * Clean and build
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
165
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
166 - Building from command line
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
167 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
168
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
169 - Running your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
170 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
171 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
172 "Executibles" panel of the target settings.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
173
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
174 - Implementation Notes
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
175 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
176 * Working directory
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
177 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
178 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
179 suit your needs.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
180 * You have a Cocoa App!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
181 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
182 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
183 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
184 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
185 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
186 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
187 * My development setup:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
188 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
189 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
190 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
191 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
192
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
193 Known bugs are listed in the file "BUGS"
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
194 LocalWords: Stuffit