Mercurial > sdl-ios-xcode

comparison Xcode/SDL/pkg-support/Readme SDL Developer.txt @ 3331:d44a0a913aa2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Eric Wing to Sam Lots of fixes. Fixed missing power management building. Added template icons to the project templates. DocSet stuff Documentation fixes.. Fixed all the SDLtests. (Lots of tedious work.) It now depends on the static library target for convenience so I am not going to remove it from the SDL xcode project.
author Sam Lantinga <slouken@libsdl.org>
date Thu, 01 Oct 2009 15:30:26 +0000
parents
children e4009cea0e82
comparison
equal deleted inserted replaced
3330:e15bcb04c9b4 3331:d44a0a913aa2
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