Package: Mac

These steps are for building and packaging using the 2023 nwjs wrapped method and are to be performed on a pre-configured development system.

---

The first steps (below) need to be performed only when an updated version of nwjs is needed. This is rarely-needed as normally you can reuse the existing version on the developer computer from previous sessions.

Update nwjs [rare]

• Download and touch-up desired nw.js release
  • Rename existing .dist/ParallaxIDE.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 ParallaxIDE.app: mv nwjs.app ParallaxIDE.app
  • Dequarantine the entire app bundle (else gatekeeper may refuse to let it run locally)
    • Dequarantine recursively with: xattr -d -r com.apple.quarantine ParallaxIDE.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 ParallaxIDE.app/*
  • Touch-up ParallaxIDE.app
    • Copy the ./package/mac-resources/ParallaxIDE.icns file (we'll use it soon)
      • NOTE: The icon should appear in Finder for the ParallaxIDE.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 ParallaxIDE.app/Contents/Resources bundle
    • On ParallaxIDE.app, right-click > Show Package Contents
      • Then navigate to Contents/Resources subfolder
      • Move the app.icns file to trash
      • Paste the ParallaxIDE.icns file in its place
    • Navigate to the Contents subfolder
    • Open ParallaxIDE app bundle's Info.plist file with XCode
    • Set the "Bundle display name" value to "Parallax IDE" (including quotes; that's important)
    • Note that the "Executable file" should already be nwjs
    • Set the "Icon file" value to ParallaxIDE.icns
      • The case must exactly match that of the file
    • Set the "Bundle versions string, short" value to the proper Major, Minor, and Release number of the Parallax IDE 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, as long as the case-sensitive name exactly matches the file.

---

These steps (below) need to be performed every time a new installation package is desired.

Mac Packaging (nwjs wrapped)

• Checkout the desired Parallax IDE version
  • Open a command window
  • Check out the needed branch from the Parallax-IDE repository
    • in Git command line:
      • $ cd /Users/{username}/{folder}/Parallax-IDE
      • $ git checkout origin {branch}
  • Set execute permissions on mac scripts (if necessary)
    • $ cd package
    • $ chmod 744 mac_app_*.sh
• Create ./release and ./dist/../app.nw subfolders if necessary
  • If ./release doesn't exist: $ mkdir release
  • If ./dist/ParallaxIDE.app/Contents/Resources/app.nw doesn't exist: $ mkdir dist/ParallaxIDE.app/Contents/Resources/app.nw
• Make Release
  • Run the build script from within the repository directory:
    • $ ./MakeReleaseMac
      • This builds and stores the application files in the /release subfolder and also into the /dist/ParallaxIDE.app/Contents/Resources/app.nw subfolder (see Note)
• Touch up Parallax IDE app product version (NOTE: This step is already done if a new nwjs app release was downloaded and touched up; from steps above)
  • Open Parallax IDE 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 Parallax IDE 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 Parallax IDE
  • $ cd ./package
  • $ ./mac_app_sign_and_package.sh -a "ParallaxIDE" -v #.#.# -d ;where #.#.# is the proper application version number
  • (OPTIONAL) $ ./mac_app_verify_signatures.sh -a "ParallaxIDE"
  • Notarize ParallaxIDE package; so Mac Gatekeeper (on macOS Catalina (10.15) and above) allows proper execution
    • $ ./mac_app_notarize.sh -a "ParallaxIDE" -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 "ParallaxIDE" -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/ParallaxIDE-#.#.#-setup-MacOS.pkg ../dist/Setup-Parallax-IDE-#.#.#-MacOS.pkg

Note: The Chrome App must be placed in raw release form (no zipping of folder) so that nwjs launches it with the same chrome.runtime.id each time, in order to not break the local storage api's ability to find the previous session's files. The issue of starting each time with a different chrome.runtime.id was discussed here, which relates to the domain setting, and also here, which relates to the package your app techniques, but only the latter solution seems to solve the problem in this case.