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