Installing on macOS

From BurnSim Wiki
Jump to navigation Jump to search

BurnSim 4 runs natively on macOS, on both Apple Silicon and Intel Macs. It is distributed as a zipped BurnSim.app bundle from the download page.

macOS needs one Terminal command before BurnSim will open. This is required, not optional, and it is a one-time step per version you install. This page explains the step, why macOS demands it, and what each of the possible error messages means.

Which build to download

Your Mac Download
Apple Silicon (M1, M2, M3, M4 - any Mac from 2020 onward) the macos-arm64 build
Intel the macos-x64 build

Not sure which you have? Click the Apple menu > About This Mac. If the Chip line says "Apple M-something" you are on Apple Silicon; if it says Processor and names an Intel chip, you are on Intel.

The Intel build does run on Apple Silicon through Rosetta 2, but there is no reason to choose it there - the arm64 build is native and faster.

Installing

  1. Download the zip for your Mac and unzip it (double-clicking the zip in Finder is enough).
  2. Drag BurnSim.app to your Applications folder.
  3. Open Terminal - it is in Applications > Utilities, or press Command-Space, type Terminal and press Return.
  4. Type this command and press Return: 
    xattr -cr /Applications/BurnSim.app
    If you put BurnSim.app somewhere other than Applications, type xattr -cr with a trailing space and then drag BurnSim.app from Finder onto the Terminal window - that fills in the correct path for you. The command prints nothing when it works.
  5. Double-click BurnSim.app. It launches, and keeps launching normally from then on.

If you skip straight to step 5, macOS reports the app as damaged. That is the error this step prevents - see below.

Why the extra step is needed

Anything macOS downloads from the web is tagged with a quarantine flag. When you first open a quarantined application, Gatekeeper assesses its code signature, and it will only clear an app that is signed with a paid Apple Developer ID and notarized by Apple. BurnSim's bundle is signed, but with an ad-hoc signature rather than an Apple-issued Developer ID, so that assessment fails.

When Gatekeeper rejects a quarantined application this way, macOS does not say the signature was not recognized. It reports:

"BurnSim is damaged and can't be opened. You should move it to the Trash."

and offers only Move to Trash and Cancel. This wording is misleading: the download is not corrupt and not damaged, and you should not move it to the Trash. It is also important to know that there is no "Open Anyway" button for this case. The System Settings > Privacy & Security route works for apps that carry a real Developer ID signature but have not been notarized; it does not appear for an ad-hoc signed app.

xattr -cr removes the quarantine flag ("-c" clears extended attributes, "-r" applies it through the whole bundle). With no quarantine flag, there is no Gatekeeper assessment to fail, and macOS launches the app. This is the same step that most independently distributed Mac software requires.

Notarizing BurnSim would remove the need for this entirely, and is the proper fix. It requires paid Apple Developer Program membership.

Error messages and what they mean

The three failure messages look similar and mean completely different things, so it is worth matching the exact wording.

Message Cause Fix
"BurnSim is damaged and can't be opened. You should move it to the Trash." The quarantine flag is set and BurnSim is not notarized. The usual case on a fresh download. xattr -cr /Applications/BurnSim.app, as above. Do not move it to the Trash.
"BurnSim can't be opened because Apple cannot check it for malicious software", or "the developer cannot be verified" Quarantine again, but with a signature macOS recognizes well enough to offer a way through. Either the same xattr -cr command, or System Settings > Privacy & Security, scroll to Security, and click Open Anyway.
"The application cannot be opened" - a bare message naming no developer and not mentioning Apple checking it The executable permission did not survive unzipping. Some third-party unzip tools drop it. 
chmod +x /Applications/BurnSim.app/Contents/MacOS/BurnSim
Then open it again. Unzipping with Finder rather than a third-party tool avoids this.

On macOS 15 (Sequoia) and later, the old right-click > Open trick no longer works for any of these. Where an override is possible at all it is now Open Anyway in System Settings.

Where BurnSim keeps your files

Settings, the propellant database, activity logs and license data are stored under: 

~/Library/Application Support/BurnSim/

That folder is left alone when you replace BurnSim.app with a newer version, so your propellants and settings survive an upgrade. To uninstall BurnSim completely, drag BurnSim.app to the Trash and delete that folder.

Reporting a problem

Activity logging is on by default (Settings > Log Activity for Bug Reports). If something goes wrong, send the newest file from 

~/Library/Application Support/BurnSim/logs/

together with a description of what you were doing, to burnsim@burnsim.com. The Mac builds are much newer than the Windows ones and have had far less real-world use, so reports are genuinely useful - please include your macOS version and whether your Mac is Apple Silicon or Intel.

See also

Retrieved from "https://wiki.burnsim.com/index.php?title=Installing_on_macOS&oldid=302"