docs/README-macosx.md
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Wed, 17 Aug 2016 21:04:50 +0200
changeset 10275 ba7dc3ebb81e
parent 10184 cb09212d4480
permissions -rw-r--r--
Emscripten: Fixed opening previously closed joystick.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     1
Mac OS X
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     2
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     3
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     4
These instructions are for people using Apple's Mac OS X (pronounced
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     5
"ten").
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     6
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     7
From the developer's point of view, OS X is a sort of hybrid Mac and
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     8
Unix system, and you have the option of using either traditional
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     9
command line tools or Apple's IDE Xcode.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    10
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    11
To build SDL using the command line, use the standard configure and make
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    12
process:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    13
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    14
	./configure
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    15
	make
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    16
	sudo make install
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    17
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    18
You can also build SDL as a Universal library (a single binary for both
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    19
32-bit and 64-bit Intel architectures), on Mac OS X 10.7 and newer, by using
9774
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    20
the gcc-fat.sh script in build-scripts:
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    21
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    22
    mkdir mybuild
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    23
    cd mybuild
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    24
    CC=$PWD/../build-scripts/gcc-fat.sh CXX=$PWD/../build-scripts/g++fat.sh ../configure
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    25
	make
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    26
	sudo make install
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    27
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    28
This script builds SDL with 10.5 ABI compatibility on i386 and 10.6
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    29
ABI compatibility on x86_64 architectures.  For best compatibility you
9774
3478d2a45b31 Updated Mac OS X documentation for fatbuilt.sh -> gcc-fat.sh transition.
Ryan C. Gordon <icculus@icculus.org>
parents: 9066
diff changeset
    30
should compile your application the same way.
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    31
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    32
Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    33
(even if you target back to 10.5 systems). PowerPC support for Mac OS X has
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    34
been officially dropped as of SDL 2.0.2.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    35
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    36
To use the library once it's built, you essential have two possibilities:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    37
use the traditional autoconf/automake/make method, or use Xcode.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    38
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    39
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    40
Caveats for using SDL with Mac OS X
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    41
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    42
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    43
Some things you have to be aware of when using SDL on Mac OS X:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    44
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    45
- If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    46
  SDL will not register its own. This means that SDL will not terminate using
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    47
  SDL_Quit if it receives a termination request, it will terminate like a 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    48
  normal app, and it will not send a SDL_DROPFILE when you request to open a
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    49
  file with the app. To solve these issues, put the following code in your 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    50
  NSApplicationDelegate implementation:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    51
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    52
9066
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    53
    - (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    54
    {
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    55
        if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    56
            SDL_Event event;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    57
            event.type = SDL_QUIT;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    58
            SDL_PushEvent(&event);
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    59
        }
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    60
    
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    61
        return NSTerminateCancel;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    62
    }
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    63
    
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    64
    - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    65
    {
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    66
        if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    67
            SDL_Event event;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    68
            event.type = SDL_DROPFILE;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    69
            event.drop.file = SDL_strdup([filename UTF8String]);
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    70
            return (SDL_PushEvent(&event) > 0);
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    71
        }
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    72
    
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    73
        return NO;
c2af3ff967cc Fixed markdown formatting in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    74
    }
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    75
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    76
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    77
Using the Simple DirectMedia Layer with a traditional Makefile
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    78
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    79
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    80
An existing autoconf/automake build system for your SDL app has good chances
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    81
to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    82
that you can distribute to users, you need to put the generated binary into a
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    83
so called "bundle", which basically is a fancy folder with a name like
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    84
"MyCoolGame.app".
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    85
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    86
To get this build automatically, add something like the following rule to
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    87
your Makefile.am:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    88
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    89
bundle_contents = APP_NAME.app/Contents
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    90
APP_NAME_bundle: EXE_NAME
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    91
	mkdir -p $(bundle_contents)/MacOS
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    92
	mkdir -p $(bundle_contents)/Resources
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    93
	echo "APPL????" > $(bundle_contents)/PkgInfo
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    94
	$(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    95
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    96
You should replace EXE_NAME with the name of the executable. APP_NAME is what
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    97
will be visible to the user in the Finder. Usually it will be the same
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    98
as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
10092
f1949a74dce5 Fixed doxygen warnings about markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9774
diff changeset
    99
usually is "TestGame". You might also want to use `@PACKAGE@` to use the package
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   100
name as specified in your configure.in file.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   101
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   102
If your project builds more than one application, you will have to do a bit
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   103
more. For each of your target applications, you need a separate rule.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   104
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   105
If you want the created bundles to be installed, you may want to add this
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   106
rule to your Makefile.am:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   107
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   108
install-exec-hook: APP_NAME_bundle
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   109
	rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   110
	mkdir -p $(DESTDIR)$(prefix)/Applications/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   111
	cp -r $< /$(DESTDIR)$(prefix)Applications/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   112
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   113
This rule takes the Bundle created by the rule from step 3 and installs them
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   114
into $(DESTDIR)$(prefix)/Applications/.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   115
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   116
Again, if you want to install multiple applications, you will have to augment
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   117
the make rule accordingly.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   118
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   119
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   120
But beware! That is only part of the story! With the above, you end up with
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   121
a bare bone .app bundle, which is double clickable from the Finder. But
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   122
there are some more things you should do before shipping your product...
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   123
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   124
1) The bundle right now probably is dynamically linked against SDL. That 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   125
   means that when you copy it to another computer, *it will not run*,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   126
   unless you also install SDL on that other computer. A good solution
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   127
   for this dilemma is to static link against SDL. On OS X, you can
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   128
   achieve that by linking against the libraries listed by
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   129
     sdl-config --static-libs
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   130
   instead of those listed by
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   131
     sdl-config --libs
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   132
   Depending on how exactly SDL is integrated into your build systems, the
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   133
   way to achieve that varies, so I won't describe it here in detail
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   134
2) Add an 'Info.plist' to your application. That is a special XML file which
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   135
   contains some meta-information about your application (like some copyright
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   136
   information, the version of your app, the name of an optional icon file,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   137
   and other things). Part of that information is displayed by the Finder
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   138
   when you click on the .app, or if you look at the "Get Info" window.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   139
   More information about Info.plist files can be found on Apple's homepage.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   140
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   141
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   142
As a final remark, let me add that I use some of the techniques (and some
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   143
variations of them) in Exult and ScummVM; both are available in source on
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   144
the net, so feel free to take a peek at them for inspiration!
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   145
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   146
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   147
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   148
Using the Simple DirectMedia Layer with Xcode
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   149
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   150
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   151
These instructions are for using Apple's Xcode IDE to build SDL applications.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   152
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   153
- First steps
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   154
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   155
The first thing to do is to unpack the Xcode.tar.gz archive in the
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   156
top level SDL directory (where the Xcode.tar.gz archive resides).
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   157
Because Stuffit Expander will unpack the archive into a subdirectory,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   158
you should unpack the archive manually from the command line:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   159
	cd [path_to_SDL_source]
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   160
	tar zxf Xcode.tar.gz
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   161
This will create a new folder called Xcode, which you can browse
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   162
normally from the Finder.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   163
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   164
- Building the Framework
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   165
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   166
The SDL Library is packaged as a framework bundle, an organized
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   167
relocatable folder hierarchy of executable code, interface headers,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   168
and additional resources. For practical purposes, you can think of a 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   169
framework as a more user and system-friendly shared library, whose library
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   170
file behaves more or less like a standard UNIX shared library.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   171
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   172
To build the framework, simply open the framework project and build it. 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   173
By default, the framework bundle "SDL.framework" is installed in 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   174
/Library/Frameworks. Therefore, the testers and project stationary expect
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   175
it to be located there. However, it will function the same in any of the
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   176
following locations:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   177
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   178
    ~/Library/Frameworks
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   179
    /Local/Library/Frameworks
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   180
    /System/Library/Frameworks
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   181
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   182
- Build Options
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   183
    There are two "Build Styles" (See the "Targets" tab) for SDL.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   184
    "Deployment" should be used if you aren't tweaking the SDL library.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   185
    "Development" should be used to debug SDL apps or the library itself.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   186
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   187
- Building the Testers
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   188
    Open the SDLTest project and build away!
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   189
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   190
- Using the Project Stationary
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   191
    Copy the stationary to the indicated folders to access it from
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   192
    the "New Project" and "Add target" menus. What could be easier?
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   193
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   194
- Setting up a new project by hand
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   195
    Some of you won't want to use the Stationary so I'll give some tips:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   196
    * Create a new "Cocoa Application"
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   197
    * Add src/main/macosx/SDLMain.m , .h and .nib to your project
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   198
    * Remove "main.c" from your project
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   199
    * Remove "MainMenu.nib" from your project
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   200
    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   201
    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   202
    * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   203
    * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   204
    * Add your files
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   205
    * Clean and build
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   206
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   207
- Building from command line
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   208
    Use pbxbuild in the same directory as your .pbproj file
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   209
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   210
- Running your app
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   211
    You can send command line args to your app by either invoking it from
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   212
    the command line (in *.app/Contents/MacOS) or by entering them in the
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   213
    "Executables" panel of the target settings.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   214
    
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   215
- Implementation Notes
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   216
    Some things that may be of interest about how it all works...
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   217
    * Working directory
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   218
        As defined in the SDL_main.m file, the working directory of your SDL app
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   219
        is by default set to its parent. You may wish to change this to better
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   220
        suit your needs.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   221
    * You have a Cocoa App!
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   222
        Your SDL app is essentially a Cocoa application. When your app
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   223
        starts up and the libraries finish loading, a Cocoa procedure is called,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   224
        which sets up the working directory and calls your main() method.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   225
        You are free to modify your Cocoa app with generally no consequence 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   226
        to SDL. You cannot, however, easily change the SDL window itself.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   227
        Functionality may be added in the future to help this.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   228
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   229
10184
cb09212d4480 Mac: Updated file name in README.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 10092
diff changeset
   230
Known bugs are listed in the file "BUGS.txt".