Creating installers - cogstat/cogstat GitHub Wiki

Building the Windows installer

Ingredients

This is not a virtual environment-based solution yet. Python installation should be fresh and no other Python components should be available for that Python installation (e.g., Roaming folder).

• Python
  • Download Python
    • https://www.python.org/downloads/windows/
    • As of CogStat 2.1 use Python 3.8 (minimal version for CogStat 2.1 is Python 3.6)
    • Use the 64 bit version. As of CS 2.1, pyreader runs only on the 64 bit version. Otherwise the 32 bit version could have been fine.
  • Install Python
    • Check "Add Python to environment variables"
• R (new in v2.5)
  • 64 bit R
  • base distribution, and packages listed in setup.py
• CogStat
  • Copy CogStat source
• Install required Python modules
  • pip install -r path_to_cogstat_source\requirements.txt
• InnoSetup
  • https://jrsoftware.org/isinfo.php
  • If some CogStat languages are not included in the default language set of InnoSetup (C:\Program Files (x86)\Inno Setup 6\Languages), you can download additional languages from here: https://www.jrsoftware.org/files/istrans/ and copy them to C:\Program Files (x86)\Inno Setup 6\Languages\ folder

Tests

• Test if CogStat can be run from source:
  • python path_to_cogStat_source\run_cogstat_gui.py
• Run automatic tests:
  • python path_to_cogStat_source\validate_calculations.py

Installer

• Make installer
  • Open .iss with InnoSetup
  • If needed, modify .iss, and add modifications to github
  • Build > Compile
• Test installer
  • Install CogStat and run it

Building the Mac Installer

Prerequisites for compiling

1. Open Terminal and install Xcode command line tools (see code below) or install full Xcode from the App Store. xcode-select --install

2. Install universal2 python from python’s website (not conda or brew). This will make sure you have both an x86_64 and arm64 version (as we can't compile a universal2 app only Intel due to pyqt5 just yet, but this might change, and if you run an M1/M2... mac, you'll likely only have the arm64 version).

3. Install qt@5 with brew brew install qt@5

4. Install requirements through this python’s pip3. Make sure configobj and chardet packages are also installed through pip3 and are added to setup-mac.py if they’re not present. Also, add p2app. pip3 install -r requirements.txt

Compiling with py2app

5. Since pyqt5 still cannot be compiled as universal2 (fat) binary, create an Intel-only app with py2app. arch -x86_64 /usr/local/bin/python3 setup-mac.py py2app --arch x86_64 -C

   5+1: Check the compiled app for broken symlinks. You can create a text file containing symlinks. Make sure you look for links that point outside the app (should not be the case if py2app made a self-contained app) or ones that point nowhere. ls -lR dist/CogStat.app/Contents | grep '^l' > cogstatsymlinks.txt In 2.4beta release we found site.pyo pointing nowhere, this had to be deleted. While broken symlinks are not a security concern to Apple when they notarise the app, the Gatekeeper will still flag your perfectly notarized and stapled app as broken if you have any.

Prerequisites for code signing

6. Make sure you have a paid Apple Developer account and you have a Developer ID Application type certificate private key in your Keychain.

7. Then check if you have notarytool xcrun --find notarytool

8. Check if you have valid identities security find-identity -p basic -v

9. Create an app-specific password for you Apple account which will be used for store credentials. Note down the app password.

10. Prepare store credentials. The ABCD123456 signifies the unique code of your apple dev id in parentheses You’ll be asked to create a profile name for the keychain notary profile. Here we use: cogstat-sign-devidapp Then you’ll need to provide the app-specific password you created. xcrun notarytool store-credentials --apple-id "[email protected]" --team-id "ABCD123456"

11. Now go and adjust codesign bash sh file and provide a valid identity in the IDENTITY= section.

12. Sign the app and verify bash codesign-cogstat-intel-python3_11.sh

    If the last 2 output lines are these, you’re fine. Otherwise, debug and adjust the .sh file.

    dist/CogStat.app: valid on disk
    dist/CogStat.app: statisfies its Designated Requirement
    

Code signing and Apple notarization

13. Prepare for the App to be notarised by Apple

    A. If you’ll distribute the app packaged as zip (for dmg, you’ll have to prepare dmg first, and you’ll upload that to Apple, but as of 2023, we’re going with zip) /usr/bin/ditto -c -k -rsrc --sequesterRsrc --keepParent dist/CogStat.app dist/zipped/CogStat.zip

    B. If you want to distribute a dmg: Prepare a dmg file whichever way you like (we used brew formula create-dmg): (You have to pack the SIGNED app you created) create-dmg --background "cogstat_dmg.png" --volname "CogStat" --volicon cogstat/resources/cogstat.icns --window-pos 200 120 --window-size 500 500 --icon "CogStat.app" 150 250 --app-drop-link 350 250 "CogStat-2_4beta.dmg" dist/Cogstat.app Then you have to sign and timestamp the dmg as well with the same Developer ID Application. codesign -s "Developer ID Application: Your Name (ABCD123456)" --timestamp -i com.cogstat.org.cogstat /Users/robert/cogstat/CogStat-2_4beta.dmg

14. Notarise the app (either zip or dmg) with Apple and the notary profile you created earlier. With --wait, the terminal will keep reconnecting to check the status. xcrun notarytool submit dist/zipped/CogStat.zip --keychain-profile "cogstat-sign-devidapp" --verbose --progress --wait

15. Wait. The zip or dmg will be uploaded to Apple and now wait patiently for minutes or a few hours… If you closed the Terminal or didn’t put the --wait command, you can still check the status like this: xcrun notarytool history --keychain-profile "cogstat-sign-devidapp" If it returns with error, checking error log based on error log number, and good luck for you… % xcrun notarytool log 1aba2345-asdfa-3535-96dc-43ntskdngadsf --keychain-profile "cogstat-sign-devdiapp" ~/Desktop/notarization_log.json

16. Stapling: If there are no errors and Apple notarises the app, you must staple the notarisation to your package if you have .pkg or .dmg and you’ll have to distribute this stapled version, which will tell MacOSes of whoever installs the app that this is not a security concern and should be run normally. If successful, this is what you’ll see:

    Info [API] Submission in terminal status: Accepted
    Processing complete
      id: d829f3b1-96e8-4049-81c9-[…]
      status: Accepted
    

    Now, if you submitted .zip, you cannot staple the zip itself. You’ll have to staple the SIGNED app you zipped up in the previous step. If they try to run an app you distributed in a zip file and the mac has internet connection, it will check with apple for this notarisation. If all is well, gatekeeper won’t throw a security fit, it will simply ask, are you sure you want to run something you downloaded from the internet. However, if it doesn’t have an internet connection, it will have security issues. If this is a concern, prepare, notarise and staple a dmg instead.

    A. Stapling the app (for the zip route): xcrun stapler staple dist/Cogstat.app

    The result should be: “The staple and validate action worked!”

    B. Stapling the signed and timestamped dmg (if you uploaded a dmg): xcrun stapler staple CogStat-2_4beta.dmg

17. Check. Validate if all worked well by uploading the file to the internet to a temporary file hosting site, and re-download. Then run: spctl -a -t open --context context:primary-signature -v ~/Downloads/CogStat-2_4beta.dmg It should work as expected if you get: accepted source=Notarized Developer ID