Mercurial > sdl-ios-xcode
annotate Xcode/SDL/pkg-support/Readme SDL Developer.txt @ 4468:82f357a91d43
SDL_KillThread() is no longer supported - it was always dangerous! :)
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Mon, 24 May 2010 22:56:36 -0700 |
| 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 |