Initial commit.

author: 3gg <3gg@shellblade.net> 2024-05-04 16:51:29 -0700
committer: 3gg <3gg@shellblade.net> 2024-05-04 16:51:29 -0700
commit: 8222bfe56d4dabe8d92fc4b25ea1b0163b16f3e1 (patch)
tree: 763389e42276035ac134d94eb1dc32293b88d807 /src/contrib/SDL-2.30.2/docs/README-macos.md
1 files changed, 285 insertions, 0 deletions
diff --git a/src/contrib/SDL-2.30.2/docs/README-macos.md b/src/contrib/SDL-2.30.2/docs/README-macos.md
new file mode 100644
index 0000000..634d456
--- /dev/null
+++ b/src/contrib/SDL-2.30.2/docs/README-macos.md
@@ -0,0 +1,285 @@
+# Mac OS X (aka macOS).
+These instructions are for people using Apple's Mac OS X (pronounced
+"ten"), which in newer versions is just referred to as "macOS".
+From the developer's point of view, macOS is a sort of hybrid Mac and
+Unix system, and you have the option of using either traditional
+command line tools or Apple's IDE Xcode.
+# Command Line Build
+To build SDL using the command line, use the standard configure and make
+process:
+```bash
+mkdir build
+cd build
+../configure
+make
+sudo make install
+```
+CMake is also known to work, although it continues to be a work in progress:
+```bash
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make
+sudo make install
+```
+You can also build SDL as a Universal library (a single binary for both
+64-bit Intel and ARM architectures), by using the build-scripts/clang-fat.sh
+script.
+```bash
+mkdir build
+cd build
+CC=$PWD/../build-scripts/clang-fat.sh ../configure
+make
+sudo make install
+```
+This script builds SDL with 10.9 ABI compatibility on 64-bit Intel and 11.0
+ABI compatibility on ARM64 architectures.  For best compatibility you
+should compile your application the same way.
+Please note that building SDL requires at least Xcode 6 and the 10.9 SDK.
+PowerPC support for macOS has been officially dropped as of SDL 2.0.2.
+32-bit Intel and macOS 10.8 runtime support has been officially dropped as
+of SDL 2.24.0.
+To use the library once it's built, you essential have two possibilities:
+use the traditional autoconf/automake/make method, or use Xcode.
+# Caveats for using SDL with Mac OS X
+If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
+SDL will not register its own. This means that SDL will not terminate using
+SDL_Quit if it receives a termination request, it will terminate like a
+normal app, and it will not send a SDL_DROPFILE when you request to open a
+file with the app. To solve these issues, put the following code in your
+NSApplicationDelegate implementation:
+```objc
+- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
+{
+    if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
+        SDL_Event event;
+        event.type = SDL_QUIT;
+        SDL_PushEvent(&event);
+    }
+    return NSTerminateCancel;
+}
+- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
+{
+    if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
+        SDL_Event event;
+        event.type = SDL_DROPFILE;
+        event.drop.file = SDL_strdup([filename UTF8String]);
+        return (SDL_PushEvent(&event) > 0);
+    }
+    return NO;
+}
+```
+# Using the Simple DirectMedia Layer with a traditional Makefile
+An existing autoconf/automake build system for your SDL app has good chances
+to work almost unchanged on macOS. However, to produce a "real" Mac binary
+that you can distribute to users, you need to put the generated binary into a
+so called "bundle", which is basically a fancy folder with a name like
+"MyCoolGame.app".
+To get this build automatically, add something like the following rule to
+your Makefile.am:
+```make
+bundle_contents = APP_NAME.app/Contents
+APP_NAME_bundle: EXE_NAME
+        mkdir -p $(bundle_contents)/MacOS
+        mkdir -p $(bundle_contents)/Resources
+        echo "APPL????" > $(bundle_contents)/PkgInfo
+        $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
+```
+You should replace `EXE_NAME` with the name of the executable. `APP_NAME` is
+what will be visible to the user in the Finder. Usually it will be the same
+as `EXE_NAME` but capitalized. E.g. if `EXE_NAME` is "testgame" then `APP_NAME`
+usually is "TestGame". You might also want to use `@PACKAGE@` to use the
+package name as specified in your configure.ac file.
+If your project builds more than one application, you will have to do a bit
+more. For each of your target applications, you need a separate rule.
+If you want the created bundles to be installed, you may want to add this
+rule to your Makefile.am:
+```make
+install-exec-hook: APP_NAME_bundle
+        rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
+        mkdir -p $(DESTDIR)$(prefix)/Applications/
+        cp -r $< /$(DESTDIR)$(prefix)Applications/
+```
+This rule takes the Bundle created by the rule from step 3 and installs them
+into "$(DESTDIR)$(prefix)/Applications/".
+Again, if you want to install multiple applications, you will have to augment
+the make rule accordingly.
+But beware! That is only part of the story! With the above, you end up with
+a barebones .app bundle, which is double-clickable from the Finder. But
+there are some more things you should do before shipping your product...
+1. The bundle right now probably is dynamically linked against SDL. That
+   means that when you copy it to another computer, *it will not run*,
+   unless you also install SDL on that other computer. A good solution
+   for this dilemma is to static link against SDL. On OS X, you can
+   achieve that by linking against the libraries listed by
+   ```bash
+   sdl-config --static-libs
+   ```
+   instead of those listed by
+   ```bash
+   sdl-config --libs
+   ```
+   Depending on how exactly SDL is integrated into your build systems, the
+   way to achieve that varies, so I won't describe it here in detail
+2. Add an 'Info.plist' to your application. That is a special XML file which
+   contains some meta-information about your application (like some copyright
+   information, the version of your app, the name of an optional icon file,
+   and other things). Part of that information is displayed by the Finder
+   when you click on the .app, or if you look at the "Get Info" window.
+   More information about Info.plist files can be found on Apple's homepage.
+As a final remark, let me add that I use some of the techniques (and some
+variations of them) in [Exult](https://github.com/exult/exult) and
+[ScummVM](https://github.com/scummvm/scummvm); both are available in source on
+the net, so feel free to take a peek at them for inspiration!
+# Using the Simple DirectMedia Layer with Xcode
+These instructions are for using Apple's Xcode IDE to build SDL applications.
+## First steps
+The first thing to do is to unpack the Xcode.tar.gz archive in the
+top level SDL directory (where the Xcode.tar.gz archive resides).
+Because Stuffit Expander will unpack the archive into a subdirectory,
+you should unpack the archive manually from the command line:
+```bash
+cd [path_to_SDL_source]
+tar zxf Xcode.tar.gz
+```
+This will create a new folder called Xcode, which you can browse
+normally from the Finder.
+## Building the Framework
+The SDL Library is packaged as a framework bundle, an organized
+relocatable folder hierarchy of executable code, interface headers,
+and additional resources. For practical purposes, you can think of a
+framework as a more user and system-friendly shared library, whose library
+file behaves more or less like a standard UNIX shared library.
+To build the framework, simply open the framework project and build it.
+By default, the framework bundle "SDL.framework" is installed in
+/Library/Frameworks. Therefore, the testers and project stationary expect
+it to be located there. However, it will function the same in any of the
+following locations:
+* ~/Library/Frameworks
+* /Local/Library/Frameworks
+* /System/Library/Frameworks
+## Build Options
+There are two "Build Styles" (See the "Targets" tab) for SDL.
+"Deployment" should be used if you aren't tweaking the SDL library.
+"Development" should be used to debug SDL apps or the library itself.
+## Building the Testers
+Open the SDLTest project and build away!
+## Using the Project Stationary
+Copy the stationary to the indicated folders to access it from
+the "New Project" and "Add target" menus. What could be easier?
+## Setting up a new project by hand
+Some of you won't want to use the Stationary so I'll give some tips:
+(this is accurate as of Xcode 12.5.)
+* Click "File" -> "New" -> "Project...
+* Choose "macOS" and then "App" from the "Application" section.
+* Fill out the options in the next window. User interface is "XIB" and
+  Language is "Objective-C".
+* Remove "main.m" from your project
+* Remove "MainMenu.xib" from your project
+* Remove "AppDelegates.*" from your project
+* Add "\$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
+* Add "\$(HOME)/Library/Frameworks" to the frameworks search path
+* Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
+* Add your files
+* Clean and build
+## Building from command line
+Use `xcode-build` in the same directory as your .pbxproj file
+## Running your app
+You can send command line args to your app by either invoking it from
+the command line (in *.app/Contents/MacOS) or by entering them in the
+Executables" panel of the target settings.
+# Implementation Notes
+Some things that may be of interest about how it all works...
+## Working directory
+In SDL 1.2, the working directory of your SDL app is by default set to its
+parent, but this is no longer the case in SDL 2.0. SDL2 does change the
+working directory, which means it'll be whatever the command line prompt
+that launched the program was using, or if launched by double-clicking in
+the finger, it will be "/", the _root of the filesystem_. Plan accordingly!
+You can use SDL_GetBasePath() to find where the program is running from and
+chdir() there directly.
+## You have a Cocoa App!
+Your SDL app is essentially a Cocoa application. When your app
+starts up and the libraries finish loading, a Cocoa procedure is called,
+which sets up the working directory and calls your main() method.
+You are free to modify your Cocoa app with generally no consequence
+to SDL. You cannot, however, easily change the SDL window itself.
+Functionality may be added in the future to help this.
+# Bug reports
+Bugs are tracked at [the GitHub issue tracker](https://github.com/libsdl-org/SDL/issues/).
+Please feel free to report bugs there!
author	3gg <3gg@shellblade.net>	2024-05-04 16:51:29 -0700
committer	3gg <3gg@shellblade.net>	2024-05-04 16:51:29 -0700
commit	8222bfe56d4dabe8d92fc4b25ea1b0163b16f3e1 (patch)
tree	763389e42276035ac134d94eb1dc32293b88d807 /src/contrib/SDL-2.30.2/docs/README-macos.md

diff --git a/src/contrib/SDL-2.30.2/docs/README-macos.md b/src/contrib/SDL-2.30.2/docs/README-macos.md new file mode 100644 index 0000000..634d456 --- /dev/null +++ b/src/contrib/SDL-2.30.2/docs/README-macos.md
@@ -0,0 +1,285 @@
	1	# Mac OS X (aka macOS).
	2
	3	These instructions are for people using Apple's Mac OS X (pronounced
	4	"ten"), which in newer versions is just referred to as "macOS".
	5
	6	From the developer's point of view, macOS is a sort of hybrid Mac and
	7	Unix system, and you have the option of using either traditional
	8	command line tools or Apple's IDE Xcode.
	9
	10	# Command Line Build
	11
	12	To build SDL using the command line, use the standard configure and make
	13	process:
	14
	15	```bash
	16	mkdir build
	17	cd build
	18	../configure
	19	make
	20	sudo make install
	21	```
	22
	23	CMake is also known to work, although it continues to be a work in progress:
	24
	25	```bash
	26	mkdir build
	27	cd build
	28	cmake -DCMAKE_BUILD_TYPE=Release ..
	29	make
	30	sudo make install
	31	```
	32
	33
	34	You can also build SDL as a Universal library (a single binary for both
	35	64-bit Intel and ARM architectures), by using the build-scripts/clang-fat.sh
	36	script.
	37
	38	```bash
	39	mkdir build
	40	cd build
	41	CC=$PWD/../build-scripts/clang-fat.sh ../configure
	42	make
	43	sudo make install
	44	```
	45
	46	This script builds SDL with 10.9 ABI compatibility on 64-bit Intel and 11.0
	47	ABI compatibility on ARM64 architectures. For best compatibility you
	48	should compile your application the same way.
	49
	50	Please note that building SDL requires at least Xcode 6 and the 10.9 SDK.
	51	PowerPC support for macOS has been officially dropped as of SDL 2.0.2.
	52	32-bit Intel and macOS 10.8 runtime support has been officially dropped as
	53	of SDL 2.24.0.
	54
	55	To use the library once it's built, you essential have two possibilities:
	56	use the traditional autoconf/automake/make method, or use Xcode.
	57
	58
	59	# Caveats for using SDL with Mac OS X
	60
	61	If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
	62	SDL will not register its own. This means that SDL will not terminate using
	63	SDL_Quit if it receives a termination request, it will terminate like a
	64	normal app, and it will not send a SDL_DROPFILE when you request to open a
	65	file with the app. To solve these issues, put the following code in your
	66	NSApplicationDelegate implementation:
	67
	68
	69	```objc
	70	- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
	71	{
	72	if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
	73	SDL_Event event;
	74	event.type = SDL_QUIT;
	75	SDL_PushEvent(&event);
	76	}
	77
	78	return NSTerminateCancel;
	79	}
	80
	81	- (BOOL)application:(NSApplication )theApplication openFile:(NSString )filename
	82	{
	83	if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
	84	SDL_Event event;
	85	event.type = SDL_DROPFILE;
	86	event.drop.file = SDL_strdup([filename UTF8String]);
	87	return (SDL_PushEvent(&event) > 0);
	88	}
	89
	90	return NO;
	91	}
	92	```
	93
	94	# Using the Simple DirectMedia Layer with a traditional Makefile
	95
	96	An existing autoconf/automake build system for your SDL app has good chances
	97	to work almost unchanged on macOS. However, to produce a "real" Mac binary
	98	that you can distribute to users, you need to put the generated binary into a
	99	so called "bundle", which is basically a fancy folder with a name like
	100	"MyCoolGame.app".
	101
	102	To get this build automatically, add something like the following rule to
	103	your Makefile.am:
	104
	105	```make
	106	bundle_contents = APP_NAME.app/Contents
	107	APP_NAME_bundle: EXE_NAME
	108	mkdir -p $(bundle_contents)/MacOS
	109	mkdir -p $(bundle_contents)/Resources
	110	echo "APPL????" > $(bundle_contents)/PkgInfo
	111	$(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
	112	```
	113
	114	You should replace `EXE_NAME` with the name of the executable. `APP_NAME` is
	115	what will be visible to the user in the Finder. Usually it will be the same
	116	as `EXE_NAME` but capitalized. E.g. if `EXE_NAME` is "testgame" then `APP_NAME`
	117	usually is "TestGame". You might also want to use `@PACKAGE@` to use the
	118	package name as specified in your configure.ac file.
	119
	120	If your project builds more than one application, you will have to do a bit
	121	more. For each of your target applications, you need a separate rule.
	122
	123	If you want the created bundles to be installed, you may want to add this
	124	rule to your Makefile.am:
	125
	126	```make
	127	install-exec-hook: APP_NAME_bundle
	128	rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
	129	mkdir -p $(DESTDIR)$(prefix)/Applications/
	130	cp -r $< /$(DESTDIR)$(prefix)Applications/
	131	```
	132
	133	This rule takes the Bundle created by the rule from step 3 and installs them
	134	into "$(DESTDIR)$(prefix)/Applications/".
	135
	136	Again, if you want to install multiple applications, you will have to augment
	137	the make rule accordingly.
	138
	139	But beware! That is only part of the story! With the above, you end up with
	140	a barebones .app bundle, which is double-clickable from the Finder. But
	141	there are some more things you should do before shipping your product...
	142
	143	1. The bundle right now probably is dynamically linked against SDL. That
	144	means that when you copy it to another computer, it will not run,
	145	unless you also install SDL on that other computer. A good solution
	146	for this dilemma is to static link against SDL. On OS X, you can
	147	achieve that by linking against the libraries listed by
	148
	149	```bash
	150	sdl-config --static-libs
	151	```
	152
	153	instead of those listed by
	154
	155	```bash
	156	sdl-config --libs
	157	```
	158
	159	Depending on how exactly SDL is integrated into your build systems, the
	160	way to achieve that varies, so I won't describe it here in detail
	161
	162	2. Add an 'Info.plist' to your application. That is a special XML file which
	163	contains some meta-information about your application (like some copyright
	164	information, the version of your app, the name of an optional icon file,
	165	and other things). Part of that information is displayed by the Finder
	166	when you click on the .app, or if you look at the "Get Info" window.
	167	More information about Info.plist files can be found on Apple's homepage.
	168
	169
	170	As a final remark, let me add that I use some of the techniques (and some
	171	variations of them) in [Exult](https://github.com/exult/exult) and
	172	[ScummVM](https://github.com/scummvm/scummvm); both are available in source on
	173	the net, so feel free to take a peek at them for inspiration!
	174
	175
	176	# Using the Simple DirectMedia Layer with Xcode
	177
	178	These instructions are for using Apple's Xcode IDE to build SDL applications.
	179
	180	## First steps
	181
	182	The first thing to do is to unpack the Xcode.tar.gz archive in the
	183	top level SDL directory (where the Xcode.tar.gz archive resides).
	184	Because Stuffit Expander will unpack the archive into a subdirectory,
	185	you should unpack the archive manually from the command line:
	186
	187	```bash
	188	cd [path_to_SDL_source]
	189	tar zxf Xcode.tar.gz
	190	```
	191
	192	This will create a new folder called Xcode, which you can browse
	193	normally from the Finder.
	194
	195	## Building the Framework
	196
	197	The SDL Library is packaged as a framework bundle, an organized
	198	relocatable folder hierarchy of executable code, interface headers,
	199	and additional resources. For practical purposes, you can think of a
	200	framework as a more user and system-friendly shared library, whose library
	201	file behaves more or less like a standard UNIX shared library.
	202
	203	To build the framework, simply open the framework project and build it.
	204	By default, the framework bundle "SDL.framework" is installed in
	205	/Library/Frameworks. Therefore, the testers and project stationary expect
	206	it to be located there. However, it will function the same in any of the
	207	following locations:
	208
	209	* ~/Library/Frameworks
	210	* /Local/Library/Frameworks
	211	* /System/Library/Frameworks
	212
	213	## Build Options
	214
	215	There are two "Build Styles" (See the "Targets" tab) for SDL.
	216	"Deployment" should be used if you aren't tweaking the SDL library.
	217	"Development" should be used to debug SDL apps or the library itself.
	218
	219	## Building the Testers
	220
	221	Open the SDLTest project and build away!
	222
	223	## Using the Project Stationary
	224
	225	Copy the stationary to the indicated folders to access it from
	226	the "New Project" and "Add target" menus. What could be easier?
	227
	228	## Setting up a new project by hand
	229
	230	Some of you won't want to use the Stationary so I'll give some tips:
	231
	232	(this is accurate as of Xcode 12.5.)
	233
	234	* Click "File" -> "New" -> "Project...
	235	* Choose "macOS" and then "App" from the "Application" section.
	236	* Fill out the options in the next window. User interface is "XIB" and
	237	Language is "Objective-C".
	238	* Remove "main.m" from your project
	239	* Remove "MainMenu.xib" from your project
	240	* Remove "AppDelegates.*" from your project
	241	* Add "\$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
	242	* Add "\$(HOME)/Library/Frameworks" to the frameworks search path
	243	* Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
	244	* Add your files
	245	* Clean and build
	246
	247	## Building from command line
	248
	249	Use `xcode-build` in the same directory as your .pbxproj file
	250
	251	## Running your app
	252
	253	You can send command line args to your app by either invoking it from
	254	the command line (in *.app/Contents/MacOS) or by entering them in the
	255	Executables" panel of the target settings.
	256
	257	# Implementation Notes
	258
	259	Some things that may be of interest about how it all works...
	260
	261	## Working directory
	262
	263	In SDL 1.2, the working directory of your SDL app is by default set to its
	264	parent, but this is no longer the case in SDL 2.0. SDL2 does change the
	265	working directory, which means it'll be whatever the command line prompt
	266	that launched the program was using, or if launched by double-clicking in
	267	the finger, it will be "/", the _root of the filesystem_. Plan accordingly!
	268	You can use SDL_GetBasePath() to find where the program is running from and
	269	chdir() there directly.
	270
	271
	272	## You have a Cocoa App!
	273
	274	Your SDL app is essentially a Cocoa application. When your app
	275	starts up and the libraries finish loading, a Cocoa procedure is called,
	276	which sets up the working directory and calls your main() method.
	277	You are free to modify your Cocoa app with generally no consequence
	278	to SDL. You cannot, however, easily change the SDL window itself.
	279	Functionality may be added in the future to help this.
	280
	281	# Bug reports
	282
	283	Bugs are tracked at [the GitHub issue tracker](https://github.com/libsdl-org/SDL/issues/).
	284	Please feel free to report bugs there!
	285