Giter Club home page Giter Club logo

briefcase-macos-xcode-template's Introduction

Briefcase macOS Xcode Template

A 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 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-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, 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:

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

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's People

Contributors

brutusthebee avatar davidfokkema avatar dependabot[bot] avatar drewbrew avatar freakboy3742 avatar mhsmith avatar nadi726 avatar rmartin16 avatar samschott avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

briefcase-macos-xcode-template's Issues

Include a PYTHONPATH extension allowing for user-space packages.

What is the problem or limitation you are having?

The stub app currently sets a PYTHONPATH that includes the app and app_packages paths, plus the stdlib.

These paths are all inside the application bundle, which is a code-signed location.

If a user wants to add additional files to the PYTHONPATH (e.g., if you were building a "Jupyter Notebook" app, and wanted the user to be able to access user-installed packages), you can't install that code into app or app_packages.

Describe the solution you'd like

The stub app should include an Application Support folder as part of the standard app path.

Following the guidance of this document, this should be something like:
~/Library/Application Support/com.example.myapp/user_packages

Describe alternatives you've considered

Don't allow user-installed packages.

Additional context

Looking in an actual application support folder, there's some variation between the use of Formal Name and bundle as the app-specific identifier - i.e., ~/Library/Application Support/My App/user_packages. Using the bundle ID seem least likely to cause collisions.

Once this feature lands, the app template will need to be updated with a new binary.

Setting PYTHONHOME when initialising Python does not work as intended

Describe the bug
The main.m program which initialises the Python runtime sets PYTHONHOME here:

python_home = [NSString stringWithFormat:@"%@/support/python-stdlib", resourcePath, nil];
NSLog(@"PythonHome: %@", python_home);
wtmp_str = Py_DecodeLocale([python_home UTF8String], NULL);
status = PyConfig_SetString(&config, &config.home, wtmp_str);

This is does not work as intended. As documented in https://docs.python.org/3/using/cmdline.html#envvar-PYTHONHOME, the home is suffixed with /lib/python3.11, resulting in the Python runtime believing that

Contents/Resources/support/python-stdlib/lib/python3.11

is the location of its stdlib.

In practice, this is not a problem because we later explicitly include the stdlib in the Python path:

path = [NSString stringWithFormat:@"%@/support/python-stdlib/lib-dynload", resourcePath, nil];
NSLog(@"- %@", path);
wtmp_str = Py_DecodeLocale([path UTF8String], NULL);
status = PyWideStringList_Append(&config.module_search_paths, wtmp_str);

This does mean however that the initially quoted lines currently are not useful at all.

To Reproduce

  1. Build the Xcode project.
  2. From the Python program, inspect ``.

Additional context
We could do either of the following:

  1. Completely rely on the PYTHONPATH to contain the stdlib.
  2. Set the stdlib dir correctly, if possible, and omit it the PYTHONPATH.
  3. Change the location of the stdlib directory to Contents/Resources/support/lib/python3.11

Isolated Python config uses Ascii encoding

Describe the bug
Now that Python is initialised with an isolated config, it seems to now longer read the LC_CTYPE environment variable which we set in the Info.plist. As a result, it is initialised with Ascii encoding instead of UTF-8.

To Reproduce
Steps to reproduce the behavior:

  1. Create and build a default briefcase app with the newest template.
  2. Try to print a non-ascii character to the console from the app.

Environment:

  • Operating System: macOS
  • Python version: 3.11
  • Software versions:
    • Briefcase: 0.3.12.dev188+g4cac510

Additional context
We should probably tell Python to use UTF-8 using in the pre-config:
https://docs.python.org/3/c-api/init_config.html#c.PyPreConfig.utf8_mode

Stub binary doesn't support `sys.executable` spawn/multiprocessing

Describe the bug

The stub binary used to start an app is an effective replacement for the python binary; however, it isn't a perfect replacements. multiprocessing in spawn mode will try to invoke sys.executable to spawn a child; it's also common to use subprocess or os.spawn to try and start sys.exectuable to run other Python code as a subprocess. However, the stub binary doesn't support this kind of execution.

Steps to reproduce

  1. Generate a stub macOS app
  2. Add a call to call multiprocessing.Process() and start it with .start()

The subprocess will call the parent process entry point, and fail.

Expected behavior

The function targeted by Process() should be invoked with the provided arguments.

Screenshots

No response

Environment

  • Operating System: All macOS
  • Python version: All
  • Software versions:
    • Briefcase: 0.3.12

Logs

n/a

Additional context

See beeware/briefcase-macOS-app-template#7 for the original report on macOS; the fault is with the stub binary, so the fix needs to be on the Xcode template. Any fix here will be inherited by the app template.

One possible solution would be to add some logic to the stub binary to inspect to see if the parent process is "self"; if so, the execution of the app should be modified to behave as if it were a normal Python binary.

Any solution should also be ported to Linux (beeware/briefcase-linux-flatpak-template#10) and Windows (beeware/briefcase-windows-VisualStudio-template#8).

Don't redirect stdout to NSLog

On iOS, it makes sense to redirect all stdout and stderr to NSLog because this output can otherwise not be captured. On macOS, there may be some circumstances in which stdout should not be redirected, for instance in case of a command line tool which is distributed as an app bundle.

Would it make sense to only redirect stderr to the NSLog? Or are there particular use cases where it would be valuable to have stdout printed to the logs? AFAIK, all Python errors and warnings are printed stderr anyways.

Cannot retrieve traceback without nslog scripts

Describe the bug
Currently, retrieving the traceback from an unhandled Python exceptions and displayed it in an error dialog relies on sys._traceback being set. sys._traceback is set by the nslog pyhton script which is no longer required by briefcase since fixing beeware/briefcase#675. If a user chooses not to install it, any Python exceptions will generate the unhelpful error message Could not access sys._traceback.

To Reproduce
Steps to reproduce the behavior:

  1. Create a briefcase project without the std-nslog dependency.
  2. Trigger an unhandled exception.

Expected behavior
Show the actual traceback instead.

Environment:

  • Operating System: macOS
  • Python version: 3.7 to 3.10

Additional context
Ideally, we would use the CPython API to retrieve and format the traceback even when std-nslog is not installed.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.