Xcode/SDL/pkg-support/Readme SDL Developer.txt
author Bob Pendleton <bob@pendleton.com>
Thu, 02 Jul 2009 16:15:55 +0000
changeset 3210 3272812c7eab
parent 2207 d63e9f5944ae
permissions -rw-r--r--
Documentation fix.
     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.
     5 	Make sure you have already installed the SDL.framework 
     6 	from the SDL.dmg. 
     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).
    13 This package contains:
    14 - SDL API Documentation
    15 - A variety of SDLMain and .Nib files to choose from
    16 - Xcode/Project Builder project templates
    19 SDL API Documentation:
    20 	We include both the HTML documentation and the man files. For 
    21 	the HTML documentation, we have previously been installing to 
    22 	/Develoepr/Documentation, but Apple explicitly says this is not 
    23 	intended for 3rd party documentation. Xcode installs/updates 
    24 	reserve the right and have been known to completely purge the 
    25 	/Developer directory before installation, so if you place stuff 
    26 	there, be aware that it could be deleted.
    29 SDLMain:
    30 	We include several different variations of SDLMain and the 
    31 	.Nibs. (Each of these are demonstrated by the different PB/Xcode 
    32 	project templates.) You get to pick which one you want to use, 
    33 	or you can write your own to meet your own specific needs. We do 
    34 	not currently provide a libSDLMain.a. You can build it yourself
    35 	once you decide which one you want to use though it is easier and 
    36 	recommended in the SDL FAQ that you just copy the SDLMain.h and 
    37 	SDLMain.m directly into your project. If you are puzzled by this, 
    38 	we strongly recommend you look at the different PB/Xcode project 
    39 	templates to understand their uses and differences. (See Project 
    40 	Template info below.) Note that the "Nibless" version is the same 
    41 	version of SDLMain we include the the devel-lite section of the 
    42 	main SDL.dmg.
    45 Project Builder/Xocde Project Templates:
    46 	For convenience, we provide Project Templates for Xcode and 
    47 	Project Builder. Using Xcode is *not* a requirement for using 
    48 	the SDL.framework. However, for newbies, we do recommend trying 
    49 	out the Xcode templates first (and work your way back to raw gcc 
    50 	if you desire), as the Xcode templates try to setup everything
    51 	for you in a working state. This avoids the need to ask those 
    52 	many reoccuring questions that appear on the mailing list 
    53 	or the SDL FAQ.
    56 	Xcode 2.1+ users may use the templates in TemplatesForXcode folder.
    57 	Project Builder and Xcode <= 2.0 users will need to use the 
    58 	templates in TemplatesForProjectBuilder folder.
    60 	We have provided 4 different kinds of SDL templates for Xcode. 
    61 	We recommend you copy each of the template folders to:
    62 	/Library/Application Support/Apple/Developer Tools/Project Templates/Appllcation (for system-wide)
    63 	or
    64 	~/Library/Application Support/Apple/Developer Tools/Project Templates/Appllcation (for per-user)
    66 	(Project Builder users will need to copy to /Developer/ProjectBuilder Extras).
    69 	After doing this, when doing a File->New Project, you will see the 
    70 	projects under the Application category.
    73 	How to create a new SDL project:
    75 	1. Open Xcode (or Project Builder)
    76 	2. Select File->New Project
    77 	3. Select SDL Application
    78 	4. Name, Save, and Finish
    79 	5. Add your sources.
    80 	*6. That's it!
    82 	* If you installed the SDL.framework to $(HOME)/Library/Frameworks 
    83 	instead of /Library/Frameworks, you will need to update the 
    84 	location of the SDL.framework in the "Groups & Files" browser.
    86 	** For Xcode users using Project Builder templates, you may 
    87 	want to convert the project to native Xcode targets since 
    88 	our current templates are Project Builder based. 
    89 	Go to the Menu->Project->Upgrade All Targets to Native
    93 	The project templates we provide are:
    94 	- SDL Application
    95 		This is the barebones, most basic version. There is no 
    96 		customized .Nib file. While still utilizing Cocoa under 
    97 		the hood, this version may be best suited for fullscreen 
    98 		applications.
   100 	- SDL Cocoa Application
   101 		This demonstrates the integration of using native 
   102 		Cocoa Menus with an SDL Application. For applications
   103 		designed to run in Windowed mode, Mac users may appreciate 
   104 		having access to standard menus for things
   105 		like Preferences and Quiting (among other things).
   107 	- SDL Custom Cocoa Application
   108 		This application demonstrates the integration of SDL with 
   109 		native Cocoa widgets. This shows how
   110 		you can get native Cocoa widgets like buttons, sliders, 
   111 		etc. to interact/integrate with your SDL application.
   113 	- SDL OpenGL Application
   114 		This reuses the same SDLMain from the "SDL Application" 
   115 		temmplate, but also demonstrates how to 
   116 		bring OpenGL into the mix.
   121 Project Builder/Xcode Tips and Tricks:
   123 - Building from command line
   124 	Use pbxbuild in the same directory as your .pbproj file
   125 	(Xcode has xcodebuild)
   127 - Running your app
   128     You can send command line args to your app by either 
   129 	invoking it from the command line (in *.app/Contents/MacOS) 
   130 	or by entering them in the "Executables" panel of the target 
   131 	settings, or the "Executables" tab in the main window 
   132 	in Project Builder 2.0.
   134 - Working directory
   135     As defined in the SDLMain.m file, the working directory of 
   136     your SDL app is by default set to its parent. You may wish to 
   137     change this to better suit your needs.
   143 Partial History:
   144 2006-03-17 - Changed the package format from a .pkg based 
   145 	installer to a .dmg to avoid requiring administrator/root 
   146 	to access contents, for better transparency, and to allow 
   147 	users to more easily control which components 
   148 	they actually want to install. 
   149 	Introduced and updated documentation.
   150 	Created brand new Xcode project templates for Xcode 2.1 
   151 	based on the old Project Builder templates as they 
   152 	required Xcode users to "Upgrade to Native Target". The new 
   153 	templates try to leveage more default options and leverage 
   154 	more Xcode conventions. The major change that may introduce 
   155 	some breakage is that I now link to the SDL framework
   156 	via the "Group & Files" browser instead of using build 
   157 	options. The downside to this is that if the user 
   158 	installs the SDL.framework to a place other than 
   159 	/Library/Frameworks (e.g. $(HOME)/Library/Frameworks),
   160 	the framework will not be found to link to and the user 
   161 	has to manually fix this. But the upshot is (in addition to 
   162 	being visually displayed in the forefront) is that it is 
   163 	really easy to copy (embed) the framework automatically 
   164 	into the .app bundle on build. So I have added this 
   165 	feature, which makes the application potentially 
   166 	drag-and-droppable ready. The Project Builder templates 
   167 	are mostly unchanged due to the fact that I don't have 
   168 	Project Builder. I did rename a file extension to .pbxproj 
   169 	for the SDL Custom Cocoa Application template because 
   170 	the .pbx extension would not load in my version of Xcode.
   171 	For both Project Builder and Xcode templates, I resync'd
   172 	the SDLMain.* files for the SDL App and OpenGL App 
   173 	templates. I think people forget that we have 2 other 
   174 	SDLMain's (and .Nib's) and somebody needs to go 
   175 	through them and merge the new changes into those.
   176 	I also wrote a fix for the SDL Custom Cocoa App 
   177 	template in MyController.m. The sprite loading code 
   178 	needed to be able to find the icon.bmp in the .app
   179 	bundle's Resources folder. This change was needed to get 
   180 	the app to run out of the box. This might change is untested 
   181 	with Project Builder though and might break it.
   182 	There also seemed to be some corruption in the .nib itself.
   183 	Merely opening it and saving (allowing IB to correct the
   184 	.nib) seemed to correct things.
   185 	(Eric Wing)