ReadMe.txt
1The Simple DirectMedia Layer (SDL for short) is a cross-platform
2library designed to make it easy to write multi-media software,
3such as games and emulators.
4
5The Simple DirectMedia Layer library source code is available from:
6http://www.libsdl.org/
7
8This library is distributed under the terms of the GNU LGPL license:
9http://www.gnu.org/copyleft/lesser.html
10
11
12This packages contains the SDL.framework for OS X.
13Conforming with Apple guidelines, this framework
14contains both the SDL runtime component and development header files.
15
16
17To Install:
18Copy the SDL.framework to /Library/Frameworks
19
20You may alternatively install it in <Your home directory>/Library/Frameworks
21if your access privileges are not high enough.
22(Be aware that the Xcode templates we provide in the SDL Developer Extras
23package may require some adjustment for your system if you do this.)
24
25
26Known Issues:
27???
28
29
30Additional References:
31
32 - Screencast tutorials for getting started with OpenSceneGraph/Mac OS X are
33 available at:
34 http://www.openscenegraph.org/projects/osg/wiki/Support/Tutorials/MacOSXTips
35 Though these are OpenSceneGraph centric, the same exact concepts apply to
36 SDL, thus the videos are recommended for everybody getting started with
37 developing on Mac OS X. (You can skim over the PlugIns stuff since SDL
38 doesn't have any PlugIns to worry about.)
39
40
41
42(Partial) History of PB/Xcode projects:
432009-09-21 - Added 64-bit for Snow Leopard. 10.4 is the new minimum requirement.
44 Removed 'no X11' targets as
45 new codebase will assume you have them. Also removed specific #defines
46 for X11, but needed to add search path to /usr/X11R6/include
47
482007-12-31 - Enabled strip -x in the Xcode settings and removed it
49 from the Build DMG script.
50 Added a per-arch setting for the Deployment targets for OTHER_LDFLAGS_ppc
51 to re-enable prebinding.
52 Need to remember to copy these changes to the SDL satellite projects.
53
542007-12-30 - Updated documentation to reflect new installation paths for
55 Xcode project templates under Leopard (Xcode 2.5/3.0).
56
57????-??-?? - Added extra targets for building formal releases against the
58 10.2 SDK so we don't have to keep modifying the settings.
59
60????-??-?? - Added fancy DMG (background logo) support with automation.
61
622006-05-09 - Added shell script phase to deal with new SDL_config.h
63 behavior. Encountered what seems to be an Xcode bug with
64 multiple files of the same name, even when conditional compiling
65 is controlled by custom #defines (SDL_sysloadso.c). Multiple or
66 undefined symbols are the result of this.
67 Recommended that macosx/SDL_sysloadso.c be modified to directly
68 include the dlopen version of the file via #ifdef's so only
69 one version needs to exist. Filed a formal bug report with Apple
70 about this (4542369).
71
722006-03-22 - gcc 4 visibility features have been added to the code base so I
73 enabled the switch in Xcode to take advantage of it. Be aware that only
74 our x86 builds will be exposed to this feature as we still build ppc
75 with gcc 3.3.
76
77 Christian Walther has sent me some great feedback on things that are
78 broken, so I have made some of these fixes. Among the issues are
79 compatibility and current library versions are not set to 1 (breaks
80 backwards compatibility), documentation errors, resource copying
81 location problems for the SDLTest apps, missing HAVE_OPENGL and
82 OpenGL.framework linking in testgl.
83 (Eric Wing)
84
852006-03-17 - Because the X11 headers are not installed by default with Xcode,
86 we decided to offer two variants of the same targets (one with X11 stuff
87 and one without). By default, since the X11 stuff does not necessarily
88 conflict with the native stuff, we build the libraries with the X11 stuff
89 so advanced developers can access it by default. However, in the case
90 that a developer did not install X11 (or just doesn't want the extra bloat),
91 the user may directly select those targets and build those instead.
92
93 Once again, we are attempting to remove the exported symbols file. If
94 I recall correctly, the clashing symbol problems we got were related
95 to the CD-ROM code which was formerly in C++. Now that the C++ code
96 has been purged, we are speculating that we might be able to remove
97 the exports file safely. The long term solution is to utilize gcc 4's
98 visibility features.
99
100 For the developer extras package, I changed the package format
101 from a .pkg based installer to a .dmg to avoid requiring
102 administrator/root to access contents, for better
103 transparency, and to allow users to more easily control which components
104 they actually want to install.
105 I also made changes and updates to the PB/Xcode project templates (see Developer ReadMe).
106 (Eric Wing)
107
1082006-03-07 - The entire code base has been reorganized and platform specific
109 defines have been pushed into header files (SDL_config_*.h). This means
110 that defines that previously had to be defined in the Xcode projects can
111 be removed (which I have started doing). Furthermore, it appears that the
112 MMX/SSE code has been rewritten and refactored so it now compiles without
113 nasm and without making us do strange things to support OS X. However, this
114 Xcode project still employs architecture specific build options in order to
115 achieve the mandated 10.2 compatibility. As a result of the code base changes,
116 there are new public headers. But also as a result of these changes, there are
117 also new headers that qualify as "PrivateHeaders". Private Headers are headers
118 that must be exported because a public header includes them, but users shouldn't
119 directly invoke these. SDL_config_macosx.h and SDL_config_dreamcast.h are
120 examples of this. We have considered marking these headers as Private, but it
121 requires that the public headers invoke them via framework conventions, i.e.
122 #include <FrameworkName/Header.h>
123 e.g.
124 #include <SDL/SDL_config_macosx.h>
125 and not
126 #include "SDL_config_macosx.h"
127 However this imposes the restriction that non-framework distributions must
128 place their headers in a directory called SDL/ (and not SDL11/ like FreeBSD).
129 Currently, I do not believe this would pose a problem for any of the current
130 distributions (Fink, DarwinPorts). Or alternatively, users could be
131 expected/forced to also include the header path:
132 -I/Library/Frameworks/SDL.framework/PrivateHeaders,
133 but most people would probably not read the documentation on this.
134 But currently, we have decided to be conservative and have opted not to
135 use the PrivateHeaders feature.
136 (Eric Wing)
137
1382006-01-31 - Updates to build Universal Binaries while retaining 10.2 compatibility.
139 We were unable to get MMX/SSE support enabled. It is believed that a rewrite of
140 the assembly code will be necessary to make it position independent and not
141 require nasm. Altivec has finally been enabled for PPC. (Eric Wing)
142
1432005-09-?? - Had to add back the exports file because it was causing build problems
144 for some cases. (Eric Wing)
145
1462005-08-21 - First entry in history. Updated for SDL 1.2.9 and Xcode 2.1. Getting
147 ready for Universal Binaries. Removed the .pkg system for .dmg for due to problems
148 with broken packages in the past several SDL point releases. Removed usage of SDL
149 exports file because it has become another point of failure. Introduced new documentation
150 about SDLMain and how to compile in an devel-lite section of the SDL.dmg. (Eric Wing)
151
152Before history:
153SDL 1.2.6? to 1.2.8
154Started updating Project Builder projects to Xcode for Panther and Tiger. Also removed
155the system that split the single framework into separate runtime and headers frameworks.
156This is against Apple conventions and causes problems on multiuser systems.
157We now distribute a single framework.
158The .pkg system has repeatedly been broken with every new release of OS X.
159With 1.2.8, started migrating stuff to .dmg based system to simplify distribution process.
160Tried updating the exports file and Perl script generation system for changing syntax. (Eric Wing)
161
162Pre-SDL 1.2.6
163Created Project Builder projects for SDL and .pkg based distribution system. (Darrell Walisser)
164
165
166
167
168
169
170
171
172
ReadMeDevLite.txt
1This directory is for developers. This directory contains some basic essentials you will need for developing SDL based applications on OS X. The SDL-devel package contains all of this stuff plus more, so you can ignore this if you install the SDL-devel.pkg. The SDL-devel package contains Xcode templates, SDL documentation, and different variations of SDLmain and NIB files for SDL.
2
3To compile an SDL based application on OS X, SDLMain.m must be compiled into your program. (See the SDL FAQ). The SDL-devel.pkg includes Xcode templates which already do this for you. But for those who may not want to install the dev package, an SDLMain is provided here as a convenience. Be aware that there are different variations of SDLMain.m depending on what class of SDL application you make and they are intended to work with NIB files. Only one SDLMain variant is provided here and without any NIB files. You should look to the SDL-devel package for the others. We currently do not provide a SDLMain.a file, partly to call to attention that there are different variations of SDLmain.
4
5To build from the command line, your gcc line will look something like this:
6
7gcc -I/Library/Frameworks/SDL.framework/Headers MyProgram.c SDLmain.m -framework SDL -framework Cocoa
8
9An SDL/OpenGL based application might look like:
10
11gcc -I/Library/Frameworks/SDL.framework/Headers -I/System/Library/Frameworks/OpenGL.framework/Headers MyProgram.c SDLmain.m -framework SDL -framework Cocoa -framework OpenGL
12
13