README.MacOSX
author Sam Lantinga <slouken@lokigames.com>
Sun, 10 Jun 2001 18:20:23 +0000
changeset 53 25dfe480c75e
parent 47 45b1c4303f87
child 172 37e3ca9254c7
permissions -rw-r--r--
Added MacOS X Project Builder projects
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
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    21
For some reason, libtool doesn't run ranlib properly, so do this
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    22
manually:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    23
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    24
	ranlib /usr/local/lib/libSDL.a
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    25
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    26
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
    27
framework", which is the port of the old Mac Toolbox to OS X.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    28
To do this, use the -F and -framework arguments for compiling
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    29
and linking, respectively:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    30
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    31
	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
    32
	cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    33
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    34
sdl-config knows about the linking path and -framework, so it's
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    35
recommended to use it to fill in your Makefile variables.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    36
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    37
==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    38
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
    39
==============================================================================
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    40
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    41
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
    42
53
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    43
- First steps
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    44
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    45
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
    46
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
    47
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
    48
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
    49
	cd [path_to_SDL_source]
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    50
	tar zxf PBProjects.tar.gz
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    51
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
    52
normally from the Finder.
25dfe480c75e Added MacOS X Project Builder projects
Sam Lantinga <slouken@lokigames.com>
parents: 47
diff changeset
    53
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    54
- Building the Framework
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    55
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    56
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
    57
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
    58
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
    59
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
    60
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
    61
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    62
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
    63
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
    64
~/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
    65
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
    66
following locations:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    67
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    68
    ~/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    69
    /Local/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    70
    /System/Library/Frameworks
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    71
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    72
- Build Options
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    73
    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
    74
    "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
    75
    "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
    76
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    77
- Building the Testers
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    78
    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
    79
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    80
- Using the Project Stationary
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    81
    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
    82
    the "New Project" and "Add target" menus. What could be easier?
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    83
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    84
- 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
    85
    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
    86
    * Create a new "Cocoa Application"
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    87
    * 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
    88
    * Remove "main.c" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    89
    * Remove "MainMenu.nib" from your project
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    90
    * 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
    91
    * 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
    92
    * 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
    93
    * 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
    94
    * Add your files
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    95
    * Clean and build
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    96
47
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    97
- Building from command line
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
    98
    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
    99
         
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   100
- Running your app
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   101
    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
   102
    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
   103
    "Executibles" panel of the target settings.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   104
    
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   105
- Implementation Notes
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   106
    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
   107
    * Working directory
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   108
        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
   109
        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
   110
        suit your needs.
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   111
    * You have a Cocoa App!
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   112
        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
   113
        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
   114
        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
   115
        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
   116
        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
   117
        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
   118
    * My development setup:
45b1c4303f87 Added initial support for Quartz video (thanks Darrell!)
Sam Lantinga <slouken@lokigames.com>
parents: 0
diff changeset
   119
        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
   120
        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
   121
        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
   122
        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
   123
        
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   124
Known bugs are listed in the file "BUGS"