diff --git a/README.md b/README.md index 4a66fcf..55a8c79 100644 --- a/README.md +++ b/README.md @@ -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//__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//__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. diff --git a/{{ cookiecutter.format }}/briefcase.toml b/{{ cookiecutter.format }}/briefcase.toml index 32bb9e0..065c6a8 100644 --- a/{{ cookiecutter.format }}/briefcase.toml +++ b/{{ cookiecutter.format }}/briefcase.toml @@ -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", diff --git a/{{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m b/{{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m index 7496322..76225bc 100644 --- a/{{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m +++ b/{{ cookiecutter.format }}/{{ cookiecutter.class_name }}/main.m @@ -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; @@ -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 @@ -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. //