# briefcase-macOS-app-template

**Repository Path**: thkiler/briefcase-macOS-app-template

## Basic Information

- **Project Name**: briefcase-macOS-app-template
- **Description**:  briefcase-macOS-app-template
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-08-23
- **Last Updated**: 2023-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## 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`_. 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`_, and extract it into
   the ``My Project/My Project.app/Contents/Resources/Suppoort`` directory
   generated by the template.

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/
                        ...
                        VERSIONS
                    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.

.. _cookiecutter: https://github.com/cookiecutter/cookiecutter
.. _Obtain a Python Apple support package for macOS: https://github.com/beeware/Python-Apple-support
.. _Rubicon: https://github.com/beeware/rubicon-objc
.. _Toga: https://beeware.org/project/projects/libraries/toga