Native System Packages¶
Host Platform Support (Platform support) |
||||||||||
---|---|---|---|---|---|---|---|---|---|---|
macOS |
Windows |
Linux |
||||||||
x86‑64 |
arm64 |
x86 |
x86‑64 |
arm64 |
x86 |
x86‑64 |
arm |
arm64 |
||
○ |
○ |
△ |
● |
△ |
● |
All modern Linux distributions have a native format for distributing packages that are integrated into their overall operating system:
.deb
, used by Debian, Ubuntu, Mint (and others).rpm
, used by Red Hat, Fedora, CentOS, AlmaLinux, openSUSE (and others).pkg.tar.zst
, used by Arch Linux and Manjaro Linux
The Briefcase system
backend provides a way to build your app in these
system package formats.
Not all Linux distributions are supported!
Briefcase cannot reliably identify every Linux vendor. If your Linux distribution
isn’t being identified (or isn’t being identified correctly), please open a ticket with the contents of your
/etc/os-release
file.
The packaged app includes a stub binary, so that the app will appear in process lists using your app’s name. It also includes a FreeDesktop registration so the app will appear in system menus.
When installed from a Briefcase-produced system package, the app will use the system Python install, and the standard library provided by the system. However, the app will be isolated from any packages that have been installed at a system level.
As the app uses the system Python, system packages are highly dependent on the distribution version. It is therefore necessary to build a different system package for every distribution you want to target. To help simplify this process, Briefcase uses Docker to provide build environments. Using these Docker environments, it is possible to build a system package for any target distribution and version, regardless of the host distribution and version - that is, you can build a Debian Buster package on an Ubuntu 20.04 machine, or an Ubuntu 22.04 package on a RHEL8 machine.
The usage of the system Python also means that system packages are different from most other Briefcase-packaged apps. On other target platforms (macOS and Windows apps, Linux AppImage, etc), the version of Python used to run Briefcase will be the version of Python used by the bundled app. However, when building a system package, Briefcase will use the operating system’s Python3 installation for system packages, regardless of the host Python version. This means you will need to perform additional platform testing to ensure that your app is compatible with that version of Python.
Icon format¶
Deb packages uses .png
format icons. An application must provide icons in
the following sizes:
16px
32px
64px
128px
256px
512px
Linux System packages do not support splash screens or installer images.
Additional files¶
The Linux system app template includes a LICENSE
and CHANGELOG
file,
with stub content. When the application is generated from template, Briefcase
will look in the project root folder (i.e., the folder that contains your
pyproject.toml
) for files with the same name. If these files are found, they
will be copied into your project. You should ensure these files are complete and
correct before publishing your app.
The Linux system app template also includes an initial draft manfile for your
app. This manfile will be populated with the description
and
long_description
of your app. You may wish to add more details on app usage.
Additional options¶
The following options can be provided at the command line when producing Deb packages:
--target
¶
A Docker base image identifier for the Linux distribution you want to target.
The identifier will be in the pattern <vendor>:<codename>
(e.g.,
debian:buster
or ubuntu:jammy
). You can also use the version number in
place of the code name (e.g., debian:10
, ubuntu:22.04
, or
fedora:37
). Whichever form you choose, you should be consistent; no
normalization of code name and version is performed, so ubuntu:jammy
and
ubuntu:22.04
will be identified as different versions (even though they the
same version).
You can specify any identifier you want, provided the distribution is still supported by the vendor, and system Python is Python 3.9 or later.
The following Linux vendors are known to work as Docker targets:
Debian (e.g.,
debian:bookworm
ordebian:12
)Ubuntu (e.g.,
ubuntu:noble
orubuntu:24.04
)Fedora (e.g,
fedora:41
)AlmaLinux (e.g.,
almalinux:9
)Red Hat Enterprise Linux (e.g.,
redhat/ubi9:9
)openSUSE Tumbleweed (e.g.,
"opensuse/tumbleweed:latest"
)Arch Linux (e.g.,
archlinux:latest
)Manjaro Linux (e.g.,
manjarolinux/base:latest
)
--Xdocker-build=<value>
¶
A configuration argument to be passed to the Docker build command for the app
image. For example, to provide an additional build argument to the Dockerfile,
specify --Xdocker-build=--build-arg=ARG=value
. See the Docker build
documentation
for details on the full list of options that can be provided.
You may specify multiple --Xdocker-build
arguments; each one specifies a
single argument to pass to Docker, in the order they are specified.
Application configuration¶
The following options can be added to the
tool.briefcase.app.<appname>.linux.system
section of your pyproject.toml
file; if defined in this section, the values will apply for all Linux
distributions for which you build packages.
If you need to override these settings for a specific target vendor, or for a specific distribution version, you can provide increasingly specific sections for vendor and version information. Each distribution is identified by:
Vendor base (e.g.,
debian
,rhel
,arch
,suse
)Vendor (e.g,
debian
,ubuntu
,rhel
,fedora
,opensuse-tumbleweed
,arch
,manjaro
). The vendor identifier may be the same as the vendor base (e.g, in the case of Debian, Red Hat, or Arch)Code name (e.g., a version number, or
jammy
).
For example, a full configuration for myapp
running on Ubuntu 22.04 (jammy)
would consist of the following sections:
tool.briefcase.app.myapp
providing global configuration optionstool.briefcase.app.myapp.linux
providing definitions common to all Linux packaging backendstool.briefcase.app.myapp.linux.system
providing definitions for all Linux system package targetstool.briefcase.app.myapp.linux.system.debian
providing definitions common to all Debian-based packaging targetstool.briefcase.app.myapp.linux.system.ubuntu
providing definitions common to all Ubuntu-based packaging targetstool.briefcase.app.myapp.linux.system.ubuntu.jammy
providing definitions specific to for Ubuntu 22.04 (Jammy).
These configurations will be merged at runtime; any version-specific definitions will override the generic vendor definitions; any vendor definitions will override the vendor-base definitions; and any vendor-base definitions will override generic system package definitions.
system_requires
¶
A list of operating system packages that must be installed for the system package build to succeed. If a Docker build is requested, this list will be passed to the Docker context when building the container for the app build. These entries should be the format the target Linux distribution will accept. For example, if you’re using a Debian-derived distribution, you might use:
system_requires = ["libgirepository1.0-dev", "libcairo2-dev"]
to make the GTK GI and Cairo operating system development packages available to your app. However, if you’re on a RedHat-derived distribution, you would use:
system_requires = ["gobject-introspection-devel", "python3-cairo-devel"]
If you see errors during briefcase build
of the form:
Could not find dependency: libSomething.so.1
but the app works under briefcase dev
, the problem may be an incomplete
system_requires
definition. The briefcase build
process generates
a new environment that is completely isolated from your development
environment, so if your app has any operating system dependencies, they
must be listed in your system_requires
definition.
system_requires
are the packages required at build time. To specify
runtime system requirements, use the system_runtime_requires
setting.
system_runtime_requires
¶
A list of system packages that your app requires at runtime. These will be
closely related to the system_requires
setting, but will likely be
different; most notably, you will probably need -dev
packages at build time,
but non -dev
packages at runtime.
system_runtime_requires
should be specified as system package requirements;
they can optionally include version pins. Briefcase will automatically include
the dependencies needed for Python. For example:
system_runtime_requires = ["libgtk-3-0 (>=3.14)", "libwebkit2gtk-4.1-0"]
will specify that your app needs Python 3, a version of libgtk >= 3.14
, and any
version of libwebkit2gtk
.
Any problems with installing or running your system package likely indicate an
issue with your system_runtime_requires
definition.
system_section
¶
When an application is published as a .deb
file, Debian requires that you
specify a “section”, describing a classification of the application area. The
template will provide a default section of utils
; if you want to override
that default, you can specify a value for system_section
. For details on the
allowed values for system_section
, refer to the Debian Policy Manual.
dockerfile_extra_content
¶
Any additional Docker instructions that are required to configure the container
used to build your Python app. For example, any dependencies that cannot be
configured with apt-get
could be installed. dockerfile_extra_content
is
string literal that will be added verbatim to the end of the project Dockerfile.
Any Dockerfile instructions added by dockerfile_extra_content
will be
executed as the brutus
user, rather than the root
user. If you need to
perform container setup operations as root
, switch the container’s user to
root
, perform whatever operations are required, then switch back to the
brutus
user - e.g.:
dockerfile_extra_content = """
RUN <first command run as brutus>
USER root
RUN <second command run as root>
USER brutus
"""
Platform quirks¶
Local path references and Docker builds¶
Docker builds are not able to reference local paths in the requires
and
requirement_installer_args
configurations. This is because the Docker container only
has access to specific file paths on the host system. See issue #2018 for more discussion of the
problem, and some possible workarounds.