diff --git a/changes/1807.doc.rst b/changes/1807.doc.rst new file mode 100644 index 000000000..2fd1d62a3 --- /dev/null +++ b/changes/1807.doc.rst @@ -0,0 +1 @@ +Documentation on Briefcase's plug-in interfaces was added. diff --git a/changes/1807.feature.rst b/changes/1807.feature.rst new file mode 100644 index 000000000..6b600ec11 --- /dev/null +++ b/changes/1807.feature.rst @@ -0,0 +1 @@ +The new project wizard now includes links to known third-party GUI bootstraps. diff --git a/docs/reference/commands/new.rst b/docs/reference/commands/new.rst index d4fbeefe2..6007de67c 100644 --- a/docs/reference/commands/new.rst +++ b/docs/reference/commands/new.rst @@ -49,3 +49,31 @@ The expected keys are specified by the cookiecutter template being used to create the new project. Therefore, the set of possible keys is not listed here but should be expected to remain consistent for any specific version of Briefcase; with version changes, though, the keys may change. + +Third-party Bootstraps +====================== + +When you run new project wizard, you are asked to select a GUI toolkit. Briefcase +includes bootstraps for `Toga `__ (BeeWare's cross-platform +GUI framework), `PySide6 `__ (Python bindings for the +Qt GUI toolkit) and `Pygame `__ (a common Python game +development toolkit), as well as an "empty" bootstrap that doesn't include any GUI code. +However, Briefcase provides a :ref:`plug-in interface ` that allows +GUI toolkits to provide a their own bootstrap implementation. + +The following third-party bootstraps are known to exist: + +=================================== ============== =================================================== +Bootstrap Package name Description +=================================== ============== =================================================== +`PursuedPyBear `__ ``ppb`` "Unbearably fun game development". A game toolkit + with a focus on being education friendly and + exposing an idiomatic Python interface. +----------------------------------- -------------- --------------------------------------------------- +`Pygame-ce `__ ``pygame-ce`` A fork of pygame, the classic library for making + games in Python. +=================================== ============== =================================================== + +To add a third-party bootstrap, ``pip install`` the named package into the virtual +environment that contains Briefcase, then run ``briefcase new``. The new bootstrap +option should be added to the list of GUI toolkits. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 0b0b958ef..812006ae3 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -14,3 +14,4 @@ This is the technical reference for public APIs provided by Briefcase. configuration commands/index platforms/index + plugins diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst new file mode 100644 index 000000000..187190ed1 --- /dev/null +++ b/docs/reference/plugins.rst @@ -0,0 +1,70 @@ +======== +Plug-ins +======== + +Briefcase ships with support for a range of platforms, output formats and GUI toolkits. +Internally, these features are implemented using a plug-in interface; as a result, it is +possible for third-party projects to add their own features to Briefcase by implementing +plug-ins that satisfy those interfaces. + +Each plug-in is defined using an `entry point +`__ definition in +``pyproject.toml``. + +.. _bootstrap-interface: + +``briefcase.bootstraps`` +======================== + +The Briefcase :doc:`new project wizard ` asks users to select a +GUI toolkit. The option selected at this step alters the content of the code generated +by the wizard, generating framework-specific requirements, system packages, and stub +code for a new application using that GUI framework. These additions are configured +using a ``briefcase.bootstrap`` plug-in. + +To add a custom ``briefcase.bootstrap`` plug-in, add a +``[project.entry-points."briefcase.platforms"]`` section to your ``pyproject.toml`` +file; each name/value pair under that section will be interpreted as a bootstrap. The +name of each bootstrap setting is the label that will be surfaced to the user in the +wizard. The value is a string identifying a class that implements the +``briefcase.bootstraps.base.BaseGuiBootstrap`` abstract base class. + +For example, the Toga bootstrap is implemented using the following configuration:: + + [project.entry-points."briefcase.bootstraps"] + Toga = "briefcase.bootstraps.toga:TogaGuiBootstrap" + +``briefcase.platforms`` and ``briefcase.formats.*`` +=================================================== + +Each command implemented by Briefcase is specialized by a platform and output format. +This implementation is defined using a pair of plug-ins - a ``briefcase.platforms`` +definition describing a platform, and a ``briefcase.format.`` definition that +defines the output formats for that platform. + +The ``briefcase.platforms`` entry point defines the existence of a platform. Each name +in this section is name of a platform that can be used when invoking Briefcase commands. +The value is a fully-qualified Python module name that must defines a single constant +``DEFAULT_OUTPUT_FORMAT``. + +Each platform name is then incorporated into the name of a separate ``format`` entry +point. Each entry in the ``format`` section for a platform is the name of an output +format that can be used when invoking Briefcase commands. The value is a fully-qualified +Python module name that defines 7 symbols: + +* ``create`` - a subclass of ``briefcase.commands.create.CreateCommand`` +* ``update`` - a subclass of ``briefcase.commands.create.UpdateCommand`` +* ``open`` - a subclass of ``briefcase.commands.create.OpenCommand`` +* ``build`` - a subclass of ``briefcase.commands.create.BuildCommand`` +* ``run`` - a subclass of ``briefcase.commands.create.RunCommand`` +* ``package`` - a subclass of ``briefcase.commands.create.PackageCommand`` +* ``publish`` - a subclass of ``briefcase.commands.create.PublishCommand`` + +For example, the definition for the macOS Xcode output format is controlled by the +following:: + + [project.entry-points."briefcase.platforms"] + macOS = "briefcase.platforms.macOS" + + [project.entry-points."briefcase.formats.macOS"] + xcode = "briefcase.platforms.macOS.xcode" diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 45bc9a116..82949e195 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -11,6 +11,7 @@ backported BeeWare Bugfix Bugfixes +ce checkmarks codebase Cookiecutter @@ -66,6 +67,7 @@ proxied Proxied proxying px +pygame Pygame Pyodide PyScript @@ -87,6 +89,7 @@ submodule subprocesses tl toml +toolkits towncrier tox TTY diff --git a/src/briefcase/commands/new.py b/src/briefcase/commands/new.py index 2bb7c74be..4e4997855 100644 --- a/src/briefcase/commands/new.py +++ b/src/briefcase/commands/new.py @@ -621,7 +621,13 @@ def build_gui_context( bootstrap_override = reverse_lookup[bootstraps[bootstrap_override]] selected_bootstrap = self.select_option( - intro="What GUI toolkit do you want to use for this project?", + intro=( + "What GUI toolkit do you want to use for this project?\n" + "\n" + "Additional GUI bootstraps are available; visit " + "https://beeware.org/bee/briefcase-bootstraps " + "for a full list of known GUI bootstraps." + ), variable="GUI Framework", default=None, options=bootstrap_options.keys(),