Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
85 changes: 22 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,54 +1,32 @@
# Briefcase iOS Xcode Template

A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template
for building Python apps that will run under iOS.
A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for building Python apps that will run under iOS.

## 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.
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 to use this template directly...

1. Install
[cookiecutter](https://github.com/cookiecutter/cookiecutter). This
is a tool used to bootstrap complex project templates:
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-iOS-Xcode-template

This will ask you for a number of details of your application,
including the <span class="title-ref">name</span> of your
application (which should be a valid PyPI identifier), and the
<span class="title-ref">Formal Name</span> of your application (the
full name you use to describe your app). The remainder of these
instructions will assume a <span class="title-ref">name</span> of
`my-project`, and a formal name of `My Project`.

3. [Obtain a Python Apple support package for
iOS](https://github.com/beeware/Python-Apple-support), and extract
it into the `My Project` directory generated by the template. This
will give you a `My Project/Support` directory containing a self
contained Python install.

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 defines a `PythonAppDelegate`
class.

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/
This will ask you for a number of details of your application, including the <span class="title-ref">name</span> of your application (which should be a valid PyPI identifier), and the <span class="title-ref">Formal Name</span> of your application (the full name you use to describe your app). The remainder of these instructions will assume a <span class="title-ref">name</span> of `my-project`, and a formal name of `My Project`.

3. [Obtain a Python Apple support package for iOS](https://github.com/beeware/Python-Apple-support), and extract it into the `My Project` directory generated by the template. This will give you a `Xcode/Support` directory containing a self contained Python install.

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 defines a `PythonAppDelegate` class.

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:

Xcode/
my-project/
app/
my_project/
Expand All @@ -63,33 +41,14 @@ structure that looks something like:
...
briefcase.toml

You're now ready to open the XCode project file, build and run your
project!
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 iOS
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 iOS system libraries.
Alternatively, you could use a cross-platform widget toolkit that
supports iOS (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 instantiate a
`UIApplicationMain` instance, using a class named `PythonAppDelegate` as
the App delegate. If a class of that name can't be instantiated, the
error raised will be logged, and the Python interpreter will be shut
down.

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.
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 iOS 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 iOS system libraries. Alternatively, you could use a cross-platform widget toolkit that supports iOS (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 instantiate a `UIApplicationMain` instance, using a class named `PythonAppDelegate` as the App delegate. If a class of that name can't be instantiated, the error raised will be logged, and the Python interpreter will be shut down.

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
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ app_packages_path = "{{ cookiecutter.class_name }}/app_packages"
info_plist_path = "{{ cookiecutter.class_name }}/{{ cookiecutter.class_name }}-Info.plist"
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, "") }}

icon.20 = "{{ cookiecutter.class_name }}/Images.xcassets/AppIcon.appiconset/icon-20.png"
Expand Down
26 changes: 0 additions & 26 deletions {{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ int main(int argc, char *argv[]) {
wchar_t *wtmp_str;
wchar_t *app_packages_path_str;
const char* app_module_str;
const char* nslog_script;
PyObject *app_packages_path;
PyObject *app_module;
PyObject *module;
Expand Down Expand Up @@ -162,30 +161,6 @@ int main(int argc, char *argv[]) {
}

@try {
// Set the name of the python NSLog bootstrap script
nslog_script = [
[[NSBundle mainBundle] pathForResource:@"app_packages/nslog"
ofType:@"py"] cStringUsingEncoding:NSUTF8StringEncoding];
if (nslog_script == NULL) {
NSLog(@"No Python NSLog handler found. stdout/stderr will not be captured.");
NSLog(@"To capture stdout/stderr, add 'std-nslog' to your app dependencies.");
} else {
NSLog(@"Installing Python NSLog handler...");
FILE* fd = fopen(nslog_script, "r");
if (fd == NULL) {
crash_dialog(@"Unable to open nslog.py");
exit(-1);
}

ret = PyRun_SimpleFileEx(fd, nslog_script, 1);
fclose(fd);
if (ret != 0) {
crash_dialog(@"Unable to install Python NSLog handler");
exit(ret);
}
}


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


// Start the app module.
//
// From here to Py_ObjectCall(runmodule...) is effectively
Expand Down