Project configuration options¶
Briefcase is a PEP518-compliant build
tool. It uses a pyproject.toml
file, in the root directory of your project,
to provide build instructions for the packaged file.
If you have an application called “My App”, with source code in the src/myapp
directory, the simplest possible pyproject.toml
Briefcase configuration
file would be:
[tool.briefcase]
project_name = "My Project"
bundle = "com.example"
version = "0.1"
[tool.briefcase.app.myapp]
formal_name = "My App"
description = "My first Briefcase App"
sources = ['src/myapp']
The configuration sections are tool specific, and start with the prefix
tool.briefcase
.
The location of the pyproject.toml
file is treated as the root of the
project definition. Briefcase should be invoked in a directory that contains a
pyproject.toml
file, and all relative file path references contained in the
pyproject.toml
file will be interpreted relative to the directory that
contains the pyproject.toml
file.
Configuration sections¶
A project that is packaged by Briefcase can declare multiple applications. Each application is a distributable product of the build process. A simple project will only have a single application. However, a complex project may contain multiple applications with shared code.
Each setting can be specified:
At the level of an output format (e.g., settings specific to building macOS DMGs);
At the level of an platform for an app (e.g., macOS specific settings);
At the level of an individual app; or
Globally, for all applications in the project.
When building an application in a particular output format, Briefcase will look
for settings in the same order. For example, if you’re building a macOS DMG for
an application called myapp
, Briefcase will look for macOS DMG settings for
myapp
, then for macOS settings for myapp
, then for myapp
settings,
then for project-level settings.
[tool.briefcase]
¶
The base [tool.briefcase]
section declares settings that project specific,
or are are common to all applications in this repository.
[tool.briefcase.app.<app name>]
¶
Configuration options for a specific application.
<app name>
must adhere to a valid Python distribution name as specified in
PEP508. The app name must also
not be a reserved word in Python, Java or JavaScript (i.e., app names like
switch
or pass
would not be valid); and it may not include any of the
filenames prohibited by Windows
(i.e., CON
, PRN
, or LPT1
).
[tool.briefcase.app.<app name>.<platform>]
¶
Configuration options for an application that are platform specific. The
platform must match a name for a platform supported by Briefcase (e.g.,
macOS
or windows
). A list of the platforms supported by Briefcase can
be obtained by running briefcase -h
, and inspecting the help for the
platform
option
[tool.briefcase.app.<app name>.<platform>.<output format>]
¶
Configuration options that are specific to a particular output format. For
example, macOS applications can be generated in app
or dmg
format.
This section can contain additional layers. for example, an app targeting the
Linux system
backend can define a tool.briefcase.app.<app
name>.linux.system.ubuntu.jammy
section to provide configurations specific to
Ubuntu 22.04 “Jammy” deployments. See the documentation for each backend for
more details.
Project configuration¶
Required values¶
bundle
¶
A reverse-domain name that can be used to identify resources for the
application e.g., com.example
. The bundle identifier will be combined with
the app name to produce a unique application identifier - e.g., if the bundle
identifier is com.example
and the app name is myapp
, the application
will be identified as com.example.myapp
.
project_name
¶
The project is the collection of all applications that are described by the briefcase configuration. For projects with a single app, this may be the same as the formal name of the solitary packaged app.
version
¶
A PEP440 compliant version string.
Examples of valid version strings:
1.0
1.2.3
1.2.3.dev4
- A development release1.2.3a5
- An alpha pre-release1.2.3b6
- A Beta pre-release1.2.3rc7
- A release candidate1.2.3.post8
- A post-release
Optional values¶
url
¶
A URL where more details about the project can be found.
Application configuration¶
Required¶
description
¶
A short, one-line description of the purpose of the application.
sources
¶
A list of paths, relative to the pyproject.toml
file, where source code for
the application can be found. The contents of any named files or folders will be
copied into the application bundle. Parent directories in any named path will
not be included. For example, if you specify src/myapp
as a source, the
contents of the myapp
folder will be copied into the application bundle; the
src
directory will not be reproduced.
Unlike most other keys in a configuration file, sources
is a cumulative
setting. If an application defines sources at the global level, application
level, and platform level, the final set of sources will be the
concatenation of sources from all levels, starting from least to most
specific.
Optional values¶
accent_color
¶
A hexadecimal RGB color value (e.g., #D81B60
) for a subtle secondary color
to be used throughout an application to call attention to key elements. This
setting is only used if the platform allows color modification, otherwise it
is ignored.
author
¶
The person or organization responsible for the application.
author_email
¶
The contact email address for the person or organization responsible for the application.
build
¶
A build identifier. An integer, used in addition to the version specifier, to identify a specific compiled version of an application.
cleanup_paths
¶
A list of strings describing paths that will be removed from the project after
the installation of the support package and app code. The paths provided will be
interpreted relative to the platform-specific build folder generated for the app
(e.g., the build/my-app/macOS/app
folder in the case of a macOS app).
- Paths can be:
An explicit reference to a single file
An explicit reference to a single directory
Any file system glob accepted by
pathlib.glob
(See the Python documentation for details)
Paths are treated as format strings prior to glob expansion. You can use Python
string formatting to include references to configuration properties of the app
(e.g., app.formal_name
, app.version
, etc).
For example, the following cleanup_paths
specification:
cleanup_paths = [
"path/to/unneeded_file.txt",
"path/to/unneeded_directory",
"path/**/*.exe",
"{app.formal_name}/content/extra.doc"
]
on an app with a formal name of “My App” would remove:
The file
path/to/unneeded_file.txt
The directory
path/to/unneeded_directory
Any
.exe
file inpath
or its subdirectories.The file
My App/content/extra.doc
.
console_app
¶
A Boolean describing if the app is a console app, or a GUI app. Defaults to False
(producing a GUI app). This setting has no effect on platforms that do not support a
console mode (e.g., web or mobile platforms). On platforms that do support console apps,
the resulting app will write output directly to stdout
/stderr
(rather than
writing to a system log), creating a terminal window to display this output (if the
platform allows).
exit_regex
¶
A regular expression that will be executed against the console output generated
by an application. If/when the regular expression find match, the application
will be terminated; the line matching the regular expression will not be
output to the console. Used by Briefcase to monitor test suites; however, the
filter will also be honored on normal run
invocations.
The regular expression should capture a single group named returncode
,
capturing the integer exit status that should be reported for the process. The
default value for this regular expression is ^>>>>>>>>>> EXIT
(?P<returncode>.*) <<<<<<<<<<$
The regex will be compiled with the
re.MULTILINE
flag enabled.
formal_name
¶
The application name as it should be displayed to humans. This name may contain
capitalization and punctuation. If it is not specified, the name
will be
used.
icon
¶
A path, relative to the directory where the pyproject.toml
file is located,
to an image to use as the icon for the application. The path should exclude
the extension; Briefcase will append a platform appropriate extension when
configuring the application. For example, an icon specification of icon =
"resources/icon"
will use resources/icon.icns
on macOS, and
resources/icon.ico
on Windows.
Some platforms require multiple icons, at different sizes; these will be
handled by appending the required size to the provided icon name. For example,
iOS requires multiple icon sizes (ranging from 20px to 1024px); Briefcase will
look for resources/icon-20.png
, resources/icon-1024.png
, and so on. The
sizes that are required are determined by the platform template.
installer_icon
¶
A path, relative to the directory where the pyproject.toml
file is located,
to an image to use as the icon for the installer. As with icon
, the
path should exclude the extension, and a platform-appropriate extension will
be appended when the application is built.
installer_background
¶
A path, relative to the directory where the pyproject.toml
file is located,
to an image to use as the background for the installer. The path should
exclude the extension, and a platform-appropriate extension will be appended
when the application is built.
long_description
¶
A longer description of the purpose of the application. This description can be
multiple paragraphs, if necessary. The long description must not be a copy of
the description
, or include the description
as the first line of the
long_description
.
primary_color
¶
A hexadecimal RGB color value (e.g., #008577
) to use as the primary color
for the application. This setting is only used if the platform allows color
modification, otherwise it is ignored.
primary_color_dark
¶
A hexadecimal RGB color value (e.g., #008577
) used alongside the primary
color. This setting is only used if the platform allows color modification,
otherwise it is ignored.
requires
¶
A list of packages that must be packaged with this application.
Unlike most other keys in a configuration file, requires
is a cumulative
setting. If an application defines requirements at the global level,
application level, and platform level, the final set of requirements will be
the concatenation of requirements from all levels, starting from least to
most specific.
Any PEP 508 version specifier is legal. For example:
Bare package name:
requires = ["pillow"]
Package name with version specifier:
requires = ["pillow==9.1.0"]
Install from source using the
--no-binary
entry:requires = [ "pillow==9.1.0", "--no-binary", "pillow", ]
Git repository:
requires=["git+https://github.com/beeware/briefcase.git"]
Local directory:
requires=["mysrc/myapp"]
Local wheel file:
requires=["fullpath/wheelfile.whl"]
revision
¶
An identifier used to differentiate specific builds of the same version of an
app. Defaults to 1
if not provided.
splash_background_color
¶
A hexadecimal RGB color value (e.g., #6495ED
) to use as the background
color for splash screens.
If the platform output format does not use a splash screen, this setting is ignored.
stub_binary
¶
A file path or URL pointing at a pre-compiled binary (or a zip/tarball of a binary) that can be used as an entry point for a bundled application.
If this setting is not provided, and a stub binary is required by the platform, Briefcase will use the default stub binary for the platform.
stub_binary_revision
¶
The specific revision of the stub binary that should be used. By default, Briefcase will use the stub binary revision nominated by the application template. If you specify a stub binary revision, that will override the revision nominated by the application template.
If you specify an explicit stub binary (using the stub_binary
setting), this
argument is ignored.
support_package
¶
A file path or URL pointing at a tarball containing a Python support package. (i.e., a precompiled, embeddable Python interpreter for the platform)
If this setting is not provided, Briefcase will use the default support package for the platform.
support_revision
¶
The specific revision of a support package that should be used. By default, Briefcase will use the support package revision nominated by the application template. If you specify a support revision, that will override the revision nominated by the application template.
If you specify an explicit support package (either as a URL or a file path), this argument is ignored.
supported
¶
Indicates that the platform is not supported. For example, if you know that
the app cannot be deployed to Android for some reason, you can explicitly
prevent deployment by setting supported=False
in the Android section of
the app configuration file.
If supported
is set to false
, the create command will fail, advising
the user of the limitation.
template
¶
A file path or URL pointing at a cookiecutter template for the output format.
If this setting is not provided, Briefcase will use a default template for the output format and Python version.
template_branch
¶
The branch of the project template to use when generating the app. If the
template is a local file, this attribute will be ignored. If not specified,
Briefcase will use a branch matching the version of Briefcase that is being
used (i.e., if you’re using Briefcase 0.3.9, Briefcase will use the
v0.3.9
template branch when generating the app). If you’re using a
development version of Briefcase, Briefcase will use the main
branch of the
template.
test_requires
¶
A list of packages that are required for the test suite to run.
Unlike most other keys in a configuration file, test_requires
is a
cumulative setting. If an application defines requirements at the global
level, application level, and platform level, the final set of requirements
will be the concatenation of requirements from all levels, starting from least
to most specific.
See requires for examples.
test_sources
¶
A list of paths, relative to the pyproject.toml
file, where test code for
the application can be found. The contents of any named files or folders will be
copied into the application bundle. Parent directories in any named path will
not be included. For example, if you specify src/myapp
as a source, the
contents of the myapp
folder will be copied into the application bundle; the
src
directory will not be reproduced.
As with sources
, test_sources
is a cumulative setting. If an
application defines sources at the global level, application level, and
platform level, the final set of sources will be the concatenation of test
sources from all levels, starting from least to most specific.
url
¶
A URL where more details about the application can be found.
Permissions¶
Applications may also need to declare the permissions they require. Permissions are
specified as sub-attributes of a permission
property, defined at the level of an
project, app, or platform. Permission declarations are cumulative; if an application
defines permissions at the global level, application level, and platform level, the
final set of permissions will be the merged set of all permissions from all levels,
starting from least to most specific, with the most specific taking priority.
Briefcase maintains a set of cross-platform permissions:
permission.camera
- permission to access the camera to take photos or video.permission.microphone
- permission to access the microphone.permission.coarse_location
- permission to determine a rough GPS location.permission.fine_location
- permission to determine a precise GPS location.permission.background_location
- permission to track GPS location while in the background.permission.photo_library
- permission to access the user’s photo library.
If a cross-platform permission is used, it will be mapped to platform-specific values in whatever files are used to define permissions on that platform.
Permissions can also be configured by adding platform-specific configuration items. See the documentation for the platform backends to see the available options.
The value for each permission is a short description of why that permission is required. If the platform requires, the value may be displayed to the user as part of an authorization dialog. This description should describe why the app requires the permission, rather than a generic description of the permission being requested.
The use of permissions may also imply other settings in your app. See the individual platform backends for details on how cross-platform permissions are mapped.
Document types¶
Applications in a project can register themselves with the operating system as
handlers for specific document types by adding a document_type
configuration section for each document type the application can support. This
section follows the format:
[tool.briefcase.app.<app name>.document_type.<document type id>]
or, for a platform-specific definition:
[tool.briefcase.app.<app name>.<platform>.document_type.<document type id>]
The document type id
is an identifier, in alphanumeric format. It is appended to the app id of an application to identify documents of the same type.
The document type declaration requires the following settings:
description
¶
A short, one-line description of the document format.
extension
¶
The extension
is the file extension to register. For example, myapp
could register as a handler for PNG image files by defining the configuration
section [tool.briefcase.app.myapp.document_type.png]
.
icon
¶
A path, relative to the directory where the pyproject.toml
file is located,
to an image for an icon to register for use with documents of this type. The
path should exclude the extension; Briefcase will append a platform-appropriate extension when configuring the application. For example, an icon
specification of:
icon = "resources/icon"
will use resources/icon.icns
on macOS, and resources/icon.ico
on
Windows.
Some platforms also require different variants (e.g., both square and round icons). These variants can be specified by qualifying the icon specification:
icon.round = "resource/round-icon"
icon.square = "resource/square-icon"
Some platforms require multiple icons, at different sizes; these will be
handled by appending the required size to the provided icon name. For example,
iOS requires multiple icon sizes (ranging from 20px to 1024px); Briefcase will
look for resources/icon-20.png
, resources/icon-1024.png
, and so on. The
sizes that are required are determined by the platform template.
If a platform requires both different sizes and variants, the variant
handling and size handling will be combined. For example, Android requires
round and square icons, in sizes ranging from 48px to 192px; Briefcase will
look for resource/round-icon-42.png
, resource/square-icon-42.png
,
resource/round-icon-192.png
, and so on.
url
¶
A URL for help related to the document format.
PEP621 compatibility¶
Many of the keys that exist in Briefcase’s configuration have analogous settings
in PEP621 project metadata.
If your pyproject.toml
defines a [project]
section, Briefcase will honor
those settings as a top level definition. Any [tool.briefcase]
definitions
will override those in the [project]
section.
The following PEP621 project metadata keys will be used by Briefcase if they are available:
version
maps to the same key in Briefcase.authors
Theemail
andname
keys of the first value in theauthors
setting map toauthor
andauthor_email
.dependencies
maps to the Briefcaserequires
setting. This is a cumulative setting; any packages defined in therequires
setting at the[tool.briefcase]
level will be appended to the packages defined withdependencies
at the[project]
level.description
maps to the same key in Briefcase.test
in an[project.optional-dependencies]
section maps totest_requires
., As withdependencies
/requires
, this is a cumulative setting.text
in a[project.license]
section will be mapped tolicense
.homepage
in a[project.urls]
section will be mapped tourl
.requires-python
will be used to validate the running Python interpreter’s version against the requirement.