Mercurial > sdl-ios-xcode
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 | 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, | |
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 | 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 |