Skip to content

Commit 679a8b9

Browse files
freakboy3742freakboy3742
authored
Bump support packages and update logging. (#122)
1 parent 0389593 commit 679a8b9

3 files changed

Lines changed: 74 additions & 102 deletions

File tree

‎README.md‎

Lines changed: 61 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,61 @@
1-
# Briefcase macOS Xcode Template
2-
3-
A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for
4-
building Python apps that will run under macOS.
5-
6-
## Using this template
7-
8-
The easiest way to use this project is to not use it at all - at least, not
9-
directly. [Briefcase](https://github.com/beeware/briefcase/) is a tool that
10-
uses this template, rolling it out using data extracted from a
11-
`pyproject.toml` configuration file.
12-
13-
However, if you *do* want use this template directly...
14-
15-
1. Install [cookiecutter](https://github.com/cookiecutter/cookiecutter).
16-
This is a tool used to bootstrap complex project templates:
17-
18-
```text
19-
pip install cookiecutter
20-
```
21-
22-
2. Run `cookiecutter` on the template:
23-
24-
```text
25-
cookiecutter https://github.com/beeware/briefcase-macOS-Xcode-template
26-
```
27-
28-
This will ask you for a number of details of your application, including the
29-
`name` of your application (which should be a valid PyPI identifier), and
30-
the `Formal Name` of your application (the full name you use to describe
31-
your app). The remainder of these instructions will assume a `name` of
32-
`my-project`, and a formal name of `My Project`.
33-
34-
3. [Obtain a Python Apple support package for macOS](https://github.com/beeware/Python-Apple-support),
35-
and extract it into the `My Project/Support` directory generated by the template.
36-
37-
4. Add your code to the template, into the `My Project/My Project/app`.
38-
directory. At the very minimum, you need to have an
39-
`app/<app name>/__main__.py` file that will be run on startup.
40-
41-
If your code has any dependencies, they should be installed into the
42-
`My Project/My Project/app_packages` directory.
43-
44-
If you've done this correctly, a project with a formal name of `My Project`,
45-
with an app name of `my-project` should have a directory structure that
46-
looks something like:
47-
48-
```text
49-
My Project/
50-
My Project/
51-
app/
52-
my_project/
53-
__init__.py
54-
app.py
55-
app_packages/
56-
...
57-
...
58-
My Project.xcodeproj/
59-
...
60-
Support/
61-
...
62-
VERSIONS
63-
briefcase.toml
64-
```
65-
66-
You're now ready to open the XCode project file, build and run your project!
67-
68-
## Next steps
69-
70-
Of course, running Python code isn't very interesting by itself - you'll be
71-
able to output to the console, and see that output in XCode, but if you tap the
72-
app icon on your phone, you won't see anything - because there isn't a visible
73-
console on an iPhone.
74-
75-
To do something interesting, you'll need to work with the native macOS system
76-
libraries to draw widgets and respond to screen taps. The
77-
[Rubicon](https://github.com/beeware/rubicon-objc) Objective
78-
C bridging library can be used to interface with the macOS system libraries.
79-
Alternatively, you could use a cross-platform widget toolkit that supports macOS
80-
(such as [Toga](https://beeware.org/project/projects/libraries/toga))
81-
to provide a GUI for your application.
82-
83-
Regardless of whether you use Toga, or you write an application natively, the
84-
template project will try to start a Python module matching the name of the
85-
`MainModule` property in the `Info.plist` file associated with the project.
86-
If that module can't be started, any error raised will be logged, and the
87-
Python interpreter will be shut down. All console output and errors are
88-
automatically redirected to the macOS system console.
89-
90-
If you have any external library dependencies (like Toga, or anything other
91-
third-party library), you should install the library code into the
92-
`app_packages` directory. This directory is the same as a `site_packages`
93-
directory on a desktop Python install.
1+
# Briefcase macOS Xcode Template
2+
3+
A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for building Python apps that will run under macOS.
4+
5+
## Using this template
6+
7+
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.
8+
9+
However, if you *do* want use this template directly...
10+
11+
1. Install [cookiecutter](https://github.com/cookiecutter/cookiecutter). This is a tool used to bootstrap complex project templates:
12+
13+
```text
14+
pip install cookiecutter
15+
```
16+
17+
2. Run `cookiecutter` on the template:
18+
19+
```text
20+
cookiecutter https://github.com/beeware/briefcase-macOS-Xcode-template
21+
```
22+
23+
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`.
24+
25+
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.
26+
27+
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.
28+
29+
If your code has any dependencies, they should be installed into the `Xcode/My Project/app_packages` directory.
30+
31+
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:
32+
33+
```text
34+
Xcode/
35+
My Project/
36+
app/
37+
my_project/
38+
__init__.py
39+
app.py
40+
app_packages/
41+
...
42+
...
43+
My Project.xcodeproj/
44+
...
45+
Support/
46+
...
47+
VERSIONS
48+
briefcase.toml
49+
```
50+
51+
You're now ready to open the XCode project file, build and run your project!
52+
53+
## Next steps
54+
55+
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.
56+
57+
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.
58+
59+
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.
60+
61+
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.

‎{{ cookiecutter.format }}/briefcase.toml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ entitlements_path = "{{ cookiecutter.class_name }}/{{ cookiecutter.app_name }}.e
1111

1212
support_path = "Support"
1313
{{ {
14-
"3.10": "support_revision = 13",
15-
"3.11": "support_revision = 8",
16-
"3.12": "support_revision = 8",
17-
"3.13": "support_revision = 13",
18-
"3.14": "support_revision = 9",
14+
"3.10": "support_revision = 14",
15+
"3.11": "support_revision = 9",
16+
"3.12": "support_revision = 9",
17+
"3.13": "support_revision = 14",
18+
"3.14": "support_revision = 10",
1919
}.get(cookiecutter.python_version|py_tag, "") }}
2020
cleanup_paths = [
2121
"Support/Python.xcframework/**/python*/config-*-darwin",

‎{{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ int main(int argc, char *argv[]) {
7979
config.write_bytecode = 0;
8080
// Isolated apps need to set the full PYTHONPATH manually.
8181
config.module_search_paths_set = 1;
82+
{% if cookiecutter.python_version|minor_version >= 14 and not cookiecutter.console_app -%}
83+
// Enable the use of the system logger
84+
config.use_system_logger = 1;
85+
{% endif -%}
8286
// Enable verbose logging for debug purposes
8387
// config.verbose = 1;
8488

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

190194
@try {
191-
// Set up an stdout/stderr handling that is required
192-
setup_stdout(mainBundle);
193-
194-
195195
// Adding the app_packages as site directory.
196196
//
197197
// This adds app_packages to sys.path and executes any .pth
@@ -232,6 +232,10 @@ int main(int argc, char *argv[]) {
232232
exit(-15);
233233
}
234234

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

236240
// Start the app module.
237241
//

0 commit comments

Comments
 (0)