Build and Package: Mac

These steps need to be performed on a pre-configured development system every time a new installation package is desired. Most steps (and their substeps) are frequent, unless marked "[rare]."

The following steps were created from multiple sessions of performing the process. There are also a number of Mac Knowledge Bytes some of these steps were created from; they are not required reading, but may contain some useful "gems" of information.

Mac Packaging

• Checkout the desired BlocklyProp Launcher version
  • Open a command window
  • Check out the needed branch from the BlocklyPropLauncher repository
    • in Git command line:
      • $ cd /Users/{username}/{folder}/BlocklyProp_Launcher
      • $ git checkout origin {branch}
  • NOTE: The source can be run from here- no build process needed; however, follow extra steps below to package for Mac
• [rare] Download/Update nw.js release (if needed); this is a rarely-needed step as normally you can reuse the existing version on the developer computer from previous sessions
  • Rename existing .dist/BlocklyPropLauncher.app to preserve it in case of error below
  • Download stable release (not -rcx, -alphax, or -betax) from http://dl.nwjs.io/
  • Extract the downloaded archive
  • Find extracted subfolder and locate nwjs.app within it
  • Move nwjs.app bundle to the ./dist subfolder
  • Switch to ./dist subfolder (for next few operations): cd ./dist
  • Rename the nwjs.app bundle to BlocklyPropLauncher.app: mv nwjs.app BlocklyPropLauncher.app
  • Dequarantine the entire app bundle (else gatekeeper may refuse to let it run locally)
    • Dequarantine recursively with: xattr -d -r com.apple.quarantine BlocklyPropLauncher.app
  • Add permissions to read and execute for groups and other users on entire app bundle (else bundle will not run once installed)
    • NOTE: Default permissions on new nwjs bundle are rwx for owner and --- on executable, library, and some subfolders for group and other users, which makes it non-functional for all but owner once the installer places it in the Applications folder
    • Amend permissions recursively with: sudo chmod -R g+r+x,o+r+x BlocklyPropLauncher.app/*
  • Touch-up BlocklyPropLauncher.app
    • Copy the ./package/mac-resources/BlocklyProp.icns file (we'll use it soon)
      • NOTE: The icon should appear in Finder for the BlocklyProp.icns file; if it does not, it's because the repository has changed it somehow and you'll need to instead copy the file from the old BlocklyPropLauncher.app/Contents/Resources bundle
    • On BlocklyPropLauncher.app, right-click > Show Package Contents
      • Then navigate to Contents/Resources subfolder
      • Move the app.icns file to trash
      • Paste the BlocklyProp.icns file in its place
    • Navigate to the Contents subfolder
    • Open BlocklyPropLauncher app bundle's Info.plist file with XCode
    • Set the "Bundle display name" value to "BlocklyProp Launcher" (including quotes; that's important)
    • Note that the "Executable file" should already be nwjs
    • Set the "Icon file" value to BlocklyProp.icns
    • Set the "Bundle versions string, short" value to the proper Major, Minor, and Release number of the BlocklyProp Launcher app
    • All the rest can stay as-is. Save the file and quit XCode.
  • NOTE: The app bundle's icon may not appear properly in Finder right away. It will resolve itself when the app bundle is signed in later steps, below.
• Make Release
  • Run the build script from within the repository directory:
    • $ ./MakeRelease
      • This builds and stores the application files in the ./release subfolder
• Copy release to app bundle
  • Copy the contents of the ./release folder (the contents, not the folder) into the BlocklyPropLauncher app bundle's Contents/Resources/app.nw subfolder (create the folder if new nwjs app release was downloaded and touched up (from steps above)
    • This can be achieved in Finder by...
      • navigating to the ./dist subfolder,
      • finding the BlocklyPropLauncher app,
      • right-click > Show Package Contents,
      • then navigate to Contents/Resources/app.nw subfolder and paste
• Touch up BlocklyPropLauncher app product version (NOTE: This step is already done if a new nwjs app release was downloaded and touched up; from steps above)
  • Open BlocklyPropLauncher app bundle's Contents/Info.plist file with XCode and set the "Bundle versions string, short" value to the proper Major, Minor, and Release number of the BlocklyProp Launcher app
    • NOTE: At the time of this writing, the mac_app_sign_and_package script below says it's setting the version, but it fails to actually do so
• Sign and Package BlocklyProp Launcher
  • $ cd ./package
  • $ ./mac_app_sign_and_package.sh -a "BlocklyPropLauncher" -v #.#.# -d ;where #.#.# is the proper application version number
  • (OPTIONAL) $ ./mac_app_verify_signatures.sh -a "BlocklyPropLauncher"
  • Notarize BlocklyProp Launcher package; so Mac Gatekeeper (on macOS Catalina (10.15) and above) allows proper execution
    • $ ./mac_app_notarize.sh -a "BlocklyPropLauncher" -v #.#.# -d {apple_developer_email_address} ;where #.#.# is the proper application version number
      • NOTES:
        1. Use the App Notarization password (from the Apple Developer account in our password database)
        2. After entering password, the CLI will appear frozen for a couple minutes; it's okay, it's uploading the package to Apple's notary service
        3. If no errors are reported, wait for notarization email (which may be a few minutes)
           • It comes to the Apple Developer account email
        4. When the email arrives, if it reports success, this means Apple has reviewed the app and give it their stamp of approval (called a notarization ticket) signifying that it does not contain any known malicious software. Their servers communicate the approval information to any macOS Gatekeepers that question it; however, the app needs to have the notarization ticket attached to it; the next step.
    • If notarization arrives and was successful, staple the notarization ticket to the app...
      • $ ./mac_app_staple.sh -a "BlocklyPropLauncher" -v #.#.# ;where #.#.# is the proper application version number
        • NOTE: It may complain near the end of the response output that "We do not know how to deal with trailer version..." but this issue doesn't seem to be fatal as it later reports "The staple and validate action worked!"
  • Rename installer
    • $ package % mv ../dist/BlocklyPropLauncher-#.#.#-setup-MacOS.pkg ../dist/Setup-BPLauncher-#.#.#-MacOS.pkg