How to compile OpenEmu for macOS

Table of Contents

How to compile OpenEmu for macOS

OpenEmu for macOS is a front-end to various retro game emulators. OpenEmu, as the name implies, is an open source project. The source code is available on GitHub.com for anyone who wishes to modify or contribute, if they so wish. We will in this guide show how to compile our own version of OpenEmu.

This can be useful if you want early access to features that have not yet made it into the official release.

Requirements

• macOS
• Xcode
• GitHub Desktop

Installation

OpenEmu comes in two flavours; the standard version and the experimental version. The latter supports Mame which can be interesting to those users who do not wish to install Mame outright on their system.

Let us first download the latest version of Xcode from the App Store, if you do not yet have it on your system.

While Xcode installs in the background, we will setup our GitHub.com environment which will enable us to download the source code for OpenEmu. The first thing that we need to do is to sign up for a free account on the following page.

https://github.com

The registration process is very simple and requires no further explanation, but it is requirement to have a GitHub account in order to be able to follow this tutorial. Proceed to the GitHub login page once your account has been created.

https://github.com/login

Generating SSH keys

Now onto the technical part. In order to access the OpenEmu repository we will need to generate and associate SSH keys with our GitHub account. However, before doing so we need to check if any existing SSH keys exist in our home directory. We can skip this step if the keys already exist.

Open a new Terminal.

Type the following command to confirm if any existing ssh keys are present.

$ ls -al ~/.ssh

-rw-r--r--   1 geek  staff    75 Dec 14 22:38 config
-rw-------   1 geek  staff  3434 Dec 14 21:34 id_rsa
-rw-r--r--   1 geek  staff   745 Dec 14 21:34 id_rsa.pub

If the above files exist you should be able to skip the next step and proceed directly to the section where SSH keys are added to your GitHub account.

However, if no files exist, as seen below, you will have to read on.

ls: /Users/geek/.ssh: No such file or directory

or

total 0
drwxr-xr-x   2 geek  staff   64 14 Dec 20:33 .
drwxr-xr-x+ 27 geek  staff  864 14 Dec 20:33 ..

We will now generate the SSH keys. Type in the following command and substitute the example email address, your_email@example.com, with the one associated with your GitHub account.

$ ssh-keygen -t rsa -b 4096 -C your_email@example.com

Generating public/private rsa key pair.

When prompted for a file in which to save the key, simply hit Enter to accept the default location.

Enter file in which to save the key (/Users/geek/.ssh/id_rsa): 

You may also enter a password for additional security.

Enter passphrase (empty for no passphrase): [type your password]

Enter same passphrase again: [type your password]

A summary will be shown once the password has been saved.

Your identification has been saved in /Users/geek/.ssh/id_rsa.

Your public key has been saved in /Users/geek/.ssh/id_rsa.pub.

The key fingerprint is:
SHA256:XXXXXXXXXXXX your_email@example.com

The key's randomart image is:
+---[RSA 4096]----+
|            xx   |
|           x  xx |
|          x x xXX|
|           x XXxx|
|      x x x X xx |
| x X X x   x xxXX|
|xX  x   x x x xxx|
|   x   x x   xxxx|
|    xxxxX x x   x|
+----[SHA256]-----+

Adding keys to the ssh-agent

We will now start the ssh-agent which is a program used to hold private keys for public key authentication.

$ eval "$(ssh-agent -s)"

Agent pid 2159

Once the ssh-agent is running in the background we can create (or modify) the ~/.ssh/config file to enable automatic loading of keys as well as storing passwords in the keychain.

Open the file ~/.ssh/config in your favourite text editor.

$ nano ~/.ssh/config

Add the following lines to the file.

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

Alternatively, we can append the text directly from within the Terminal by typing the following command.

echo "Host *" >> ~/.ssh/config
echo "  AddKeysToAgent yes" >> ~/.ssh/config
echo "  UseKeychain yes" >> ~/.ssh/config
echo "  IdentityFile ~/.ssh/id_rsa" >> ~/.ssh/config

We are now ready to add our SSH private key to the ssh-agent and to store the password in the keychain.

$ ssh-add -K ~/.ssh/id_rsa

If you opted to use an SSH password in the previous step you will need to enter it again here.

Enter passphrase for /Users/geek/.ssh/id_rsa: [type your password] 

You will receive a confirmation once the key has been added.

Identity added: /Users/geek/.ssh/id_rsa (your_email@example.com)

Adding the SSH key to our GitHub account

Let us return to GitHub.com’s website and select our profile picture in the upper-right corner of any page and click Settings.

On the Settings page, select SSH and GPG keys in the left-hand menu.

Press the green button labelled New SSH Key in the upper-right corner of the SSH and GPG keys page.

We are now ready to copy and paste the SSH key into the input box below.

From a Terminal, type the following command to copy the SSH key into the clipboard.

$ pbcopy < ~/.ssh/id_rsa.pub

Paste the content of your clipboard under Key and provide an identifiable name under Title.

Press Add SSH Key once you are done.

On the SSH and GPG keys page you should now see that the SSH key has been associated with your GitHub account.

Testing the SSH connection

Once the SSH key has been added we can test to see if the connection works correctly.

In a Terminal, type the following command:

$ ssh -T git@github.com

The authenticity of host 'github.com (xxx.xx.xxx.x)' can't be established.
RSA key fingerprint is SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.
Are you sure you want to continue connecting (yes/no)?

Type yes when prompted.

Upon successful connection you will see a message similar to the one below. Verify that your username and RSA key fingerprint matches the one you have stored on GitHub.

Warning: Permanently added 'github.com,xxx.xx.xxx.x' (RSA) to the list of known hosts.
Hi your_username! You've successfully authenticated, but GitHub does not provide shell access.

Your GitHub account and its credentials have now been setup.

Cloning the OpenEmu repository

We are now ready to clone the OpenEmu repository. Several methods exist, but we will in this example show how to do it with the GitHub Desktop application. You may ask why we can not clone the repository directly from within Xcode? The reason is because Xcode’s integrated Git UI does not support cloning of submodules (i.e. a recursive clone). Since OpenEmu consists of many submodules, the easier option is to just use GitHub Desktop which supports this out of the box.

Download the GitHub Desktop application from the following page.

https://desktop.github.com

Once downloaded, it is recommended that you drag and drop the GitHub Desktop icon into your Applications folder. Double-click on the icon to launch the application.

You will be presented by a welcome screen where you will be asked to sign in to your GitHub account. Click on the link labelled Sign in to GitHub.com.

Enter your GitHub.com login credentials and press Sign in.

You will be asked to provide a public username which will be used for identification when/if you decide to contribute to an open source project.

Decide if you wish to submit usage stats to the GitHub Desktop team and press Finish to complete the setup.

We are now ready to clone the OpenEmu repository. Either click on the button labelled Clone a Repository from the Internet… or choose File > Clone Repository from the system menu.

In the window that pops up, select the URL tab and type the following address under the Repository URL section.

https://github.com/OpenEmu/OpenEmu.git

Specify an empty folder under the Local Path section. (GitHub Desktop will not allow you to clone into folders that already contain files)

Press Clone to start the process.

Depending on the speed of your connection, cloning can take several minutes…

If you see the following authentication error message, your GitHub.com credentials have not been set up correctly. Please revisit the earlier sections to confirm that you have not missed any step.

If the clone is successful you will see the OpenEmu repository page. This page will periodically refresh to show any new commits that other users have made.

We will, however, not stay in GitHub Desktop but instead open the Finder window and browse to the folder where our OpenEmu repository is located.

Locate the file labelled OpenEmu.xcworkspace and double-click to open it in Xcode, which has hopefully finished downloading now. There is also another workspace file labelled OpenEmu-metal.xcworkspace which you are free to test. This one supports Metal hardware acceleration.

You might briefly see a Welcome screen before the project opens. A shortcut will also be saved in the right column which gives you easy access to the project the next time you open Xcode.

Once the project has loaded we will see a rather empty first page with many familiar emulator names in the left-hand column. We are currently interested in the Active scheme menu which is located to the right of the Stop button.

When we press the button a new menu will be shown where we will set the active scheme to OpenEmu > My Mac.

With the active scheme set we are ready to build the application.

In the top hand menu select Product > Build For > Profiling.

Depending on your machine specs, the compilation may take several minutes…

You might see various compiler warnings throughout the build. This is generally harmless, but if the build fails for unknown reason you might be unlucky to have checked out a branch that currently has some issues. The only thing that we can recommend is to sit tight, make sure that the software is up-to-date and try to revert to a previous commit where the code might have worked. Someone will eventually notice the problem and push an update to the OpenEmu repository.

You are obviously welcome to debug the code yourself as well, if you so wish :)

If the build is successful you will see the following notification.

Testing our OpenEmu build

With the GitHub setup and compilation out of the way, all that remains is to test our shiny new OpenEmu build. The binaries are for various reasons located in rather obscure folders which can be a bit difficult to find for those users who do not know where to look.

We will therefore open Xcode’s File > Workspace Settings which will give us a hint in the right direction.

In the Per-User Workspace Settings, above the Advanced button, we can see where the base directory is located. If we click the small arrow icon, next to the path, a new Finder window will open up.

In our case the base folder is: /Users/geek/Library/Developer/Xcode/DerivedData

The full path to OpenEmu is, however, unique because a hash number will be added to the file path. In our case the full path is:

/Users/geek/Library/Developer/Xcode/DerivedData/OpenEmu-fmwrbboecfjcqfdvnjwoyyoehdbd/Build/Products/Release/OpenEmu.app

Your path will be different but the example should at least give you a pointer where to find the file. For ease of use, let us move it into the Applications folder.

Double click the icon to launch OpenEmu.

Congratulations! Your freshly compiled OpenEmu application should now open.

Summary

This guide has shown the required steps how to compile our own version of OpenEmu. This can be useful if we want early access to features that have not yet made it into the official release.

Further information

For more information on how to compile OpenEmu, visit the official Wiki pages at: https://github.com/OpenEmu/OpenEmu/wiki

Happy compiling!