blob: c65380cc0f75b23e2c13a9085ef4fc13db4f0365 [file]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""Defines `py_zipapp_binary()`, a Python binary packaged as a `.pyz` zipapp."""
load("@rules_python//python:py_info.bzl", "PyInfo")
load("//build/bazel/platforms:constraints.bzl", "HOST_OS_CONSTRAINTS")
load(
":py_data_package.bzl",
"CollectedPyDataPackageInfo",
"collect_py_data_package_aspect",
)
load(":py_toolchain.bzl", "PY_TOOLCHAIN_ATTRS", "generate_python_build_action")
visibility(["//..."])
# The runfiles directory name of the main repository. With Bzlmod, this is
# always "_main", which is also what `host_py_test()` assumes.
_MAIN_REPO_RUNFILES_DIR = "_main"
def _runfiles_path(file):
"""Returns the path of `file` relative to the runfiles root.
This is the form used by `PyInfo.imports`, e.g. "_main/build/foo/bar.py"
for a file in the main repository, or "<canonical_repo>/foo/bar.py" for a
file in an external repository (whose `short_path` is "../<repo>/...").
"""
if file.short_path.startswith("../"):
return file.short_path[len("../"):]
return _MAIN_REPO_RUNFILES_DIR + "/" + file.short_path
def _py_zipapp_binary_impl(ctx):
output_name = ctx.attr.output_name or ctx.label.name + ".pyz"
if not output_name.endswith(".pyz"):
fail("output_name must have .pyz as extension, got: " + output_name)
if ctx.files.data_sources and not ctx.attr.data_package_name:
fail("data_package_name is required if data_sources are provided")
main = ctx.file.main
if not main.basename.endswith(".py"):
fail("main must be a .py file, got: " + main.basename)
binary_sources = [main] + [f for f in ctx.files.srcs if f != main]
# Like `py_binary()`, the binary's own sources are also importable through
# the import roots that cover them (e.g. the repository root), in addition
# to being placed at the archive root. Data files staged by transitive
# `py_data_package()` dependencies are placed under their import roots too.
data_package_files = [
dep[CollectedPyDataPackageInfo].files
for dep in ctx.attr.deps
if CollectedPyDataPackageInfo in dep
]
all_sources = depset(
direct = binary_sources,
transitive = [dep[PyInfo].transitive_sources for dep in ctx.attr.deps] + data_package_files,
)
imports = depset(transitive = [dep[PyInfo].imports for dep in ctx.attr.deps])
pyz = ctx.actions.declare_file(output_name)
args = ctx.actions.args()
args.use_param_file("@%s", use_always = True)
args.set_param_file_format("multiline")
args.add("--output", pyz)
args.add("--main_module", main.basename[:-len(".py")])
args.add("--main_callable", ctx.attr.main_callable)
if ctx.attr.unbuffered_output:
args.add("--unbuffered")
args.add_all(binary_sources, before_each = "--binary_source")
# Pass each source's runfiles path and its path as separate, parallel lists
# (expanding the same depset gives the same order), since both can contain
# any character other than a newline.
args.add_all(all_sources, map_each = _runfiles_path, before_each = "--source_runfiles_path")
args.add_all(all_sources, before_each = "--source")
args.add_all(imports, before_each = "--import")
if ctx.attr.data_package_name:
args.add("--data_package_name", ctx.attr.data_package_name)
args.add_all(ctx.files.data_sources, before_each = "--data_source")
generate_python_build_action(
ctx,
py_script = ctx.file._builder,
inputs = depset(ctx.files.data_sources, transitive = [all_sources]),
outputs = [pyz],
arguments = [args],
mnemonic = "PyZipapp",
progress_message = "Packaging Python zipapp %{output}",
)
return [DefaultInfo(
files = depset([pyz]),
executable = pyz,
)]
_py_zipapp_binary = rule(
implementation = _py_zipapp_binary_impl,
doc = "Packages Python sources and their PyInfo dependencies into a `.pyz` zipapp.",
executable = True,
attrs = {
"main": attr.label(
doc = "Source file containing `main_callable`.",
mandatory = True,
allow_single_file = [".py"],
),
"srcs": attr.label_list(
doc = "Additional sources of the binary, placed at the archive root.",
allow_files = [".py"],
),
"deps": attr.label_list(
doc = "Python libraries and `py_data_package()` targets the binary depends on.",
providers = [PyInfo],
aspects = [collect_py_data_package_aspect],
),
"main_callable": attr.string(
doc = "Name of the callable in `main` to run.",
default = "main",
),
"output_name": attr.string(
doc = "Name of the output archive. Must end with `.pyz`.",
),
"unbuffered_output": attr.bool(
doc = "Run the interpreter with `-u` when the archive is executed directly.",
),
"data_package_name": attr.string(
doc = "Name of the Python package that holds `data_sources`.",
),
"data_sources": attr.label_list(
doc = "Data files accessible through `importlib.resources`.",
allow_files = True,
),
"_builder": attr.label(
default = "//build/bazel/rules/python:build_py_zipapp.py",
allow_single_file = True,
),
} | PY_TOOLCHAIN_ATTRS,
)
def _py_zipapp_binary_macro_impl(name, visibility, target_compatible_with, **kwargs):
_py_zipapp_binary(
name = name,
visibility = visibility,
target_compatible_with = (
HOST_OS_CONSTRAINTS if target_compatible_with == None else target_compatible_with
),
**kwargs
)
py_zipapp_binary = macro(
doc = """Defines a Python binary packaged as a self-contained `.pyz` zipapp.
This is the Bazel equivalent of the GN `python_binary()` template
(//build/python/python_binary.gni). Unlike `py_binary()`, whose launcher needs
a sibling `<name>.runfiles/` tree, the output is a single file, so
`bazel_py_host_tool()` (//build/bazel/bazel_py_host_tool.gni) can copy it into
the Ninja build, for `python_action()` or to install it as a host tool.
Archive layout:
* `main` and `srcs` at the archive root, by basename (like GN
`python_binary()`).
* Every source of the binary and of its transitive `deps`, under every
import root that contains it, like `py_binary()` puts each root on
`sys.path`: the root of the file's repository (so imports like
`from build.foo import bar` work) and each `PyInfo.imports` entry.
* `data_sources` in the `data_package_name` package, plus data files staged
by transitive `py_data_package()` dependencies under their import roots.
* A generated `__main__.py` that runs `main_callable` from `main` (with
`asyncio.run()` if it is a coroutine function).
Only Python sources and `py_data_package()` resources are packaged: plain
`data` of dependencies and native extension modules (unless explicitly staged
and extracted with `importlib.resources.as_file()`) are not.
The archive starts with `#!/usr/bin/env fuchsia-vendored-python`, so it can be
executed directly in the Fuchsia build and developer environments.
`target_compatible_with` defaults to HOST_OS_CONSTRAINTS.
""",
implementation = _py_zipapp_binary_macro_impl,
# All the public attributes of the rule, including common ones such as
# `testonly`, `tags` and `target_compatible_with`.
inherit_attrs = _py_zipapp_binary,
)