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