To get the very latest in-development build, you will need to build from source with Xcode. There are no shortcuts. Provenance is a large project with required dependencies and submodules that help enable efficient development. Check that you meet the requirements. Follow each and every step. Make no assumptions. Do not skip anything.

1. ​Get Source​

2. ​Setup (install requirements and dependencies)

3. ​Build Source to device (Xcode)

4. (Optional) Enable Advanced Features​

💢 If you get stuck, check out Troubleshooting.

Get Source

Source Options

• 🔃 Clone using…

  • ​ Terminal​

  • ​ Tower​

Clone

Cloning is how you pull the source code from GitHub. The primary way to do this is using Terminal; However, if you're a developer or familiar with powerful git clients like Tower, this is also an option as long as you enable for initializing submodules.

Terminal

1. Make sure you have the latest version of the Xcode command-line tools installed: xcode-select --install

2. (Optional) Choose an install directory with cd [path] (drag & drop a folder on Terminal after cd to get directory path).

3. Download source with…

   • HTTPS: git clone --recurse-submodules -j4 https://github.com/Provenance-Emu/Provenance.git

4. Continue to Setup…

Tower

Tower is a powerful commercial git client that can automate a lot of the tasks you'd otherwise be using commandline for, such as stashing changes. It is however, not free.

1. Purchase/Download Tower​

2. Launch Tower and Add Your Service Account: GitHub

3. (Optional) In Menubar: Select Tower → Preferences (or use ⌘, shortcut):

   • Set a 'default directory for clone repositories' such as ~Documents/GitHub

4. In Menubar: Select File → Clone Git Repository (or use ⌃⌘C shortcut):

   • Remote URL: https://github.com/Provenance-Emu/Provenance.git

   • ☑️ Initialize Submodules

5. Continue to Setup…

Download

🚫 Due to the inclusion of submodules this method no longer works. Do not manually download source as .zip…

Setup

Using Terminal install the following requirements. If already set up, skip to Build Source.

Install Requirements

1. Install Homebrew (if you don't have it):

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Install RVM:

   \curl -sSL https://get.rvm.io | bash -s stable --ruby && source ~/.rvm/scripts/rvm

3. Install Carthage using Homebrew

   brew install carthage

4. Navigate to the 'Provenance' directory with: cd [path] (can drag & drop a folder on Terminal after cd to get directory path)

5. Install and build the relevant Submodules, Setup & Launch, using…

   ./carthage.sh bootstrap --platform iOS 
   ./carthage.sh bootstrap --platform tvOS

6. Continue to Build Source…​

💢 If you get stuck, check out Troubleshooting.

Build Source

1. Open the Provenance Xcode workspace: Provenance.xcworkspace

   ⚠️ Do not use the .xcodeproj file or you will have build errors!

   ​​

2. Go to Preferences via Menubar: Xcode → Preferences or use ⌘, shortcut.

   • Select Accounts tab.

   • Click +

   • Sign in with your personal or developer Apple ID. If you don't have one, click Create Apple ID or go to appleid.apple.com.

1. In Project Settings, edit all of the targets for your device:

   • iOS

     • Provenance

     • Spotlight

     • ProvenanceShared

     • ProvenanceSharedTests

   • tvOS

     • ProvenanceTV

     • TopShelf

     • ProvenanceShared-tvOS

   • Change the Bundle IDs for your target by replacing only provenance-emu with something unique to you (like your username), and use the same replacement for all of your targets and all subsequent updates.

• If using a free Apple Developer account, Turn OFF these Capabilities for all targets:

  • ​ App Groups

  • ​ iCloud

  • ​ Multipath

  • ​ Push Notifications

  • ​ Siri

• Turn ON ☑️Automatically manage signing and select your Development Team for your targets.

  ​​

• Select a -Release profile from the Scheme Menu and connect your device(s) and select in the Destination Menu:

  ​​

  ​​

• If you are…

  • Paid Apple Developer: Continue to Enable Advanced Features…​

  • Free Apple Developer: Hit the ▶︎ (Run) button.

• Provenance will compile and run on your device. Unless testing, hit ◼︎ (Stop). Done.

💢 If you get stuck, check out Troubleshooting.

Advanced Features

1. If you haven't made one previously, add a new App Group ID: group.[change-this].provenance to your Apple Developer portal, or continue to next step and see if it allows you to add an App Group ID automatically when using + in App Groups.

2. [Re-]enable Capabilities on your target(s), with the following settings:

   • iOS:

     • Provenance:

       • ​ App Groups

         • 🔲 group.provenance-emu.provenance

         • ☑️ group.[change-this].provenance

       • ​ iCloud

       • ​ Multipath

       • ​ Push Notifications

       • ​ Siri

     • Spotlight:

       • ​ App Groups

       • ​ iCloud

         • 🔘Specify custom containers:

           • 🔲 `iCloud.com.provenance-emu.provenance`

             ☑️ `iCloud.com.[change-this].provenance`

   • tvOS:

     • ProvenanceTV:

       • ​ App Groups

         • 🔲 group.provenance-emu.provenance

         • ☑️ group.[change-this].provenance

       • ​ iCloud

       • ​ Push Notifications

     • TopShelf:

       • ​ App Groups

         • 🔲 group.provenance-emu.provenance

         • ☑️ group.[change-this].provenance

   ​​

3. Define the value for PVAppGroupId in PVAppConstants.swift with your App Group ID.

   ​​

4. Hit the ▶︎ (Run) button to build to your device.

5. Provenance will compile and run on your device. Unless testing, hit ◼︎ (Stop). Done

💢 Troubleshooting

If you are having trouble building or sideloading the app, check for your issue here or below in Known Issues.

xcrun: error: unable to find utility "xcodebuild", not a developer tool or in PATH

• Go to Xcode Preferences>Locations, and make sure to select an Xcode version for Command Line Tools.

Unable to code-sign / install…

• Change the Bundle IDs of the app targets and extensions, as described in Build Source steps.

• If you are using a free Apple developer account, you can only install a total of 3 apps per Apple ID at a time. You must use delete some apps you are signing, or install with different Apple ID and Bundle IDs.

• If you used to have a free Safari Developer Account which is no longer supported by Apple, you have two options:

  1) Upgrade to a paid Apple Developer account.

  2) Use a different Apple ID that is not an expired and deprecated Safari Developer account.

Can't install after changing fork / pulling…

1. Check the Bundle IDs haven't been reset to the projects defaults.

2. If not, select your team drop down and reselect your team / name. Sometimes Xcode gets out of sync with the identity being used after a merge / pull / branch change, especially in the extension targets.

Cycle in dependencies between targets… error

• Circular dependency error. Clean Build Folder (⇧⌘K) and/or nuke Xcode's derived data: rm -rf ~/Library/Developer/Xcode/DerivedData and restart Xcode.

Stuttering sound or lag

• This probably means you built the debug version by mistake (app will be named Prov Debug on Home Screen and the version displayed in Settings will be DEBUG)… If so, Re-build using Provenance-Release (iOS) or ProvenanceTV-Release (tvOS) option in Xcode.

—application-identifier entitlement does not match…

• This means you need to match the Bundle IDs with the ones from your previous sideload or build on your device. If you don't know it, or used a 3rd party web-sign (unsupported), we recommend you backup your files, delete the app and try to clean-install.

Your maximum App ID limit has been reached…

• You have made too many Bundle IDs (App IDs) in one week on a free Apple developer account. Stop making new Bundle IDs and revert to one you already made. You are chasing the wrong problem. If all else fails, use a different Apple ID, and make only one new, unique Bundle ID with it (and save it for later when you need to re-sign in 7 days).

something something …Mupen build error

• You are missing submodules. Do not download .zip from GitHub. Use Terminal. Go back to Get Source and do not skip any steps.

Unsupported arch

• You are probably trying to build for a 32-bit device. Provenance only support 64bit devices at this time. as only mupen64plus requires 64-bit at this time, try this as a workaround: Remove the mupen64plus framework from the apps Embed and Link stages and from the Build → Targets list in the Edit Scheme… settings.

Duplicate app

• If app installs or updates as a duplicate app instead of updating existing installation, you need delete it and use the same Bundle ID as your original build or you'll end up with a double installation…

Linking…carthage/…Error: Permission denied @ dir_s_mkdir - /usr/local/Frameworks…

• Just a permissions error with the directory, it can be fixed with:

    sudo mkdir /usr/local/Frameworks
    sudo chown $(whoami):admin /usr/local/Frameworks
    brew link carthage

Linking… Failed

• Fails when switching from one target to another. Try…

  1. Delete Build folders in Provenance/Carthage/ and /Provenance/PVSupport/Carthage/

  2. In Xcode: Run Clean a/o Clean Build Folder and rebuild.

bundler: failed to load command… error

• Carthage might have a dirty cache, clean with rm -rf ~/Library/Caches/org.carthage.CarthageKit

[email protected]: Permission denied (publickey)…

• Setup an SSH Key on your GitHub account, or…

• Add the following to your bash file via nano ~/.gitconfig (save with Write Out ^O):

   [url "https://github.com"]
   insteadOf = ssh://[email protected]

conflicting provisioning settings…Distribution

• In Build Settings for the targets with errors, manually reset all the Code Signing Identities that are iOS Distribution to be iOS Developer, and try building again.

…can't find header files for ruby at …/…ruby.h

• Try reinstalling ruby via RVM in Setup instructions, or try…

  gem update --system

⚠️ Known Issues

something about database build error

• This means there have been changes to the database model which is no longer compatible with your previous build. In order to update you must clean install (delete app and re-install, not build or install over over existing app). If you would like to migrate your save games and states, you can refer to Restoring Files.

🏍 You can install a duplicate app for testing by using a different bundle ID than your previous/main install.

Issues with dependencies and building on Apple Silicon

Currently there's a couple of issues with dependencies and building for Apple Silicon machines, as documented here but there are a couple of workarounds which should work.

1) When bootstrapping you may receive build errors in building lipo, such as:

Building universal frameworks with common architectures is not possible. The device and simulator slices for "CocoaLumberjack" both build for: arm64
Rebuild with --use-xcframeworks to create an xcframework bundle instead.

If you see this error, you should be able to run the ./carthage.sh script under Rosetta2, IE:

arch -x86_64 ./carthage.sh bootstrap --platform iOS
arch -x86_64 ./carthage.sh bootstrap --platform tvOS

2) Depending on how you installed brew you may also run into an error in the final step of building, with an error message like:

/usr/local/bin/carthage: No such file or directory

This is because the install location for Apple Silicon brew binaries is /opt/homebrew/bin/carthage. You can work around this with with a symlink:

sudo ln -s /opt/homebrew/bin/carthage /usr/local/bin/carthage