https://github.com/beeware/briefcase-macos-app-template

A template for generating macOS app projects with Briefcase
https://github.com/beeware/briefcase-macos-app-template

Last synced: 11 months ago
JSON representation

A template for generating macOS app projects with Briefcase

• Host: GitHub
• URL: https://github.com/beeware/briefcase-macos-app-template
• Owner: beeware
• License: mit
• Created: 2019-10-20T03:34:45.000Z (over 6 years ago)
• Default Branch: main
• Last Pushed: 2025-07-19T11:21:38.000Z (11 months ago)
• Last Synced: 2025-07-19T16:11:58.130Z (11 months ago)
• Language: Python
• Homepage:
• Size: 170 MB
• Stars: 28
• Watchers: 7
• Forks: 19
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Briefcase macOS App Template

A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template

for building Python apps that will run under macOS.

## Using this template

The easiest way to use this project is to not use it at all - at least,

not directly. [Briefcase](https://github.com/beeware/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](https://github.com/cookiecutter/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

    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](https://github.com/beeware/Python-Apple-support), and extract

    it into the `My Project/My Project.app/Contents/Resources/Suppoort`

    directory generated by the template.

4.  Obtain a stub binary, and add it as a file named `My Project` in the

    `My Project/My Project.app/Contents/MacOS/` directory generated by

    the template. The [stub

    project](https://github.com/beeware/briefcase-macOS-Xcode-template/tree/main/stub)

    in the [Briefcase macOS Xcode

    template](https://github.com/beeware/briefcase-macOS-Xcode-template)

    generates two stub binaries - one for GUI apps, and one for console

    apps; copy the appropriate executable from that project into your

    app template.

5.  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//__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/

                        ...

                        VERSIONS

                    my-project.icns

                Info.plist

        installer/

            resources/

                welcome.html

            scripts/

                postinstall

            Distribution.xml

        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.

Before you can run the app, you will need to sign any binary files,

frameworks and embedded apps in the `My Project.app` folder, as well as

the `My Project.app` folder itself. The `Entitlements.plist` file should

be a good starting point for the entitlements required to sign the app.

## 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](https://github.com/beeware/rubicon-objc) 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](https://github.com/beeware/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.