Xcode/SDL/pkg-support/Readme SDL Developer.txt
author Sam Lantinga <slouken@libsdl.org>
Wed, 03 Oct 2012 19:02:46 -0700
changeset 6549 db16b819e1d1
parent 3682 e4009cea0e82
permissions -rwxr-xr-x
Added a delay hack to let the window manager adjust to the mode change. I'm not sure if this is a good idea, but at least it works sometimes now. :)
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,
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
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