README.MacOSX
author Sam Lantinga <slouken@libsdl.org>
Tue, 11 Sep 2001 19:00:18 +0000
changeset 172 37e3ca9254c7
parent 53 25dfe480c75e
child 191 c151cfc43c07
permissions -rw-r--r--
Date: Sat, 8 Sep 2001 04:42:23 +0200 From: Max Horn <max@quendi.de> Subject: SDL/OSX: Joystick; Better key handling I just finished implementing improved keyhandling for OS X (in fact the code should be easily ported to the "normal" MacOS part of SDL, I just had no chance yet). Works like this: First init the mapping table statically like before. Them, it queries the OS for the "official" key table, then iterates over all 127 scancode and gets the associates ascii code. It ignores everythng below 32 (has to, as it would lead to many problems if we did not... e.g. both ESC and NUM LOCk produce an ascii code 27 on my keyboard), and all stuff above 127 is mapped to SDLK_WORLD_* simply in the order it is encountered. In addition, caps lock is now working, too. The code work flawless for me, but since I only have one keyboard, I may have not encountered some serious problem... but I am pretty confident that it is better than the old code in most cases. The joystick driver works fine for me, too. I think it can be added to CVS already. It would simply be helpful if more people would test it. Hm, I wonder if Maelstrom or GLTron has Joystick support? That would be a wonderful test application :) I also took the liberty of modifying some text files like BUGS, README.CVS, README.MacOSX (which now contains the OS X docs I long promised)
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     1
==============================================================================
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     2
Using the Simple DirectMedia Layer with Mac OS X
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     3
==============================================================================
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     4
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     5
These instructions are for people using Apple's Mac OS X (pronounced
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     6
"ten").
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     7
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     8
From the developer's point of view, OS X is a sort of hybrid Mac and
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     9
Unix system, and you have the option of using either traditional
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    10
command line tools or Apple's IDE ProjectBuilder (PB).
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    11
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    12
To build using the command line, use the standard configure and make
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    13
process:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    14
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    15
	./configure
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    16
	make
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    17
	make install
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    18
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    19
(You may need to create the subdirs of /usr/local manually.)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    20
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    21
/*
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    22
To use the library once it's built, you need to use the "Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    23
framework", which is the port of the old Mac Toolbox to OS X.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    24
To do this, use the -F and -framework arguments for compiling
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    25
and linking, respectively:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    26
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    27
	cc -c myprog.c -I/usr/local/include/SDL -F/System/Library/Frameworks/Carbon.framework
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    28
	cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    29
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    30
sdl-config knows about the linking path and -framework, so it's
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    31
recommended to use it to fill in your Makefile variables.
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    32
*/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    33
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    34
To use the library once it's built, you essential have two possibilities:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    35
use the traditional autoconf/automake/make method, or use Apple's Project Builder.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    36
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    37
==============================================================================
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    38
Using the Simple DirectMedia Layer with a traditional Makefile
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    39
==============================================================================
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    40
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    41
In the following, it will be mostly assumed that you are using autoconf and
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    42
automake to setup your SDL project, and furthermore that you use the AM_PATH_SDL
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    43
macro provided by SDL in sdl.m4. If you are not using these tools, you can
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    44
still use SDL but it will be somewhat hard to get running.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    45
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    46
Only step 1) is really required to get started, but for full OS X support you
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    47
will want to do the other steps, too.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    48
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    49
1) Update your acinclude.m4 file in case you have copied an older version of
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    50
   sdl.m4 into it. This is essential as AM_PATH_SDL now performs some additional
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    51
   tasks when used on MacOS X
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    52
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    53
   Rationale: AM_PATH_SDL copies /usr/local/share/sdl/Info.plist and the folder
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    54
   /usr/local/share/sdl/SDLMain.nib/ into the directory where configure is invoked.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    55
   This is essential for the configure script to be able to run the test code
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    56
   that detects SDL.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    57
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    58
2) Copy SDL's Info.plist.in file (from src/main/macosx) into your project's main
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    59
   folder (the same spot that your configure.in sits), and edit it to suite your
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    60
   needs. Then add it to your AC_OUTPUT list in configure.in
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    61
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    62
   Rationale: The Info.plist file can be used to specify an icon file for
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    63
   your app, and also to provide a human readable version/copyright string
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    64
   and other meta-information to the user via the Finder's Get Info dialog.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    65
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    66
3) Add something like the following rule to your Makefile.am:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    67
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    68
APP_NAME.app: EXE_NAME
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    69
	mkdir -p $@/Contents/MacOS
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    70
	mkdir -p $@/Contents/Resources
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    71
	mkdir -p $@/Contents/Resources/SDLMain.nib
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    72
	echo "APPL????" > $@/Contents/PkgInfo
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    73
	$(INSTALL_DATA) Info.plist $@/Contents/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    74
	$(INSTALL_DATA) SDLMain.nib/*.nib $@/Contents/Resources/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    75
	$(INSTALL_PROGRAM) $< $@/Contents/MacOS/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    76
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    77
   You should replace EXE_NAME with the name of the executable. APP_NAME is what
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    78
   will be visible to the user in the Finder. Usually it will be the same
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    79
   as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    80
   usually is "TestGame"
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    81
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    82
   If your project builds more than one application, you will have to do a bit more.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    83
   For each of your target applications, you need a seperate rule. Furthermore, each
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    84
   needs its own Info.plist file, since that has to contain the exact name of the 
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    85
   executable (i.e. EXE_NAME above). One way to do that is to use sed in your make rules
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    86
   and modify a single master Info.plist.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    87
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    88
   Rationale: on Mac OS X, executables have to be put into so-called "bundles".
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    89
   The make rule given above will construct such a bundle around the executable
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    90
   for you. You need to make a copy of it for each target application.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    91
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    92
4) If you want the create bundles to be installed, you may want to add this
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    93
   rule to your Makefile.am:
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    94
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    95
install-exec-local: Exult.app
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    96
	mkdir -p /Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    97
	cp -r $< /Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    98
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
    99
   This rule takes the Bundle created by the rule from step 3 and installs them
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   100
   into /Applications/. An alternate installation place would be $HOME/Applications/
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   101
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   102
   Again, if you want to install multiple applications, you will have to augment
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   103
   the make rule accordingly.
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   104
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   105
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   106
==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   107
Using the Simple DirectMedia Layer with Project Builder
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   108
==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   109
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   110
These instructions are for using Apple's Project Builder IDE to build SDL applications.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   111
53
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   112
- First steps
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   113
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   114
The first thing to do is to unpack the PBProjects.tar.gz archive in the
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   115
top level SDL directory (where the PBProjects.tar.gz archive resides).
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   116
Because Stuffit Expander will unpack the archive into a subdirectory,
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   117
you should unpack the archive manually from the command line:
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   118
	cd [path_to_SDL_source]
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   119
	tar zxf PBProjects.tar.gz
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   120
This will create a new folder called PBProjects, which you can browse
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   121
normally from the Finder.
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
   122
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   123
- Building the Framework
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   124
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   125
The SDL Library is packaged as a framework bundle, an organized
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   126
relocatable folder heirarchy of executible code, interface headers, 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   127
and additional resources. For practical purposes, you can think of a 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   128
framework as a more user and system-friendly shared library, whose library
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   129
file behaves more or less like a standard UNIX shared library.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   130
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   131
To build the framework, simply open the framework project and build it. 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   132
By default, the framework bundle "SDL.framework" is installed in 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   133
~/Library/Frameworks. Therefore, the testers and project stationary expect
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   134
it to be located there. However, it will function the same in any of the
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   135
following locations:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   136
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   137
    ~/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   138
    /Local/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   139
    /System/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   140
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   141
- Build Options
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   142
    There are two "Build Styles" (See the "Targets" tab) for SDL.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   143
    "Deployment" should be used if you aren't tweaking the SDL library.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   144
    "Development" should be used to debug SDL apps or the library itself.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   145
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   146
- Building the Testers
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   147
    Open the SDLTest project and build away!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   148
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   149
- Using the Project Stationary
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   150
    Copy the stationary to the indicated folders to access it from
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   151
    the "New Project" and "Add target" menus. What could be easier?
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   152
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   153
- Setting up a new project by hand
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   154
    Some of you won't want to use the Stationary so I'll give some tips:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   155
    * Create a new "Cocoa Application"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   156
    * Add src/main/macosx/SDLMain.m , .h and .nib to your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   157
    * Remove "main.c" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   158
    * Remove "MainMenu.nib" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   159
    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   160
    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   161
    * Add "-framework SDL" to the "OTHER_LDFLAGS" variable
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   162
    * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   163
    * Add your files
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   164
    * Clean and build
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   165
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   166
- Building from command line
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   167
    Use pbxbuild in the same directory as your .pbproj file
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   168
         
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   169
- Running your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   170
    You can send command line args to your app by either invoking it from
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   171
    the command line (in *.app/Contents/MacOS) or by entering them in the
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   172
    "Executibles" panel of the target settings.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   173
    
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   174
- Implementation Notes
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   175
    Some things that may be of interest about how it all works...
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   176
    * Working directory
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   177
        As defined in the SDLMain.m file, the working directory of your SDL app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   178
        is by default set to its parent. You may wish to change this to better
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   179
        suit your needs.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   180
    * You have a Cocoa App!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   181
        Your SDL app is essentially a Cocoa application. When your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   182
        starts up and the libraries finish loading, a Cocoa procedure is called,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   183
        which sets up the working directory and calls your main() method.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   184
        You are free to modify your Cocoa app with generally no consequence 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   185
        to SDL. You cannot, however, easily change the SDL window itself.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   186
        Functionality may be added in the future to help this.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   187
    * My development setup:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   188
        I am using version 1.0.1 (v63.0) of Project Builder on MacOS X 10.0.3,
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   189
        from the Developer Tools CD for May 2001.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   190
        As of May 31 2001, Apple hasn't released this version of the tools to the public, 
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   191
        but I expect that things will still work on older versions.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   192
        
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   193
Known bugs are listed in the file "BUGS"
172
37e3ca9254c7 Date: Sat, 8 Sep 2001 04:42:23 +0200
Sam Lantinga <slouken@libsdl.org>
parents: 53
diff changeset
   194
 LocalWords:  Stuffit