Skip to content

BUILD_MACOS.md

Latest commit

 

History

History
77 lines (47 loc) · 3.81 KB

BUILD_MACOS.md

File metadata and controls

77 lines (47 loc) · 3.81 KB

Building on macOS

This file documents how to build a macOS executable/app for GitRepositoryManager using the included build_macos.sh script.

Prerequisites

  • macOS machine with Python 3.x installed (python3 on PATH)
  • Xcode command line tools (for building native extensions when installing packages)
  • Git (used by the application at runtime)

Quick build steps

  1. Make the script executable (first time):

    chmod +x build_macos.sh

  2. Run the build script:

    ./build_macos.sh

What the script does

  • Creates (if needed) a virtual environment in .venv
  • Installs or upgrades pip, requirements.txt, and a pinned pyinstaller version
  • Runs pyinstaller in directory mode so app_data.json remains writable next to the app

Notes and tips

  • Directory mode (default) produces dist/GitRepositoryManager/ which contains the executable and bundled files.

  • You can enable a single-file build by uncommenting the --onefile line in build_macos.sh. Single-file builds are slower to start and make writing adjacent files harder.

  • To codesign the built app/binary use the codesign tool and, for distribution, follow Apple's notarization steps.

  • If you'd like the same options as the provided GitRepositoryManager.spec, you may build using that spec:

    pyinstaller GitRepositoryManager.spec

Security/Signing

  • For local testing ad-hoc signing is often sufficient:

    codesign --deep --force --verbose --sign - dist/GitRepositoryManager/GitRepositoryManager

  • For App Store or Gatekeeper compliance you must sign with a valid Apple Developer ID and notarize the build.

Creating a .pkg installer

  • The script will attempt to create a .pkg installer using pkgbuild (part of Xcode command line tools).
  • If pkgbuild is not available the script will skip this step and print a message.
  • Output: dist/GitRepositoryManager-1.0.pkg by default.

Customize package identifier and version

If you want to change the package identifier or version, edit the PKG_ID and PKG_VERSION variables in build_macos.sh before running the script. For production builds replace com.example.GitRepositoryManager with your reverse-domain identifier (e.g., com.yourcompany.GitRepositoryManager).

Notes on signing the installer

  • pkgbuild can embed signed .pkg files if you pass signed components; you typically sign the .app and then use productbuild to produce a signed installer with a developer certificate. For basic distribution, ad-hoc signing of the .app plus notarization is recommended.

Creating a DMG

  • The script will attempt to create a compressed .dmg containing the .app using hdiutil (macOS built-in tool).
  • Output: dist/GitRepositoryManager-1.0.dmg by default.
  • The DMG will include the .app and a symbolic link to /Applications so users can drag-and-drop to install.

If you want a more customized DMG (background image, positioning of icons), consider using a tool like create-dmg (npm) or dropdmg and customizing the staging folder before calling hdiutil.

Troubleshooting: PermissionError related to CodeResources

  • If PyInstaller (or the script) fails with a PermissionError mentioning CodeResources or similar when removing/building macOS bundles, it usually means some files in dist/ were created by a different user (or by root from a previous signed build).
  • The script now attempts to remove such artifacts safely and will try to fix ownership using sudo chown -R if required. If you still see permission errors, manually remove the offending files (for example dist/GitRepositoryManager.app/Contents/_CodeSignature/CodeResources) with sudo and re-run the script:
sudo rm -rf dist/GitRepositoryManager.app
sudo rm -rf dist/GitRepositoryManager-1.0.pkg
./build_macos.sh

Make sure you're running the script as a normal user; avoid creating build artifacts as root to prevent repeated permission issues.