Provenance EMU
  • Welcome
  • Frequently Asked Questions
  • Installation & Usage
    • Installing Provenance
      • Sideloading
      • Building from Source
      • Updating
    • BIOS Requirements
    • ROMs
      • Importing ROMs
      • Formatting ROMs
      • Customizing ROMs
      • Modding ROMs
  • Info
    • Supported Systems
    • Controllers & Controls
      • Controllers
        • Controller Reviews
      • Controls
    • Game Saves
    • Miscellaneous
      • Restoring Files
      • Launch ROMs via URL
      • Virtualizing macOS
  • Help
    • Troubleshooting
    • Contributing
    • Discord
  • Development
    • GitHub
    • Release Roadmap
Powered by GitBook
On this page
  • Get Source
  • Clone
  • Build Source
  • Advanced Features
  • 💢 Troubleshooting
  • xcrun: error: unable to find utility "xcodebuild", not a developer tool or in PATH
  • Unable to code-sign / install…
  • Can't install after changing fork / pulling…
  • Cycle in dependencies between targets… error
  • Stuttering sound or lag
  • —application-identifier entitlement does not match…
  • Your maximum App ID limit has been reached…
  • something something …Mupen build error
  • Unsupported arch
  • Duplicate app
  • Linking… Failed
  • git@github.com: Permission denied (publickey)…
  • conflicting provisioning settings…Distribution
  • ⚠️ Known Issues

Was this helpful?

  1. Installation & Usage
  2. Installing Provenance

Building from Source

Moderate: Install latest in-development build.

PreviousSideloadingNextUpdating

Last updated 1 year ago

Was this helpful?

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. (install requirements and dependencies)

  2. to device (Xcode)

  3. (Optional)

The beta is in active-development.

DO NOT expect to use a beta without issues, losing your saves, or bugs.

Requirements

  • macOS 12

    • on a Mac, Hackintosh or virtual machine ()

  • 13.3+

  • iOS 11+ a/o tvOS 10+ SDKs

  • Free account (at a minimum) or a paid account.

🛑 DO NOT enroll to join the full Developer Program or you will be locked into a Pending payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.

  • Connections:

    • iPhone / iPad: Lightning → USB-A / USB-C cable¹

    • Apple TV 4: USB-C → USB-A / USB-C cable¹

    • Apple TV 4K: WiFi² ()³

¹ Depends on which you have. WiFi can be setup after. ² USB ports have been discontinued on Apple TV 4K+. ³ If using a virtual machine, you may need to .

Get Source

Source Options

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

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

  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

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. Launch Tower and Add Your Service Account: GitHub

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

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

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

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

    • ☑️ Initialize Submodules

Download

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

If building from active develop branch, we will not be held responsible for any loss of your game data! Install at your own risk! …and back up your files.

Build Source

  1. ⚠️ 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 +

🛑 DO NOT enroll to join the full Developer Program or you will be locked into a Pending payment state, unable to code-sign unless you pay or contact Apple to cancel the enrollment.

Copy CodeSigning.xcconfig.sample to CodeSigning.xcconfig and modify the file replacing DEVELOPMENT_TEAM with your Team ID and ORG_IDENTIFIER with a bundle identifier that is registered to you.

If you have a paid Apple Developer account, you can find your Team ID at https://developer.apple.com/account/#/membership

If you have a free Apple Developer account, you need to generate a new signing certificate. To do so, follow the steps in [iOS App Signer][3] to create a new Xcode project and generate a provisioning profile. After saving the project, open project.pbxproj inside your newly created .xcproj and look for DEVELOPMENT_TEAM. Copy this value to CodeSigning.xcconfig and your unique identifier to ORG_IDENTIFIER.

Set DEVELOPER_ACCOUNT_PAID = YES if you used a paid Apple Developer account in order to automatically request the increased memory limit entitlement from Apple.

After updating CodeSigning.xcconfig, re-open the project (remember to use Provenance.xcworkspace when opening the project).

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

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

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

  • If you are…

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

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

Free Apple developer provisioning expires every 7 days, requiring reloading, but you will not lose any data.

Paid Apple Developer provisioning may only require re-signing once a year.

Advanced Features

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

    • iOS:

      • Provenance:

          • 🔲 group.provenance-emu.provenance

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

      • Spotlight:

          • 🔘Specify custom containers:

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

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

    • tvOS:

      • ProvenanceTV:

          • 🔲 group.provenance-emu.provenance

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

      • TopShelf:

          • 🔲 group.provenance-emu.provenance

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

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

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

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

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

💢 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:

    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…

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

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… Failed

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

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

git@github.com: Permission denied (publickey)…

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

     [url "https://github.com"]
     insteadOf = ssh://git@github.com

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.

⚠️ Known Issues

something about database build error

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

💢 If you get stuck, check out .

🔃 using…

Continue to …

Purchase/Download

Continue to …

Open the Provenance Xcode workspace: Provenance.xcworkspace

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 and do no more than agree to the terms.

App Groups

iCloud

Multipath

Push Notifications

Siri

Paid Apple Developer: Continue to

💢 If you get stuck, check out .

Requires a paid account.

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

App Groups

iCloud

Multipath

Push Notifications

Siri

App Groups

iCloud

App Groups

iCloud

Push Notifications

App Groups

1) Upgrade to a paid account.

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, delete the app and try to clean-install.

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

Setup an , or…

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 .

🗯 If you are still stuck try it yourself or ask for on our Discord.

Tower
appleid.apple.com
Apple Developer
Apple Developer
Apple Developer
Apple Developer
backup your files
SSH Key on your GitHub account
Restoring Files
debugging
help
Troubleshooting
Clone
Setup
Setup
Enable Advanced Features…
Troubleshooting
Get Source
Virtualizing macOS
Xcode
Apple Developer
Instructions
ports
Get Source
Setup
Build Source
Enable Advanced Features
Terminal
Tower
configure your network settings