1:::{default-domain} bzl 2::: 3:::{bzl:currentfile} //python/config_settings:BUILD.bazel 4::: 5 6# //python/config_settings 7 8:::{bzl:flag} python_version 9Determines the default hermetic Python toolchain version. This can be set to 10one of the values that `rules_python` maintains. 11::: 12 13::::{bzl:flag} exec_tools_toolchain 14Determines if the {obj}`exec_tools_toolchain_type` toolchain is enabled. 15 16:::{note} 17* Note that this only affects the rules_python generated toolchains. 18::: 19 20Values: 21 22* `enabled`: Allow matching of the registered toolchains at build time. 23* `disabled`: Prevent the toolchain from being matched at build time. 24 25:::{versionadded} 0.33.2 26::: 27:::: 28 29::::{bzl:flag} precompile 30Determines if Python source files should be compiled at build time. 31 32:::{note} 33The flag value is overridden by the target level {attr}`precompile` attribute, 34except for the case of `force_enabled` and `forced_disabled`. 35::: 36 37Values: 38 39* `auto`: (default) Automatically decide the effective value based on environment, 40 target platform, etc. 41* `enabled`: Compile Python source files at build time. Note that 42 {bzl:obj}`--precompile_add_to_runfiles` affects how the compiled files are included into 43 a downstream binary. 44* `disabled`: Don't compile Python source files at build time. 45* `if_generated_source`: Compile Python source files, but only if they're a 46 generated file. 47* `force_enabled`: Like `enabled`, except overrides target-level setting. This 48 is mostly useful for development, testing enabling precompilation more 49 broadly, or as an escape hatch if build-time compiling is not available. 50* `force_disabled`: Like `disabled`, except overrides target-level setting. This 51 is useful useful for development, testing enabling precompilation more 52 broadly, or as an escape hatch if build-time compiling is not available. 53:::{versionadded} 0.33.0 54::: 55:::: 56 57::::{bzl:flag} precompile_source_retention 58Determines, when a source file is compiled, if the source file is kept 59in the resulting output or not. 60 61:::{note} 62This flag is overridden by the target level `precompile_source_retention` 63attribute. 64::: 65 66Values: 67 68* `auto`: (default) Automatically decide the effective value based on environment, 69 target platform, etc. 70* `keep_source`: Include the original Python source. 71* `omit_source`: Don't include the orignal py source. 72* `omit_if_generated_source`: Keep the original source if it's a regular source 73 file, but omit it if it's a generated file. 74 75:::{versionadded} 0.33.0 76::: 77:::{versionadded} 0.36.0 78The `auto` value 79::: 80:::: 81 82::::{bzl:flag} precompile_add_to_runfiles 83Determines if a target adds its compiled files to its runfiles. 84 85When a target compiles its files, but doesn't add them to its own runfiles, it 86relies on a downstream target to retrieve them from 87{bzl:obj}`PyInfo.transitive_pyc_files` 88 89Values: 90* `always`: Always include the compiled files in the target's runfiles. 91* `decided_elsewhere`: Don't include the compiled files in the target's 92 runfiles; they are still added to {bzl:obj}`PyInfo.transitive_pyc_files`. See 93 also: {bzl:obj}`py_binary.pyc_collection` attribute. This is useful for allowing 94 incrementally enabling precompilation on a per-binary basis. 95:::{versionadded} 0.33.0 96::: 97:::: 98 99::::{bzl:flag} pyc_collection 100Determine if `py_binary` collects transitive pyc files. 101 102:::{note} 103This flag is overridden by the target level `pyc_collection` attribute. 104::: 105 106Values: 107* `include_pyc`: Include `PyInfo.transitive_pyc_files` as part of the binary. 108* `disabled`: Don't include `PyInfo.transitive_pyc_files` as part of the binary. 109:::{versionadded} 0.33.0 110::: 111:::: 112 113::::{bzl:flag} py_linux_libc 114Set what libc is used for the target platform. This will affect which whl binaries will be pulled and what toolchain will be auto-detected. Currently `rules_python` only supplies toolchains compatible with `glibc`. 115 116Values: 117* `glibc`: Use `glibc`, default. 118* `muslc`: Use `muslc`. 119:::{versionadded} 0.33.0 120::: 121:::: 122 123::::{bzl:flag} pip_whl 124Set what distributions are used in the `pip` integration. 125 126Values: 127* `auto`: Prefer `whl` distributions if they are compatible with a target 128 platform, but fallback to `sdist`. This is the default. 129* `only`: Only use `whl` distributions and error out if it is not available. 130* `no`: Only use `sdist` distributions. The wheels will be built non-hermetically in the `whl_library` repository rule. 131:::{versionadded} 0.33.0 132::: 133:::: 134 135::::{bzl:flag} pip_whl_osx_arch 136Set what wheel types we should prefer when building on the OSX platform. 137 138Values: 139* `arch`: Prefer architecture specific wheels. 140* `universal`: Prefer universal wheels that usually are bigger and contain binaries for both, Intel and ARM architectures in the same wheel. 141:::{versionadded} 0.33.0 142::: 143:::: 144 145::::{bzl:flag} pip_whl_glibc_version 146Set the minimum `glibc` version that the `py_binary` using `whl` distributions from a PyPI index should support. 147 148Values: 149* `""`: Select the lowest available version of each wheel giving you the maximum compatibility. This is the default. 150* `X.Y`: The string representation of a `glibc` version. The allowed values depend on the `requirements.txt` lock file contents. 151:::{versionadded} 0.33.0 152::: 153:::: 154 155::::{bzl:flag} pip_whl_muslc_version 156Set the minimum `muslc` version that the `py_binary` using `whl` distributions from a PyPI index should support. 157 158Values: 159* `""`: Select the lowest available version of each wheel giving you the maximum compatibility. This is the default. 160* `X.Y`: The string representation of a `muslc` version. The allowed values depend on the `requirements.txt` lock file contents. 161:::{versionadded} 0.33.0 162::: 163:::: 164 165::::{bzl:flag} pip_whl_osx_version 166Set the minimum `osx` version that the `py_binary` using `whl` distributions from a PyPI index should support. 167 168Values: 169* `""`: Select the lowest available version of each wheel giving you the maximum compatibility. This is the default. 170* `X.Y`: The string representation of the MacOS version. The allowed values depend on the `requirements.txt` lock file contents. 171 172:::{versionadded} 0.33.0 173::: 174:::: 175 176::::{bzl:flag} bootstrap_impl 177Determine how programs implement their startup process. 178 179Values: 180* `system_python`: Use a bootstrap that requires a system Python available 181 in order to start programs. This requires 182 {obj}`PyRuntimeInfo.bootstrap_template` to be a Python program. 183* `script`: Use a bootstrap that uses an arbitrary executable script (usually a 184 shell script) instead of requiring it be a Python program. 185 186:::{note} 187The `script` bootstrap requires the toolchain to provide the `PyRuntimeInfo` 188provider from `rules_python`. This loosely translates to using Bazel 7+ with a 189toolchain created by rules_python. Most notably, WORKSPACE builds default to 190using a legacy toolchain built into Bazel itself which doesn't support the 191script bootstrap. If not available, the `system_python` bootstrap will be used 192instead. 193::: 194 195:::{seealso} 196{obj}`PyRuntimeInfo.bootstrap_template` and 197{obj}`PyRuntimeInfo.stage2_bootstrap_template` 198::: 199 200:::{versionadded} 0.33.0 201::: 202 203:::: 204