libretro-super/docs/README.MacOSX.md

# Requirements for libretro-super on OS X

As of this writing, OS X support for libretro-super requires use of a Terminal
application.  You'll also need Apple's Xcode, a set of command line tools for
your versionf of Xcode, and possibly also the source code management tool git.

## OS X 10.7 Lion and later

As of OS X 10.7, the correct way to get Xcode is via the Mac App Store.  If
you've been keeping up with OS X versions, you may simply go to the App Store
page for [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) and
click the friendly GET or iCloud download button, as appropriate.  An annoying
bug recently observed (as of 2015 February) is that you cannot download old
versions of App Store programs unless you have already "purchased" the app.

In that case, go to [Apple Developer Connection](http://developer.apple.com/)
and find it there.  It's buried and Apple tends to move it around
periodically, sorry.

Once you have installed Xcode (version 4+), open it and go into Preferences.
Select the Downloads pane, and click the Install button for Command Line
Tools.  Every time you upgrade Xcode, you'll want to back here to see if
Command Line Tools needs upgrading.

Once you've done that, check the section below about ``git``.


## OS X 10.5 Leopard and 10.6 Snow Leopard (and older?)

While the final versionf of OS X 10.6 did feature the Mac App Store, Xcode for
these versions generally came with the system installation media or a retail
OS X install disc.  Even so, a more recent version is probably available for
you at [Apple Developer Connection](http://developer.apple.com/) and it's
generally wise to have the latest version intended for your OS version.  OS X
Leopard can use up to Xcode 3.1 versions, which are the last ones to run
natively on PowerPC and the first to support compiling for iPhoneOS (yes,
pre-iPad!)

Xcode 3.2 is still able to compile PowerPC binaries, however like the OS X
Snow Leopard it runs on, you'll need an Intel processor to use it.

Older versions of OS X are not officially supported at this time, but if you
are more technically inclined, you might be able to make it work.  If you get
it to work, please send us a patch!  Obviously any version of Xcode predating
10.4.6 will not support Intel processors.

You will need to install git if you haven't already done so.

## git

On recent versions of OS X, you may already have git installed by Apple.  To
check, open up a terminal and type the command (without quotes) "``which
git``".  If you get another shell prompt without any output, you definitely
need to install git.  If you see a UNIX path name to git, then you're probably
good to go.  ``/usr/bin/git`` is the version supplied by Apple.  If it lives
somewhere else it was either compiled by hand or installed by source ports
system.  If you don't have it, a source ports system is a good way to get it.
Here's a few choices:

 * [MacPorts](http://www.macports.org/)
 * [HomeBrew](http://brew.sh/)
 * [Fink](http://www.finkproject.org/)

Of these, Fink tends to be the heaviest and HomeBrew the lightest.

One common criticism of HomeBrew is that using it tends to suggest downloading
ruby scripts right off the Internet and running them sight-unseen, with admin
access to your system.  If that sounds unwise, HomeBrew isn't for you.  That
said, think about the last commercial program you installed on your Mac.  Did
you look at its source code before verifying it was safe to run after you
downloaded it off the Internet?

MacPorts is somewhere in the middle, depending on how good you are at cleaning
up old "inactive" versions of things (use ``port -cu upgrade outdated`` when
you upgrade to keep things tidy.)  Your author uses MacPorts for all but a
couple of rare items not packaged by that port system.  That and check a
port's variants before installing it to make sure it has the features you
want, and disables the ones you don't.

Fink tends to follow the Debian model, which means lots of libraries needed
for optional features, just in case.  That's disk space used on a release
version, and lots of time compiling all of those libs if you are running a
pre-release.

Or you could just go and find git's website, download it, and follow the
instructions.  A basic Mac with Xcode installed probably meets all necessary
requirements.

<!-- FIXME: Too much handholding here? -->


# Using libretro-super

TODO: Works the same as libretro-super for Linux or under MSYS2 from here.
Document what that means exactly, later.

<!-- vim: set tw=78 ft=markdown: -->