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"""Implementation of the exec tools toolchain provider.""" 15 16PyExecToolsInfo = provider( 17 doc = "Build tools used as part of building Python programs.", 18 fields = { 19 "exec_interpreter": """ 20:type: Target | None 21 22If available, an interpreter valid for running in the exec configuration. 23When running it in an action, use `DefaultInfo.files_to_run` to ensure all its 24files are appropriately available. An exec interpreter may not be available, 25e.g. if all the exec tools are prebuilt binaries. 26 27NOTE: this interpreter is really only for use when a build tool cannot use 28the Python toolchain itself. When possible, prefeer to define a `py_binary` 29instead and use it via a `cfg=exec` attribute; this makes it much easier 30to setup the runtime environment for the binary. See also: 31`py_interpreter_program` rule. 32 33NOTE: What interpreter is used depends on the toolchain constraints. Ensure 34the proper target constraints are being applied when obtaining this from 35the toolchain. 36""", 37 "precompiler": """ 38:type: Target | None 39 40If available, the tool to use for generating pyc files. If not available, 41precompiling will not be available. 42 43Must provide one of the following: 44 * PyInterpreterProgramInfo 45 * DefaultInfo.files_to_run 46 47This target provides either the `PyInterpreterProgramInfo` provider or is a 48regular executable binary (provides DefaultInfo.files_to_run). When the 49`PyInterpreterProgramInfo` provider is present, it means the precompiler program 50doesn't know how to find the interpreter itself, so the caller must provide it 51when constructing the action invocation for running the precompiler program 52(typically `exec_interpreter`). See the `PyInterpreterProgramInfo` provider docs 53for details on how to construct an invocation. 54 55If {obj}`testing.ExecutionInfo` is provided, it will be used to set execution 56requirements. This can be used to control persistent worker settings. 57 58The precompiler command line API is: 59* `--invalidation_mode`: The type of pyc invalidation mode to use. Should be 60 one of `unchecked_hash` or `checked_hash`. 61* `--optimize`: The optimization level as an integer. 62* `--python_version`: The Python version, in `Major.Minor` format, e.g. `3.12` 63 64The following args are repeated and form a list of 3-tuples of their values. At 65least one 3-tuple will be passed. 66* `--src`: Path to the source `.py` file to precompile. 67* `--src_name`: The human-friendly file name to record in the pyc output. 68* `--pyc`: Path to where pyc output should be written. 69 70NOTE: These arguments _may_ be stored in a file instead, in which case, the 71path to that file will be a positional arg starting with `@`, e.g. `@foo/bar`. 72The format of the file is one arg per line. 73""", 74 }, 75) 76