README.MacOSX
author Sam Lantinga <slouken@lokigames.com>
Thu, 07 Jun 2001 14:28:11 +0000
changeset 47 45b1c4303f87
parent 0 74212992fb08
child 53 25dfe480c75e
permissions -rw-r--r--
Added initial support for Quartz video (thanks Darrell!)
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@0
    21
For some reason, libtool doesn't run ranlib properly, so do this
slouken@0
    22
manually:
slouken@0
    23
slouken@0
    24
	ranlib /usr/local/lib/libSDL.a
slouken@0
    25
slouken@0
    26
To use the library once it's built, you need to use the "Carbon
slouken@0
    27
framework", which is the port of the old Mac Toolbox to OS X.
slouken@0
    28
To do this, use the -F and -framework arguments for compiling
slouken@0
    29
and linking, respectively:
slouken@0
    30
slouken@0
    31
	cc -c myprog.c -I/usr/local/include/SDL -F/System/Library/Frameworks/Carbon.framework
slouken@0
    32
	cc myprog.o -L/usr/local/lib -lSDL -framework Carbon
slouken@0
    33
slouken@0
    34
sdl-config knows about the linking path and -framework, so it's
slouken@0
    35
recommended to use it to fill in your Makefile variables.
slouken@0
    36
slouken@47
    37
==============================================================================
slouken@47
    38
Using the Simple DirectMedia Layer with Project Builder
slouken@47
    39
==============================================================================
slouken@0
    40
slouken@47
    41
These instructions are for using Apple's Project Builder IDE to build SDL applications.
slouken@0
    42
slouken@47
    43
- Building the Framework
slouken@47
    44
slouken@47
    45
The SDL Library is packaged as a framework bundle, an organized
slouken@47
    46
relocatable folder heirarchy of executible code, interface headers, 
slouken@47
    47
and additional resources. For practical purposes, you can think of a 
slouken@47
    48
framework as a more user and system-friendly shared library, whose library
slouken@47
    49
file behaves more or less like a standard UNIX shared library.
slouken@47
    50
slouken@47
    51
To build the framework, simply open the framework project and build it. 
slouken@47
    52
By default, the framework bundle "SDL.framework" is installed in 
slouken@47
    53
~/Library/Frameworks. Therefore, the testers and project stationary expect
slouken@47
    54
it to be located there. However, it will function the same in any of the
slouken@47
    55
following locations:
slouken@47
    56
slouken@47
    57
    ~/Library/Frameworks
slouken@47
    58
    /Local/Library/Frameworks
slouken@47
    59
    /System/Library/Frameworks
slouken@47
    60
slouken@47
    61
- Build Options
slouken@47
    62
    There are two "Build Styles" (See the "Targets" tab) for SDL.
slouken@47
    63
    "Deployment" should be used if you aren't tweaking the SDL library.
slouken@47
    64
    "Development" should be used to debug SDL apps or the library itself.
slouken@47
    65
slouken@47
    66
- Building the Testers
slouken@47
    67
    Open the SDLTest project and build away!
slouken@47
    68
slouken@47
    69
- Using the Project Stationary
slouken@47
    70
    Copy the stationary to the indicated folders to access it from
slouken@47
    71
    the "New Project" and "Add target" menus. What could be easier?
slouken@47
    72
slouken@47
    73
- Setting up a new project by hand
slouken@47
    74
    Some of you won't want to use the Stationary so I'll give some tips:
slouken@47
    75
    * Create a new "Cocoa Application"
slouken@47
    76
    * Add src/main/macosx/SDLMain.m , .h and .nib to your project
slouken@47
    77
    * Remove "main.c" from your project
slouken@47
    78
    * Remove "MainMenu.nib" from your project
slouken@47
    79
    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
slouken@47
    80
    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
slouken@47
    81
    * Add "-framework SDL" to the "OTHER_LDFLAGS" variable
slouken@47
    82
    * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
slouken@47
    83
    * Add your files
slouken@47
    84
    * Clean and build
slouken@47
    85
slouken@47
    86
- Building from command line
slouken@47
    87
    Use pbxbuild in the same directory as your .pbproj file
slouken@47
    88
         
slouken@47
    89
- Running your app
slouken@47
    90
    You can send command line args to your app by either invoking it from
slouken@47
    91
    the command line (in *.app/Contents/MacOS) or by entering them in the
slouken@47
    92
    "Executibles" panel of the target settings.
slouken@47
    93
    
slouken@47
    94
- Implementation Notes
slouken@47
    95
    Some things that may be of interest about how it all works...
slouken@47
    96
    * Working directory
slouken@47
    97
        As defined in the SDLMain.m file, the working directory of your SDL app
slouken@47
    98
        is by default set to its parent. You may wish to change this to better
slouken@47
    99
        suit your needs.
slouken@47
   100
    * You have a Cocoa App!
slouken@47
   101
        Your SDL app is essentially a Cocoa application. When your app
slouken@47
   102
        starts up and the libraries finish loading, a Cocoa procedure is called,
slouken@47
   103
        which sets up the working directory and calls your main() method.
slouken@47
   104
        You are free to modify your Cocoa app with generally no consequence 
slouken@47
   105
        to SDL. You cannot, however, easily change the SDL window itself.
slouken@47
   106
        Functionality may be added in the future to help this.
slouken@47
   107
    * My development setup:
slouken@47
   108
        I am using version 1.0.1 (v63.0) of Project Builder on MacOS X 10.0.3,
slouken@47
   109
        from the Developer Tools CD for May 2001.
slouken@47
   110
        As of May 31 2001, Apple hasn't released this version of the tools to the public, 
slouken@47
   111
        but I expect that things will still work on older versions.
slouken@47
   112
        
slouken@0
   113
Known bugs are listed in the file "BUGS"