xref: /aosp_15_r20/external/bazelbuild-rules_python/python/private/flags.bzl (revision 60517a1edbc8ecf509223e9af94a7adec7d736b8) 
1# Copyright 2024 The Bazel Authors. All rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Values and helpers for flags.
16
17NOTE: The transitive loads of this should be kept minimal. This avoids loading
18unnecessary files when all that are needed are flag definitions.
19"""
20
21load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
22load("//python/private:enum.bzl", "enum")
23
24def _bootstrap_impl_flag_get_value(ctx):
25    return ctx.attr._bootstrap_impl_flag[BuildSettingInfo].value
26
27# buildifier: disable=name-conventions
28BootstrapImplFlag = enum(
29    SYSTEM_PYTHON = "system_python",
30    SCRIPT = "script",
31    get_value = _bootstrap_impl_flag_get_value,
32)
33
34def _precompile_flag_get_effective_value(ctx):
35    value = ctx.attr._precompile_flag[BuildSettingInfo].value
36    if value == PrecompileFlag.AUTO:
37        value = PrecompileFlag.DISABLED
38    return value
39
40# Determines if the Python exec tools toolchain should be registered.
41# buildifier: disable=name-conventions
42ExecToolsToolchainFlag = enum(
43    # Enable registering the exec tools toolchain using the hermetic toolchain.
44    ENABLED = "enabled",
45    # Disable registering the exec tools toolchain using the hermetic toolchain.
46    DISABLED = "disabled",
47)
48
49# Determines if Python source files should be compiled at build time.
50#
51# NOTE: The flag value is overridden by the target-level attribute, except
52# for the case of `force_enabled` and `forced_disabled`.
53# buildifier: disable=name-conventions
54PrecompileFlag = enum(
55    # Automatically decide the effective value based on environment,
56    # target platform, etc.
57    AUTO = "auto",
58    # Compile Python source files at build time. Note that
59    # --precompile_add_to_runfiles affects how the compiled files are included
60    # into a downstream binary.
61    ENABLED = "enabled",
62    # Don't compile Python source files at build time.
63    DISABLED = "disabled",
64    # Compile Python source files, but only if they're a generated file.
65    IF_GENERATED_SOURCE = "if_generated_source",
66    # Like `enabled`, except overrides target-level setting. This is mostly
67    # useful for development, testing enabling precompilation more broadly, or
68    # as an escape hatch if build-time compiling is not available.
69    FORCE_ENABLED = "force_enabled",
70    # Like `disabled`, except overrides target-level setting. This is useful
71    # useful for development, testing enabling precompilation more broadly, or
72    # as an escape hatch if build-time compiling is not available.
73    FORCE_DISABLED = "force_disabled",
74    get_effective_value = _precompile_flag_get_effective_value,
75)
76
77def _precompile_source_retention_flag_get_effective_value(ctx):
78    value = ctx.attr._precompile_source_retention_flag[BuildSettingInfo].value
79    if value == PrecompileSourceRetentionFlag.AUTO:
80        value = PrecompileSourceRetentionFlag.KEEP_SOURCE
81    return value
82
83# Determines if, when a source file is compiled, if the source file is kept
84# in the resulting output or not.
85# buildifier: disable=name-conventions
86PrecompileSourceRetentionFlag = enum(
87    # Automatically decide the effective value based on environment, etc.
88    AUTO = "auto",
89    # Include the original py source in the output.
90    KEEP_SOURCE = "keep_source",
91    # Don't include the original py source.
92    OMIT_SOURCE = "omit_source",
93    # Keep the original py source if it's a regular source file, but omit it
94    # if it's a generated file.
95    OMIT_IF_GENERATED_SOURCE = "omit_if_generated_source",
96    get_effective_value = _precompile_source_retention_flag_get_effective_value,
97)
98
99# Determines if a target adds its compiled files to its runfiles. When a target
100# compiles its files, but doesn't add them to its own runfiles, it relies on
101# a downstream target to retrieve them from `PyInfo.transitive_pyc_files`
102# buildifier: disable=name-conventions
103PrecompileAddToRunfilesFlag = enum(
104    # Always include the compiled files in the target's runfiles.
105    ALWAYS = "always",
106    # Don't include the compiled files in the target's runfiles; they are
107    # still added to `PyInfo.transitive_pyc_files`. See also:
108    # `py_binary.pyc_collection` attribute. This is useful for allowing
109    # incrementally enabling precompilation on a per-binary basis.
110    DECIDED_ELSEWHERE = "decided_elsewhere",
111)
112
113# Determine if `py_binary` collects transitive pyc files.
114# NOTE: This flag is only respect if `py_binary.pyc_collection` is `inherit`.
115# buildifier: disable=name-conventions
116PycCollectionFlag = enum(
117    # Include `PyInfo.transitive_pyc_files` as part of the binary.
118    INCLUDE_PYC = "include_pyc",
119    # Don't include `PyInfo.transitive_pyc_files` as part of the binary.
120    DISABLED = "disabled",
121)
122