Briefcase macOS App Template

A Cookiecutter template for building Python apps that will run under macOS.

This repository branch contains a template for Python 3.8. Other Python versions are available by cloning other branches of repository.

Using this template

The easiest way to use this project is to not use it at all - at least, not directly. Briefcase is a tool that uses this template, rolling it out using data extracted from a pyproject.toml configuration file.

However, if you do want use this template directly...

1. Install cookiecutter. This is a tool used to bootstrap complex project templates:

   $ pip install cookiecutter
   

2. Run cookiecutter on the template:

   $ cookiecutter https://github.com/beeware/briefcase-macOS-app-template --checkout 3.8
   

   This will ask you for a number of details of your application, including the name of your application (which should be a valid PyPI identifier), and the Formal Name of your application (the full name you use to describe your app). The remainder of these instructions will assume a name of my-project, and a formal name of My Project.

3. Download the Python Apple support package for macOS, and extract it into the My Project/My Project.app/Contents/Resources directory generated by the template. This will give you a My Project/My Project.app/Contents/Resources/Support directory containing a self-contained Python install.

   Alternatively, you can download the Python-Apple-support project, and build your own version.

4. Add your code to the template, into the My Project/My Project.app/Contents/Resources/app directory. At the very minimum, you need to have an app/<app name>/__main__.py file that defines an entry point that will start your application.

   If your code has any dependencies, they should be installed into the My Project/My Project.app/Contents/Resources/app_packages directory.

If you've done this correctly, a project with a formal name of My Project, with an app name of my-project should have a directory structure that looks something like:

My Project/
    My Project.app/
        Contents/
            MacOS/
                My Project
            Resources/
                app/
                    README
                    my_project/
                        __init__.py
                        __main__.py
                app_packages/
                    README
                    ...
                Support/
                    ...
                my-project.icns
            Info.plist
    Entitlements.plist
    briefcase.toml

The My Project.app directory should identify as an macOS application that can be started by clicking on the application icon in Finder. It can also be distributed as a standalone package.

Next steps

Of course, running Python code isn't very interesting by itself - you won't be able to do any console input or output, because a macOS app doesn't display a console.

To do something interesting, you'll need to work with the native macOS system libraries to draw widgets and respond to user input. The Rubicon Objective C bridging library can be used to interface with the macOS system libraries. Alternatively, you could use a cross-platform widget toolkit that supports macOS (such as Toga) to provide a GUI for your application.

If you have any external library dependencies (like Toga, or anything other third-party library), you should install the library code into the app_packages directory. This directory is the same as a site_packages directory on a desktop Python install.

Debugging

If, when you run your application, you get an error of:

LSOpenURLsWithRole() failed with error -10810 for the file /Users/.../My Project.app.

then your application is crashing during startup. This might indicate a problem with the Briefcase template; however, it's more likely a problem with your code - probably a syntax error, or a missing dependency.

To get more helpful debugging information, you can run the application directly from the command line. Although it presents as a single icon in Finder, internally a macOS application is a folder with a specific structure, and an entry point matching the name of the application. We can use this entry point to manually start the application directly from the command line.

If your application is called My Project, you can start the application by running:

$ My\ Project/My\ Project.app/Contents/MacOS/My\ Project

This starts the application the same way as Finder, but outputs any Python errors to the console.

If the problem is a syntax error, you can fix your code.

If it's a dependency problem, ensure that any required dependencies have been installed into the Contents/Resources/app_packages directory.

If it's a problem with the execution environment, you can modify the entry point script. My\ Project/My\ Project.app/Contents/MacOS/My\ Project is a simple Bash script that starts the python interpreter after setting some environment variables. If necessary, you can modify this script.