Packaging for MacOS

[Trilarion]

The goal is to have an easy-to-use package that installs or updates the game and its dependencies (mainly python and python packages) and makes starting the game easy. Additionally we need to automatize the package creation.

What are the available options? What are the pros and cons of them? How would one need to do for them?

Dependent issues:

• [] #12

[krs013]

Based on my experience and a little research last night, I see three options that could work for our use case:

1. App Bundles macOS apps are distributed as packages, which are directories that behave like files for normal users. The directories contain all of the code and resources required to run the program, so the user simply drags the package into their Applications folder and it's installed. Double-clicking the package launches the program. Building the bundle is a matter of organizing the code and resources (this would include a copy of Qt and a Python interpreter, along with the libraries used) and adding a few meta-data files. The result could be downloaded as a zip file or disk image and no further installation is required. Automation isn't hard--I think it would just be a build script of some sort that assembles the package and then the result can be hosted on GitHub or elsewhere.

   • Pros:
     • Simplest distribution
     • Most familiar for Mac users
     • Does not require any installation
   • Cons:
     • Organization is particular to macOS
     • Unless an app is "signed" by someone with Apple's $100/yr developer account, it will display a warning before allowing a user to run it (just the first time--it's pretty common to bypass it)
   • See also:
     • Distributing Apps outside the App Store
     • Bundle Structures
     • Blog post about Gatekeeper and being at Apple's mercy

2. Homebrew Tap Homebrew is a third-party package manager used by some Mac users that gives access to programs and utilities not included with macOS. It is an alternative to (and usually considered exclusive with) Macports, and I think fink is another but I don't hear much about it anymore. Homebrew packages are "recipes" written in Ruby that download and install software all needed dependencies. Users can connect to external repositories called "taps" that are maintained outside of the core repository (usually they are just GitHub repos) and install software from those as well, and it integrates with the existing dependency structure.

   • Pros:
     • Dependencies are installed separately (smaller download)
     • Updating is best among the three options (automatic + dependencies)
   • Cons:
     • Again, this solution only works for Mac (but is probably a bit less work than option 1)
     • Only available to users who have installed or will install Homebrew, some will not want to if they already have Macports or similar
     • While Homebrew does (or did?) have the ability to create an App in the Applications folder (icon, double-click, etc.), that feature has been deprecated because of problems with the search function
   • See also:
     • Formula cookbook
     • How to create and maintain a tap

3. Do it all within Python Currently, all requirements for this project can be satisfied with pip, so a user with Python3 could install everything with by invoking pip. The package would have to be uploaded to the Python Packaging Index each time there was an update, which would make it available for pip to download.

   • Pros:
     • Cross-platform as long as our dependencies stay within Python
     • Maybe less work than the first two options, especially if works for all target distributions
   • Cons:
     • Does require Python3 to be installed (does not come with macOS), and non-developer users will probably opt for the binary installer which can lead to problems
     • If a user installed Python3 with the binary installer, installation may require admin privileges (and files end up in weird places) unless they use a virtual environment
     • Updating might be hard, or at least might require a reinstall each time (pip is not good with updates)
     • I don't know if it will result in an App that can be used cleanly by a novice user
     • Installation is a command-line affair requiring pip and hopefully venv. This shouldn't be too hard to automate in a shell script, though.
   • See also:
     • Python documentation on distribution
     • Python documentation on how to install packages with pip
     • How to package your Python code (legacy?)

[krs013]

My opinion on this is that Option 1 would be the best experience in the end (no external tools, no command line), Option 2 is the best as long as the game is under development (updating is easy), but Option 3 would be the most straightforward solution in that it's cross-platform and not as complicated as the other two.

[Trilarion]

Thanks for the overview. The game is alread on the Python package index (https://pypi.python.org/pypi/imperialism-remake), however not the latest version. The aim would rather be something more automatic like your option 1.

Your option 1 corresponds to a dmg file, right? How would updating/installing a different version work with these?

In general I think that the average user should get an automatic binary package, that works right out of the box (for both, Windows and Mac). The PyPi version is plattform independent and for the somewhat savy user who has Python already installed, and the Github source code repository is for developers.

[krs013]

Correct, most of the time the app bundles are packaged on a .dmg image file, but it's not necessary.

I'm not sure if it's possible to update from within the program. The solution I think I see the most (even with professional software) is to download a completely fresh copy of the updated version and move it into the Applications folder. Since the apps have the same name, the user is prompted to overwrite the old one, and that's it. Saves and configuration files are usually kept in a different location (e.g., ~/Library/Application Support/imperialism_remake) so that data is not lost when the app is updated.

[krs013]

It appears that py2app creates an app bundle out of a Python program, as py2exe does for Windows.

[Trilarion]

Okay, that an app bundle (including Python and the required modules) seems to have everything we want. A task would then to try to create an app bundle (see #12).