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