Alpha warning

This is documentation for an experimental rewrite of py2app, and is not relevant for public releases of py2app.

Configuration for py2app

This page will describe the configuration file for py2app.

Basic ideas:

  • The file will be a “TOML” file, with a default name of “py2app.toml”

    Todo

    determine if TOML is the right choice, it appears to use too much quoting to be a nice language, YAML appears to be friendlier.

  • The file contains arrays of tables describing application and plugin bundles

  • There may be global configuration, which can be overridden

  • Application bundles may contain an array table for plugins

  • In the long run it might be interesting to try to generalize the format to be usable on other platforms (windows, linux flatpacks, …)

  • The format should support all features of macOS applications/bundles, and should have a gentle learning curve (“easy things should be easy, hard things should be possible”)

Todo

What about conditional “logic” (version dependent settings etc.)

Introduction

The configuration file for py2app is a TOML file containing information on what, and how to build. This document is a reference for that configuration, see the to be written tutorial for a gentler introduction to this file.

The default name for this file is “py2app.toml”, located in the root of the source tree for a project.

A basic example of a py2app configuration is included below:

[py2app]
build_style = "alias"

[[py2app.application]]
name = "Hello World"
entrypoint = "main.py"

This defines an “alias” build for an application named “Hello World” that has “main.py” as its entry point.

Specification

The configuration for py2app is stored in a TOML file with a table named “py2app”. All other data in the file is ignored by py2app.

This table contains global and shared configuration as well as arrays of tables for applications and bundles. The configuration should define at least one application or bundle.

Global configuration in the table [py2app]:

  • build_style: The type of bundle to build

    Values values are:

    • “standalone” (default): Create a fully standalone bundle that can be copied to other machines without further dependencies.
    • “semi-standalone”: Create a standalone bundle that only relies on a Python framework. Can be run on all machines where a Python framework for the correct version of Python is installed.
    • “alias”: Create a bundle that includes references to source code. These bundles cannot be moved and are primarily usefull during debugging.

Table arrays [py2app.application] and [[py2app.bundle]] are used to describe applications and plugin bundles and contain the following keys and tables:

  • entrypoint: Name of the source file that is used to start the application.

  • name: Name of the bundle, defaults to the basename of the entrypoint file.

  • suffix: Name of the suffix for the bundle. This defaults to “.app” for application bundles, and “.bundle” for plugin bundles.

    Note

    The suffix should be changed for plugin bundles.

    Todo

    Document the suffix for common types of plugin bundles.

  • archs: Either a single string value, or an array of strings. Values values are:

    • “i386”: 32-bit Intel binary
    • “x86_64”: 64-bit Intel binary

    This defaults to the architectures of the python binary.

  • deployment_target: The minimal macOS version where the output can be used on. This defaults to the version of macOS on the build machine.

  • iconfile: Name of a icon file. This must be an existing file in the ICNS format. When no icon is provided py2app will use a generic icon.

  • build_type: Type of build. Valid values are:

    • “python”: a python program
    • “native”: use native (Objective-C) code to build this bundle. The bundle will not have a Python dependency.

  • native_source: List of Objective-C sources for this bundle.

    For “python” builds these sources are used to specify a custom launcher (instead of the launcher provided by py2app).

  • native_cflags: Compiler flags to be used when building native sources

  • native_ldflags: Compiler flags to be used when linking the native binary

Todo

Add more options to specify information that will be placed in the Info.plist file (other than iconfile), to make the info table a poweruser tool.

The table [py2app.application.info] contains information to be included in the Info.plist file for the bundle. See Apple’s document for the Info.plist file for information that can be included. The information in this table is copied as is into the Info.plist file.

For application bundles the table array [[py2app.application.plugins]] can be used to add plugins into the application bundle. These bundles will be placed in the right location in the application bundle to be found by the system. The structureof these table arrays is the same as the toplevel [py2app.plugins]] table array.