docs/README-macosx.md
author Ryan C. Gordon <icculus@icculus.org>
Sun, 27 Aug 2017 22:15:57 -0400
changeset 11365 a9bd2625fa01
parent 10556 007dfe83abf8
child 11400 9eefdf672499
permissions -rw-r--r--
vulkan: Initial Vulkan support!

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