Skip to content

Bump support packages and update logging. #122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mhsmith merged 1 commit into from
Jun 13, 2026
+74 −102
Merged

Bump support packages and update logging. #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 61 additions & 93 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,93 +1,61 @@
# Briefcase macOS Xcode 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:

```text
pip install cookiecutter
```

2. Run `cookiecutter` on the template:

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

```text
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!

## Next steps

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](https://github.com/beeware/rubicon-objc) 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](https://beeware.org/project/projects/libraries/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.
# Briefcase macOS Xcode 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:

```text
pip install cookiecutter
```

2. Run `cookiecutter` on the template:

```text
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](https://github.com/beeware/Python-Apple-support), and extract it into the `Xcode/Support` directory generated by the template.

4. Add your code to the template, into the `Xcode/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 `Xcode/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:

```text
Xcode/
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!

## Next steps

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](https://github.com/beeware/rubicon-objc) 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](https://beeware.org/project/projects/libraries/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.
10 changes: 5 additions & 5 deletions {{ cookiecutter.format }}/briefcase.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ entitlements_path = "{{ cookiecutter.class_name }}/{{ cookiecutter.app_name }}.e

support_path = "Support"
{{ {
"3.10": "support_revision = 13",
"3.11": "support_revision = 8",
"3.12": "support_revision = 8",
"3.13": "support_revision = 13",
"3.14": "support_revision = 9",
"3.10": "support_revision = 14",
"3.11": "support_revision = 9",
"3.12": "support_revision = 9",
"3.13": "support_revision = 14",
"3.14": "support_revision = 10",
}.get(cookiecutter.python_version|py_tag, "") }}
cleanup_paths = [
"Support/Python.xcframework/**/python*/config-*-darwin",
Expand Down
12 changes: 8 additions & 4 deletions {{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@ int main(int argc, char *argv[]) {
config.write_bytecode = 0;
// Isolated apps need to set the full PYTHONPATH manually.
config.module_search_paths_set = 1;
{% if cookiecutter.python_version|minor_version >= 14 and not cookiecutter.console_app -%}
// Enable the use of the system logger
config.use_system_logger = 1;
{% endif -%}
// Enable verbose logging for debug purposes
// config.verbose = 1;

Expand Down Expand Up @@ -188,10 +192,6 @@ int main(int argc, char *argv[]) {
}

@try {
// Set up an stdout/stderr handling that is required
setup_stdout(mainBundle);


// Adding the app_packages as site directory.
//
// This adds app_packages to sys.path and executes any .pth
Expand Down Expand Up @@ -232,6 +232,10 @@ int main(int argc, char *argv[]) {
exit(-15);
}

{# if cookiecutter.python_version|minor_version < 14 and not cookiecutter.console_app -#}
// Set up any stdout/stderr handling that is required
setup_stdout(mainBundle);
{# endif -#}

// Start the app module.
//
Expand Down
Loading