annotate Xcode/SDL/pkg-support/Readme SDL Developer.txt @ 5066:3afb71c202b2

Fixed bug #945 The configure script was breaking the substitutions into multiple fragments, breaking them across the substitution for the build rules. This of course totally hosed the process. I switched to using a more modern usage of AC_OUTPUT and added a post-process step that appends the build rules to the Makefile.
author Sam Lantinga <slouken@libsdl.org>
date Fri, 21 Jan 2011 12:43:25 -0800
parents e4009cea0e82
children
rev   line source
3331
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
1 SDL Mac OS X Developer Notes:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
2 This is an optional developer package to provide extras that an
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
3 SDL developer might benefit from.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
4
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
5 Make sure you have already installed the SDL.framework
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
6 from the SDL.dmg.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
7
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
8 For more complete documentation, please see READMEs included
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
9 with the SDL source code. Also, don't forget about the API
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
10 documentation (also included with this package).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
11
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
12
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
13 This package contains:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
14 - SDL API Documentation
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
15 - A variety of SDLMain and .Nib files to choose from
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
16 - Xcode project templates
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
17
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
18
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
19 SDL API Documentation:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
20 We include both the HTML documentation and the man files.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
21 We also include an Xocde DocSet which
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
22 is generated via Doxygen. These require Xcode 3.0 or greater.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
23
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
24 You will need to drill down into the XcodeDocSet directory
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
25 from the Documentation folder and find the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
26 org.libsdl.sdl.docset bundle. We recommend you copy this to:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
27
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
28 /Library/Developer/Shared/Documentation/DocSets
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
29
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
30 Again, this follows all the standard Xcode patterns
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
31 described with the project templates (below). You may need
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
32 to create the directories if they don't already exist.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
33 You may install it on a per-user basis.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
34 And you may target specific versions of Xcode
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
35 in lieu of using the "Shared" directory.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
36
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
37 To use, it is quite simple. Just bring up the Xcode
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
38 Documentation Browser window (can be activated through
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
39 the Xcode Help Menu) and start searching for something.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
40
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
41 If nothing is found on a legitimate search, verify that
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
42 the SDL documentation is enabled by opening up the DocSet
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
43 popup box below the toolbar in Snow Leopard.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
44 (In Leopard, the DocSets appear in the left-side panel.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
45
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
46 Another handy trick is to use the mouse and Option-Double-Click
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
47 on a function or keyword to bring up documentation on the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
48 selected item. Prior to Xcode 3.2 (Snow Leopard), this would
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
49 jump you to the entry in the Xcode Documentation Browser.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
50
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
51 However, in Xcode 3.2 (Snow Leopard), this behavior has been
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
52 altered and you are now given a hovering connected popup box
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
53 on the selected item (called Quick Help). Unfortunately, the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
54 Doxygen generated DocSet doesn't currently provide Quick Help
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
55 information. You can either follow a link to the main
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
56 Documentation Browser from the Quick Help, or alternatively,
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
57 you can bypass Quick Help by using Command-Option-Double-Click
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
58 instead of Option-Double-Click. (Please file feedback with both
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
59 Doxygen and Apple to improve Quick Help integration.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
60
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
61
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
62 For those that want to tweak the documentation output,
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
63 you can find my Doxyfile in the XcodeDocSet directory in
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
64 the Xcode directory of the SDL source code base (and in this package).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
65
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
66 One of the most significant options is "Separate Member Pages"
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
67 which I disable. When disabled, the documentation is about 6MB.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
68 When enabled, the documentation is closer to 1.6GB (yes gigabytes).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
69 Obviously, distribution will be really hard with sizes that huge
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
70 so I disable the option.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
71
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
72 I also disabled Dot because there didn't seem to be
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
73 much benefit of generating graphs for public C functions.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
74
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
75 One thing I would like to see is a CSS file that makes the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
76 Doxygen DocSet look more like the native Apple documentation
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
77 style. Style sheets are outside my expertise so I am asking for
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
78 contributions on this one. Meanwhile, I also request you send
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
79 feedback to Doxygen and Apple about this issue too.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
80
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
81
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
82 Finally for convenience, I have added a new shell script target
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
83 to the Xcode project that builds SDL that refers to my Doxyfile
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
84 and generate the DocSet we distribute.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
85
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
86
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
87 SDLMain:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
88 We include several different variations of SDLMain and the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
89 .Nibs. (Each of these are demonstrated by the different PB/Xcode
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
90 project templates.) You get to pick which one you want to use,
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
91 or you can write your own to meet your own specific needs. We do
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
92 not currently provide a libSDLMain.a. You can build it yourself
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
93 once you decide which one you want to use though it is easier and
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
94 recommended in the SDL FAQ that you just copy the SDLMain.h and
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
95 SDLMain.m directly into your project. If you are puzzled by this,
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
96 we strongly recommend you look at the different PB/Xcode project
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
97 templates to understand their uses and differences. (See Project
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
98 Template info below.) Note that the "Nibless" version is the same
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
99 version of SDLMain we include the the devel-lite section of the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
100 main SDL.dmg.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
101
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
102
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
103 Xocde Project Templates:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
104 For convenience, we provide Project Templates for Xcode.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
105 Using Xcode is *not* a requirement for using
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
106 the SDL.framework. However, for newbies, we do recommend trying
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
107 out the Xcode templates first (and work your way back to raw gcc
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
108 if you desire), as the Xcode templates try to setup everything
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
109 for you in a working state. This avoids the need to ask those
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
110 many reoccuring questions that appear on the mailing list
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
111 or the SDL FAQ.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
112
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
113
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
114 We have provided 3 different kinds of SDL templates for Xcode and have
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
115 a different set of templates for each version of Xcode (which generally
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
116 correspond with a particular Mac OS X version).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
117 The installion directory depends on which version of Xcode you have.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
118 (Note: These directories may not already exist on your system so you must create them yourself.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
119
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
120 For Leopard and Snow Leopard (Xcode 2.5, 3+), we recommend you install to:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
121 /Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
122
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
123 For Xcode 1.0 to 2.4,
3682
e4009cea0e82 Added Xcode-iPhoneOS to make dist
Sam Lantinga <slouken@libsdl.org>
parents: 3331
diff changeset
124 /Library/Application Support/Apple/Developer Tools/Project Templates/Application
3331
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
125
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
126
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
127 Also note you may place it in per-user locations, e.g.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
128 ~/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
129
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
130
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
131 And for advanced users who have multiple versions of Xcode installed on a single system,
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
132 you may put each set in a directory with the Xcode version number instead of using "Shared", e.g.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
133 /Library/Application Support/Developer/2.5/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
134 /Library/Application Support/Developer/3.1/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
135 /Library/Application Support/Developer/3.2/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
136
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
137
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
138 Copy each of the SDL/Xcode template directories into the correct location (e.g. "SDL OpenGL Application").
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
139 Do not copy our enclosing folder into the location (e.g. TemplatesForXcodeSnowLeopard).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
140 So for example, in:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
141 /Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
142 you should have the 3 folders:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
143 SDL Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
144 SDL Cocoa Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
145 SDL OpenGL Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
146
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
147
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
148 After doing this, when doing a File->New Project, you will see the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
149 projects under the Application category.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
150 (Newer versions of Xcode have a separate section for User Templates and it will
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
151 appear in the Application category of the User Templates section.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
152
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
153
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
154
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
155 How to create a new SDL project:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
156
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
157 1. Open Xcode
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
158 2. Select File->New Project
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
159 3. Select SDL Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
160 4. Name, Save, and Finish
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
161 5. Add your sources.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
162 *6. That's it!
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
163
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
164 * If you installed the SDL.framework to $(HOME)/Library/Frameworks
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
165 instead of /Library/Frameworks, you will need to update the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
166 location of the SDL.framework in the "Groups & Files" browser.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
167
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
168
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
169 The project templates we provide are:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
170 - SDL Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
171 This is the barebones, most basic version. There is no
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
172 customized .Nib file. While still utilizing Cocoa under
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
173 the hood, this version may be best suited for fullscreen
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
174 applications.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
175
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
176 - SDL Cocoa Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
177 This demonstrates the integration of using native
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
178 Cocoa Menus with an SDL Application. For applications
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
179 designed to run in Windowed mode, Mac users may appreciate
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
180 having access to standard menus for things
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
181 like Preferences and Quiting (among other things).
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
182
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
183 - SDL OpenGL Application
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
184 This reuses the same SDLMain from the "SDL Application"
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
185 temmplate, but also demonstrates how to
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
186 bring OpenGL into the mix.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
187
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
188
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
189 Special Notes:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
190 Only the 10.6 Snow Leopard templates (and later) will include 64-bit in the Universal Binary as
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
191 prior versions of OS X lacked the API support SDL requires for 64-bit to work correctly.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
192 To prevent 64-bit SDL executables from being launched on 10.5 Leopard, a special key has been set
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
193 in the Info.plist in our Snow Leopard SDL/Xcode templates.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
194
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
195
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
196 Xcode Tips and Tricks:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
197
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
198 - Building from command line
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
199 Use the command line tool: xcodebuild (see man page)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
200
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
201 - Running your app
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
202 You can send command line args to your app by either
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
203 invoking it from the command line (in *.app/Contents/MacOS)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
204 or by entering them in the "Executables" panel of the target
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
205 settings.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
206
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
207 - Working directory
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
208 As defined in the SDLMain.m file, the working directory of
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
209 your SDL app is by default set to its parent. You may wish to
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
210 change this to better suit your needs.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
211
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
212
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
213
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
214 Additional References:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
215
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
216 - Screencast tutorials for getting started with OpenSceneGraph/Mac OS X are
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
217 available at:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
218 http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
219 Though these are OpenSceneGraph centric, the same exact concepts apply to
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
220 SDL, thus the videos are recommended for everybody getting started with
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
221 developing on Mac OS X. (You can skim over the PlugIns stuff since SDL
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
222 doesn't have any PlugIns to worry about.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
223
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
224
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
225 Partial History:
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
226 2009-09-21 - CustomView template project was removed because it was broken by
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
227 the removal of legacy Quicktime support while moving to 64-bit.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
228 ProjectBuilder templates were removed.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
229 Tiger, Leopard, and Snow Leopard Xcode templates were introduced instead of
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
230 using a single common template due to the differences between the 3.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
231 (Tiger used a chevron marker for substitution while Leopard/Snow Leopard use ___
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
232 and we need the 10.6 SDK for 64-bit.)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
233
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
234 2007-12-30 - Updated documentation to reflect new template paths in Leopard
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
235 Xcode. Added reference to OSG screencasts.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
236
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
237 2006-03-17 - Changed the package format from a .pkg based
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
238 installer to a .dmg to avoid requiring administrator/root
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
239 to access contents, for better transparency, and to allow
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
240 users to more easily control which components
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
241 they actually want to install.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
242 Introduced and updated documentation.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
243 Created brand new Xcode project templates for Xcode 2.1
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
244 based on the old Project Builder templates as they
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
245 required Xcode users to "Upgrade to Native Target". The new
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
246 templates try to leveage more default options and leverage
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
247 more Xcode conventions. The major change that may introduce
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
248 some breakage is that I now link to the SDL framework
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
249 via the "Group & Files" browser instead of using build
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
250 options. The downside to this is that if the user
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
251 installs the SDL.framework to a place other than
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
252 /Library/Frameworks (e.g. $(HOME)/Library/Frameworks),
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
253 the framework will not be found to link to and the user
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
254 has to manually fix this. But the upshot is (in addition to
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
255 being visually displayed in the forefront) is that it is
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
256 really easy to copy (embed) the framework automatically
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
257 into the .app bundle on build. So I have added this
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
258 feature, which makes the application potentially
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
259 drag-and-droppable ready. The Project Builder templates
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
260 are mostly unchanged due to the fact that I don't have
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
261 Project Builder. I did rename a file extension to .pbxproj
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
262 for the SDL Custom Cocoa Application template because
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
263 the .pbx extension would not load in my version of Xcode.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
264 For both Project Builder and Xcode templates, I resync'd
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
265 the SDLMain.* files for the SDL App and OpenGL App
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
266 templates. I think people forget that we have 2 other
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
267 SDLMain's (and .Nib's) and somebody needs to go
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
268 through them and merge the new changes into those.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
269 I also wrote a fix for the SDL Custom Cocoa App
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
270 template in MyController.m. The sprite loading code
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
271 needed to be able to find the icon.bmp in the .app
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
272 bundle's Resources folder. This change was needed to get
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
273 the app to run out of the box. This might change is untested
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
274 with Project Builder though and might break it.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
275 There also seemed to be some corruption in the .nib itself.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
276 Merely opening it and saving (allowing IB to correct the
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
277 .nib) seemed to correct things.
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
278 (Eric Wing)
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
279
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
280
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
281
d44a0a913aa2 Eric Wing to Sam
Sam Lantinga <slouken@libsdl.org>
parents:
diff changeset
282