Installing Provenance

Joe Mattiello edited this page Nov 15, 2018 · 239 revisions

To install Provenance or update your existing installation follow the official guides below.

💢  If you get stuck, check out Troubleshooting.
⚠️  Please refer to the Known Issues regarding Installation, and read Issues Usage before posting a new one.


There are two approved methods to install Provenance: The easiest—or novice—method is to side-load an official prebuilt .ipa file to your device(s), however this is only available for stable releases. The more advanced method (and only official way to install the current beta) is to build from source directly to your device(s).

Installation Options:

🚫  Side-loading from 3rd party sources is not supported.
♿️  Requires free Apple Developer account, but code-signing provisioning expires every 7 days.
       …You will have to re-sign/re-build.

Advanced Features:

🛂  Requires paid Apple Developer account


Prebuilt .ipa releases are available via Releases and must be re-signed using your own developer profile(s) using a tool such as Cydia Impactor.

  1. Download a Release of Provenance.
  2. Download and launch Cydia Impactor.
  3. Connect your device (you may need to launch iTunes and choose Trust… when it pops up).
  4. Select your device in Impactor.
  5. Drag & drop .ipa file onto Impactor.
  6. Enter your Apple ID.
  7. If not using 2-Factor Authentication, enter your account password, otherwise…
    1. (If you haven't yet), login to your Apple ID online and Generate an App-Specific Password, under Security section (and write it down somewhere for later use). appleid-2factor-generate
    2. Enter your App-Specific Password in Cydia Impactor, verbatim.
  8. On device: Go to SettingsGeneralProfiles & Device Management, tap on your certificate and then Trust
  9. Done. (If using a free developer account, repeat from Step 5 after it expires in 7 days)

♿️  Free Apple Developer account is still required at a minimum.
🚫  Side-loading from 3rd party sources is not supported.
💢  If you get stuck, check out Troubleshooting.


To get the very latest in-development beta, 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.

⚠️  The beta is in active-development.
🛑  DO NOT use the beta in place of a release and expect to use it without issues, losing your saves, or experiencing bugs.
🏍  Alternatively, you can install a beta "sidecar" for testing alongside a previous install at the same time, using a different bundle ID than your previous install.

Build from Source:

  1. Get Source
  2. Install Requirements
  3. Install Dependencies
  4. Build Source to device (Xcode)
  5. (Optional) Enable Advanced Features


  • macOS 10.13.6+
  • Xcode 10+
  • iOS 10+ a/o tvOS 10+ SDKs
  • Free Apple Developer Account (at a minimum)
  • Connections:
    • iPhone / iPad:   LightningUSB-A / USB-C cable¹
    • Apple TV 4:      USB-CUSB-A / USB-C cable¹
    • Apple TV 4K:    WiFi² (Instructions)

¹ Depends on which ports you have.
² USB ports have been discontinued on Apple TV 4K+, and will have to be paired to Xcode over WiFi.
💢  If you get stuck, check out Troubleshooting.

Get Source

⚠️ Setup a GitHub SSH Key Recomended

Provenance uses SSH submodules to clone dependencies. By default cloning uses SSH for performance. It's recommended to setup GitHub with an SSH key, especially if your Carthage steps are stalling.

Follow GitHub's guide.

Alternative you can force Git to use HTTPS instead of SSH.

For only

git config --global url."".insteadOf

For ALL git repos. Not Recommended

git config --global url."https://".insteadOf git://

Source Options


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.


The Terminal app can be found in: /Applications/Utilities


  1. Make sure you have the latest version of the Xcode command line tools installed:
    xcode-select --install
  1. (Optional) Choose an install directory with cd [path]
    (alternatively, you can drag & drop a folder on Terminal after cd if don't know how to get the directory path)
  2. Download source with either...
    • SSH: git clone
    • HTTPS: git clone

SSH is the method we prefer, and sub-modules repos are set to SSH. GitHub recommends HTTPS if behind a firewall or other cases. Read about the differences here. You can force HTTPS if you're having issues with SSH clones. Instructions

  1. Navigate to the directory with cd Provenance
  2. Install Submodules with git submodule update --init --recursive
  3. Continue…


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 TowerPrefences (or use ⌘, shortcut):
    • Set a 'default directory for clone repositories' such as ~Documents/GitHub
  4. In Menubar: Select FileClone Git Repository (or use ⌃⌘C shortcut):
    • Remote URL:
    • ☑︎ Initialize Submodules
  5. Continue…


🚫 Due to the inclusion of submodules this method no longer works…

  ⚠️  If building from a dev (beta or feature) branch, we will not be held responsible for any loss of your game data!
  Install dev branches at your own risk! …and back up your files.

Install Requirements New

The steps of Installing Requirements and Building are now integrated into a Makefile

First time setup
make setup
make open

Then setup the project for codesigning by following steps in Building...

Get updates and build

If you've already done the First time setup, then you can build from the command line using the following commands These commands will pull any updates and build, so you can opt to update and build using only the terminal in the future.

make ios

or for Apple TV

make tvos

You can get a list of all commands by running,

make help

Install Requirements Old

Using Terminal¹ install the following requirements. If already installed, skip to Install Dependencies.

  1. Install Homebrew (if you don't have it) with:
    /usr/bin/ruby -e "$(curl -fsSL"
  2. Install Carthage via Homebrew with: brew install carthage
  3. Install Fastlane via Homebrew with: brew cask install fastlane
  4. (Optional/Recommended) Install rbenv via Homebrew:
    1. brew install rbenv
    2. rbenv init and follow instructions
    3. Verify installation: rbenv install --list
  5. (Optional/Recommended) Install/Upgrade latest Ruby 2.X via rbenv: rbenv install 2.5.1
  6. Activate rbenv Ruby: rbenv global 2.5.1
  7. (If needed) Add the following to your bash file via nano ~/.bash_profile (save with Write Out ^O):
    export PATH="$HOME/.fastlane/bin:$PATH"
    eval "$(rbenv init -)"
  8. Close and re-open Terminal, Install bundle via gem: gem install bundle
  9. Continue…

¹ The Terminal app can be found in: /Applications/Utilities

Install Dependencies

Using Terminal¹ install the following dependencies.

  1. Navigate to the 'Provenance' directory with: cd [path]
    (alternatively, you can drag & drop a folder on Terminal after cd if don't know how to get the directory path)
  2. Install gems: bundle install
  3. Bootstrap (select one):
    • bundle exec fastlane carthage_bootstrap - ALL or…
    • bundle exec fastlane carthage_bootstrap_ios - iOS only
    • bundle exec fastlane carthage_bootstrap_tvos - tvOS only
  4. Continue…

¹ The Terminal app can be found in: /Applications/Utilities
💢  If you get stuck, check out Troubleshooting.

Build Source

  1. Open the Provenance Xcode workspace: xcode-workspace-21x17 Provenance.xcworkspace
    ⚠️  Do not use the .xcodeproj file or you will have build errors!

  2. Go to Preferences via Menubar: XcodePreferences 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
      ⚠️ At minimum, sign up as a free Apple Developer and do nothing more than agree to the terms.
      🛑 DO NOT enroll to join the Developer Program or you will be locked into a Pending payment state.
      You will be unable to code-sign with this account unless you pay or contact Apple to cancel the enrollment.
  3. In Project Settings, edit all of the targets for your device:
    • iOS
      • Provenance
      • Spotlight
    • tvOS
      • ProvenanceTV
      • TopShelf
    1. 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.
      🏍  To install "sidecar" or alongside a previous install, intentionally use another/different Bundle ID.

    2. Turn on ☑️Automatically manage signing and select your Development Team for your targets.


    3. If using a free Apple Developer account, Turn OFF App Groups (and potentially iCloud) in Capabilities for your targets.
  4. Select a -Release profile from the Scheme Menu and connect your device(s) and select in the Destination Menu:


  5. If you have…
  6. Provenance will compile and run on your device. Hit ◼︎ (Stop). Done.

💢  If you get stuck, check out Troubleshooting.

Advanced Features

Enable TopShelf/Spotlight/iCloud

⚠️ Requires a paid Apple Developer account.

  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 +.

  2. Enable App Groups and iCloud on the target(s), specify your provenance App Group ID and disable group.provenance-emu.provenance &…

    • iCloud (iOS)
      • Provenance Project → Provenance → Capabilities → iCloud
      • Provenance Project → Spotlight → Capabilities → iCloud
    • Spotlight (iOS)
      • Provenance Project → Provenance → Capabilities → App Groups
      • Provenance Project → Spotlight → Capabilities → App Groups
    • TopShelf (tvOS)
      • Provenance Project → Provenance TV → Capabilities → App Groups
      • Provenance Project → TopShelf → Capabilities → App Groups
  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


When there is a new release or recent commits to a source branch you have two options for updating. You can side-load a release over your existing side-loaded installation or you can pull the local source and build over your existing built-from-source installation.

Update Options


Update with Terminal¹

  1. Navigate to the 'Provenance' directory with: cd [path]
    (alternatively, you can drag & drop a folder on Terminal after cd if don't know how to get the directory path)
  2. Update latest source (Options):
    • Overwrite Changes: If you haven't yet made any changes to source files or don't mind overwriting them and reapplying your Bundle IDs, App Groups from the original installation:
      git pull origin develop
    • Stash Changes: If want to reapply your changes to source files (especially any PRs you are working on or simply your Bundle IDs App Groups), you will need to stash and re-apply them with:
      git stash
      git reset --hard HEAD
      git pull origin develop
      git stash pop
  3. Update Homebrew Installations:
    brew update
    brew upgrade
  4. Update submodules: git submodule update --init --recursive
  5. Return to Xcode and…
    • Return to Build: Step 3 to reapply your settings, else…
    • If stashed changes above, just hit the ▶︎ (Run) button.
  6. Provenance will compile and run on your device. Unless testing, Hit ◼︎ (Stop). Done.

¹ The Terminal app can be found in: /Applications/Utilities

Update with Tower

  1. In Repositories double-click Provenance or select and click Open
  2. With 'develop' branch marked (HEAD), click Fetch
  3. If develop branch shows a number next to it, click Pull
  4. Click Stash Changes
  5. After changes are pulled, click Apply Stash, select stash and click Apply Stash
  6. Return to Xcode: Hit the ▶︎ (Run) button.
  7. Provenance will compile and run on your device. Hit ◼︎ (Stop). Done.

To learn more about stashing refer to Tower's Using the Stash documentation.

⁉️  If all else fails, delete the Provenance folder and start over.

💢  Troubleshooting:

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

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.

Side-loading cannot authenticate

  • If using 2-Factor Authentication, you will need to go to Apple ID settings and make a key and save it for use in Cydia Impactor, type it verbatim.

—application-identifier entitlement does not match…

  • This means you need to match the Bundle IDs with the ones from your previous side-load 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 and Clean Build Folder and rebuild.

bundler: failed to load command fastlane… error

  • Carthage might have a dirty cache, clean with rm -rf ~/Library/Caches/org.carthage.CarthageKit 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 ""]
    insteadOf = ssh://

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 iPhone Developer, and try building again.

⚠️  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.
    Alternatively, you can change your Bundle ID to install "sidecar" or alongside the previous app at the same time.

🗯 If you are still stuck ask for help on our Discord.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.