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

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-Xcode-template
   

   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. Obtain a Python Apple support package for macOS, and extract it into the My Project/Support directory generated by the template.

4. Add your code to the template, into the My Project/My Project/app. directory. At the very minimum, you need to have an app/<app name>/__main__.py file that will be run on startup.

   If your code has any dependencies, they should be installed into the My Project/My Project/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/
            my_project/
                __init__.py
                app.py
        app_packages/
            ...
        ...
    My Project.xcodeproj/
        ...
    Support/
        ...
        VERSIONS
    briefcase.toml

You're now ready to open the XCode project file, build and run your project!

Of course, running Python code isn't very interesting by itself - you'll be able to output to the console, and see that output in XCode, but if you tap the app icon on your phone, you won't see anything - because there isn't a visible console on an iPhone.

To do something interesting, you'll need to work with the native macOS system libraries to draw widgets and respond to screen taps. 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.

Regardless of whether you use Toga, or you write an application natively, the template project will try to start a Python module matching the name of the MainModule property in the Info.plist file associated with the project. If that module can't be started, any error raised will be logged, and the Python interpreter will be shut down. All console output and errors are automatically redirected to the macOS system console.

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.