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