Skip to content

Mac Knowledge Bytes

Jump to bottom
Parallax Git Administrator edited this page Mar 24, 2020 · 21 revisions

Mac Requirements and Tips

A collection of Mac-specific details, history, and tips.

macOS Version Differences

Mac OS X Mavericks through macOS High Sierra (10.9 - 10.13)

  • Includes Apple's attempt to directly support FTDI USB chipsets through Apple's kernel extension (kext)
    • first at /System/Library/Extensions/IOUSBFamily.kext/Contents/PlugIns/AppleUSBFTDI.kext
    • later at /System/Library/Extensions/AppleUSBFTDI.kext (Mac OS X 10.11 "El Capitan")
  • Introduced a new required destination for third-party driver installation destination
    • from /System/Library/Extensions/
    • to /Library/Extensions/ (FTDI's driver must go here)
  • Apple's FTDI driver (AppleUSBFTDI.kext)
    • Didn't support all features Parallax needs (namely, DTR support was missing or inadequate)
    • Caused system conflicts on some computers when FTDI's driver was installed (occasional Kernel Panics)
      • The occurrence of this grew very rare as time when on (later versions after Mavericks seemed to solve it)
    • Sometimes needed manual administrative help to prevent problems; see KEXT Admin Tips

macOS Mojave (10.14)

  • Apple introduced app hardened runtime, entitlements, notarization, and stapling.
    • These are optional features in Mojave and required in Catalina.
  • FTDI drivers are still required (v2.4.2)

macOS Catalina and beyond (10.15+)

  • Apple enforced app hardened runtime, entitlements, and notarization.
  • Apple introduced system extensions (dext) and deprecated kernel extensions (kext) for third-party use.
    • Accordingly, Apple's built-in FTDI support changed from kext to dext
      • Stored here /System/Library/DriverExtensions/DriverKit.AppleUSBFTDI.dext
      • Works great (on hosts, not on VMs for an unknown reason)

System Extensions

https://developer.apple.com/documentation/systemextensions

KEXT Admin Tips

Manually disable Apple's kext driver: sudo kextunload -b com.apple.driver.AppleUSBFTDI

Manually enable FTDI's kext driver: sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver

Verify FTDI's driver is running:

  • Plug in FTDI-based device
  • kextstat | grep FTDI
    • If all is well, it will report a line of information with the FTDI driver (not the Apple driver) listed in reverse-domain form (com.FTDI.driver.FTDIUSBSerialDriver).
    • If something's wrong, it won't report anything, or it will report the Apple driver instead (com.apple.driver.AppleUSBFTDI).

FTDI Driver (Mac)

  • Do not use v2.3 (suffers a "surprise removal" bug)
  • Use v2.4.2 only on macOS 10.12 "Sierra" through macOS 10.14 "Mojave"
  • Do not use any FTDI driver on macOS 10.15 "Catalina" (or later); it's not needed as Mac's included driver works
  • FTDI's v2.4.2 driver (re-signed and re-released 2019-12-24) will not install in Catalina (or Mojave?) due to Apple discontinuing their kext-signing permission on their Developer ID. FTDI is begging Apple to reissue their Developer ID with the kext-signing permission. Meanwhile, Parallax still maintains the formerly-signed v2.4.2 that still installs on Mojave and runs properly.

NW.js Wrapped Apps on Catalina

  • This NWJS Issue details the struggle others are experiencing. It was instrumental in getting the NWJS-wrapped BlocklyProp Launcher notarized and runnable on Catalina.
  • Gatekeeper on Catalina prevents apps from running unless they are developer-signed and Apple-notarized.
  • NWJS's app bundle contains many libraries and helper applications (bundles), all of which need to be signed (by either the NWJS team or by Parallax) in order for Apple issue a successful notarization.
  • Apps need to be signed with the hardened runtime attribute as well as with app-specific special permissions (called entitlements) in order to run properly (as a hardened runtime) and have access to resources they need.
    • NWJS seems to require the com.apple.security.cs.allow-unsigned-executable-memory entitlement be set to true in order for it to read it's bundle-embedded app (in its /Resources/app.nw/ folder). Without this entitlement, the OS starts NWJS and fails silently (only showing an NWJS menu but no application window).

Code Signing In Depth

See article about Apple's macOS Code Signing In Depth

Random Knowledge Bytes (Needs Organizing)

  • Using Finder's Duplicate feature (on an NWJS bundle) makes a copy of the NWJS-wrapped app but keeps symbolic links to the original nodes. Later, if the original is moved to trash, the duplicate's symbolic links now point to the trash.
    • The same behavior may be true of Finder's Copy feature - this seemed to be the behavior witnessed.
    • A potential solution is to use the command-line copy; however, developers have noted the same problems.
      • It appears that modern versions of macOS support cp -a which maintains symbolic links

Entitlements File

At the time of this writing, the entitlements below (see "..." values) are required to get the BlocklyProp Launcher to fully run (after install) on macOS 10.15.3 "Catalina." This is from the neededToRun.entitlements file in the repo and is used by the codesign app (called by the "mac_sign..." script).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.automation.apple-events</key>
	<true/>
	<key>com.apple.security.device.audio-input</key>
	<true/>
	<key>com.apple.security.device.camera</key>
	<true/>
	<key>com.apple.security.personal-information.addressbook</key>
	<true/>
	<key>com.apple.security.personal-information.calendars</key>
	<true/>
        <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
        <true/>
</dict>
</plist>

Terminal History

cd ../dist/BlocklyPropLauncher.app/Contents/Frameworks/nwjs\ Framework.framework/Versions/Current/Libraries

codesign -s "Developer ID Application" --deep -f -v --options runtime --timestamp --entitlements "../../../../../../../../package/mac-resources/neededToRun.entitlements" "libEGL.dylib"

codesign -s "Developer ID Application" --deep -f -v --options runtime --timestamp --entitlements "../../../../../../../../package/mac-resources/neededToRun.entitlements" "libGLESv2.dylib"

codesign -s "Developer ID Application" --deep -f -v --options runtime --timestamp --entitlements "../../../../../../../../package/mac-resources/neededToRun.entitlements" "libswiftshader_libEGL.dylib"

codesign -s "Developer ID Application" --deep -f -v --options runtime --timestamp --entitlements "../../../../../../../../package/mac-resources/neededToRun.entitlements" "libswiftshader_libGLESv2.dylib"

cd ../dist/BlocklyPropLauncher.app/Contents/Frameworks/nwjs\ Framework.framework

codesign -s "Developer ID Application" --deep -f -v --options runtime --timestamp --entitlements "../../../../../package/mac-resources/neededToRun.entitlements" "nwjs Framework"

codesign -vvvv --deep --strict nwjs\ Framework

cd ../../../../../  

cd package

./mac_app_sign_and_package.sh -a "BlocklyPropLauncher" -v 0.11.1 -d

xcrun altool --notarize-app --primary-bundle-id "BlocklyPropLauncher" --username "jmartin@parallax.com" --file "../dist/BlocklyPropLauncher-0.11.1-setup-MacOS.pkg"

xcrun altool -u "jmartin@parallax.com" --notarization-info d5aedf84-ea23-4e19-a035-c925bed389dd

xcrun stapler staple -v ../dist/BlocklyPropLauncher-0.11.1-setup-MacOS.pkg

Future Apple Requirements

  • It's been said that Apple will eventually require both hardened runtime and sandboxing in macOS apps. These are two different things- read more.

Clone this wiki locally