| # Copyright 2018 The Bazel Authors. All rights reserved. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| |
| """ A library of functions creating structs for CcToolchainConfigInfo.""" |
| |
| def _check_is_none_or_right_type(obj, obj_of_right_type, parameter_name, method_name): |
| if obj != None: |
| _check_right_type(obj, obj_of_right_type, parameter_name, method_name) |
| |
| def _check_right_type(obj, obj_of_right_type, parameter_name, method_name): |
| if type(obj) != type(obj_of_right_type): |
| fail("{} parameter of {} should be a {}, found {}." |
| .format(parameter_name, method_name, type(obj_of_right_type), type(obj))) |
| |
| def _check_is_nonempty_string(obj, parameter_name, method_name): |
| _check_right_type(obj, "", parameter_name, method_name) |
| if obj == "": |
| fail("{} parameter of {} must be a nonempty string." |
| .format(parameter_name, method_name)) |
| |
| def _check_is_nonempty_list(obj, parameter_name, method_name): |
| _check_right_type(obj, [], parameter_name, method_name) |
| if len(obj) == 0: |
| fail("{} parameter of {} must be a nonempty list." |
| .format(parameter_name, method_name)) |
| |
| EnvEntryInfo = provider(fields = ["key", "value", "type_name"]) |
| |
| def env_entry(key, value): |
| """ A key/value pair to be added as an environment variable. |
| |
| The returned EnvEntry provider finds its use in EnvSet creation through |
| the env_entries parameter of env_set(); EnvSet groups environment variables |
| that need to be expanded for specific actions. |
| The value of this pair is expanded in the same way as is described in |
| flag_group. The key remains an unexpanded string literal. |
| |
| Args: |
| key: a string literal representing the name of the variable. |
| value: the value to be expanded. |
| |
| Returns: |
| An EnvEntryInfo provider. |
| """ |
| _check_is_nonempty_string(key, "key", "env_entry") |
| _check_is_nonempty_string(value, "value", "env_entry") |
| return EnvEntryInfo(key = key, value = value, type_name = "env_entry") |
| |
| VariableWithValueInfo = provider(fields = ["name", "value", "type_name"]) |
| |
| def variable_with_value(name, value): |
| """ Represents equality check between a variable and a certain value. |
| |
| The returned provider finds its use through flag_group.expand_if_equal, |
| making the expansion of the flag_group conditional on the value of the |
| variable. |
| |
| Args: |
| name: name of the variable. |
| value: the value the variable should be compared against. |
| |
| Returns: |
| A VariableWithValueInfo provider. |
| """ |
| _check_is_nonempty_string(name, "name", "variable_with_value") |
| _check_is_nonempty_string(value, "value", "variable_with_value") |
| return VariableWithValueInfo( |
| name = name, |
| value = value, |
| type_name = "variable_with_value", |
| ) |
| |
| MakeVariableInfo = provider(fields = ["name", "value", "type_name"]) |
| |
| def make_variable(name, value): |
| """ A make variable that is made accessible to rules.""" |
| _check_is_nonempty_string(name, "name", "make_variable") |
| _check_is_nonempty_string(value, "value", "make_variable") |
| return MakeVariableInfo( |
| name = name, |
| value = value, |
| type_name = "make_variable", |
| ) |
| |
| FeatureSetInfo = provider(fields = ["features", "type_name"]) |
| |
| def feature_set(features = []): |
| """ A set of features. |
| |
| Used to support logical 'and' when specifying feature requirements in a |
| feature. |
| |
| Args: |
| features: A list of unordered feature names. |
| |
| Returns: |
| A FeatureSetInfo provider. |
| """ |
| _check_right_type(features, [], "features", "feature_set") |
| return FeatureSetInfo(features = features, type_name = "feature_set") |
| |
| WithFeatureSetInfo = provider(fields = ["features", "not_features", "type_name"]) |
| |
| def with_feature_set(features = [], not_features = []): |
| """ A set of positive and negative features. |
| |
| This stanza will evaluate to true when every 'feature' is enabled, and |
| every 'not_feature' is not enabled. |
| |
| Args: |
| features: A list of feature names that need to be enabled. |
| not_features: A list of feature names that need to not be enabled. |
| |
| Returns: |
| A WithFeatureSetInfo provider. |
| """ |
| _check_right_type(features, [], "features", "with_feature_set") |
| _check_right_type(not_features, [], "not_features", "with_feature_set") |
| return WithFeatureSetInfo( |
| features = features, |
| not_features = not_features, |
| type_name = "with_feature_set", |
| ) |
| |
| EnvSetInfo = provider(fields = ["actions", "env_entries", "with_features", "type_name"]) |
| |
| def env_set(actions, env_entries = [], with_features = []): |
| """ Groups a set of environment variables to apply for certain actions. |
| |
| EnvSet providers are passed to feature() and action_config(), to be applied to |
| the actions they are specified for. |
| |
| Args: |
| actions: A list of actions this env set applies to; each env set must |
| specify at least one action. |
| env_entries: A list of EnvEntry - the environment variables applied |
| via this env set. |
| with_features: A list of feature sets defining when this env set gets |
| applied. The env set will be applied when any one of the feature |
| sets evaluate to true. (That is, when when every 'feature' is |
| enabled, and every 'not_feature' is not enabled.) |
| If 'with_features' is omitted, the env set will be applied |
| unconditionally for every action specified. |
| |
| Returns: |
| An EnvSetInfo provider. |
| """ |
| _check_is_nonempty_list(actions, "actions", "env_set") |
| _check_right_type(env_entries, [], "env_entries", "env_set") |
| _check_right_type(with_features, [], "with_features", "env_set") |
| return EnvSetInfo( |
| actions = actions, |
| env_entries = env_entries, |
| with_features = with_features, |
| type_name = "env_set", |
| ) |
| |
| FlagGroupInfo = provider(fields = [ |
| "flags", |
| "flag_groups", |
| "iterate_over", |
| "expand_if_available", |
| "expand_if_not_available", |
| "expand_if_true", |
| "expand_if_false", |
| "expand_if_equal", |
| "type_name", |
| ]) |
| |
| def flag_group( |
| flags = [], |
| flag_groups = [], |
| iterate_over = None, |
| expand_if_available = None, |
| expand_if_not_available = None, |
| expand_if_true = None, |
| expand_if_false = None, |
| expand_if_equal = None): |
| """ A group of flags. Supports parametrization via variable expansion. |
| |
| To expand a variable of list type, flag_group has to be annotated with |
| `iterate_over` message. Then all nested flags or flag_groups will be |
| expanded repeatedly for each element of the list. |
| For example: |
| flag_group( |
| iterate_over = 'include_path', |
| flags = ['-I', '%{include_path}'], |
| ) |
| ... will get expanded to -I /to/path1 -I /to/path2 ... for each |
| include_path /to/pathN. |
| |
| To expand a variable of structure type, use dot-notation, e.g.: |
| flag_group( |
| iterate_over = "libraries_to_link", |
| flag_groups = [ |
| flag_group( |
| iterate_over = "libraries_to_link.libraries", |
| flags = ["-L%{libraries_to_link.libraries.directory}"], |
| ) |
| ] |
| ) |
| |
| Flag groups can be nested; if they are, the flag group must only contain |
| other flag groups (no flags) so the order is unambiguously specified. |
| In order to expand a variable of nested lists, 'iterate_over' can be used. |
| For example: |
| flag_group ( |
| iterate_over = 'object_files', |
| flag_groups = [ |
| flag_group ( |
| flags = ['--start-lib'], |
| ), |
| flag_group ( |
| iterate_over = 'object_files', |
| flags = ['%{object_files}'], |
| ), |
| flag_group ( |
| flags = ['--end-lib'], |
| ) |
| ] |
| ) |
| ... will get expanded to |
| --start-lib a1.o a2.o ... --end-lib --start-lib b1.o b2.o .. --end-lib |
| with %{object_files} being a variable of nested list type |
| [['a1.o', 'a2.o', ...], ['b1.o', 'b2.o', ...], ...]. |
| |
| Args: |
| flags: a string list, representing flags. Only one of flags and |
| flag_groups can be set, as to avoid ambiguity. |
| flag_groups: a list of FlagGroup entries. Only one of flags and |
| flag_groups can be set, as to avoid ambiguity. |
| iterate_over: a string, representing a variable of list type. |
| expand_if_available: A build variable that needs to be available |
| in order to expand the flag_group. |
| expand_if_not_available: A build variable that needs to be |
| unavailable in order for this flag_group to be expanded. |
| expand_if_true: if set, this variable needs to evaluate to True in |
| order for the flag_group to be expanded. |
| expand_if_false: if set, this variable needs to evalate to False in |
| order for the flag_group to be expanded. |
| expand_if_equal: a VariableWithValue, the flag_group is expanded in |
| case of equality. |
| |
| Returns: |
| A FlagGroupInfo provider. |
| """ |
| |
| _check_right_type(flags, [], "flags", "flag_group") |
| _check_right_type(flag_groups, [], "flag_groups", "flag_group") |
| if len(flags) > 0 and len(flag_groups) > 0: |
| fail("flag_group must not contain both a flag and another flag_group.") |
| if len(flags) == 0 and len(flag_groups) == 0: |
| fail("flag_group must contain either a list of flags or a list of flag_groups.") |
| _check_is_none_or_right_type(expand_if_true, "string", "expand_if_true", "flag_group") |
| _check_is_none_or_right_type(expand_if_false, "string", "expand_if_false", "flag_group") |
| _check_is_none_or_right_type(expand_if_available, "string", "expand_if_available", "flag_group") |
| _check_is_none_or_right_type( |
| expand_if_not_available, |
| "string", |
| "expand_if_not_available", |
| "flag_group", |
| ) |
| _check_is_none_or_right_type(iterate_over, "string", "iterate_over", "flag_group") |
| |
| return FlagGroupInfo( |
| flags = flags, |
| flag_groups = flag_groups, |
| iterate_over = iterate_over, |
| expand_if_available = expand_if_available, |
| expand_if_not_available = expand_if_not_available, |
| expand_if_true = expand_if_true, |
| expand_if_false = expand_if_false, |
| expand_if_equal = expand_if_equal, |
| type_name = "flag_group", |
| ) |
| |
| FlagSetInfo = provider(fields = [ |
| "actions", |
| "with_features", |
| "flag_groups", |
| "type_name", |
| ]) |
| |
| def flag_set( |
| actions = [], |
| with_features = [], |
| flag_groups = []): |
| """ A set of flags to be expanded in the command line for specific actions. |
| |
| Args: |
| actions: The actions this flag set applies to; each flag set must |
| specify at least one action. |
| with_features: A list of feature sets defining when this flag set gets |
| applied. The flag set will be applied when any one of the feature |
| sets evaluate to true. (That is, when when every 'feature' is |
| enabled, and every 'not_feature' is not enabled.) |
| If 'with_feature' is omitted, the flag set will be applied |
| unconditionally for every action specified. |
| flag_groups: A FlagGroup list - the flags applied via this flag set. |
| |
| Returns: |
| A FlagSetInfo provider. |
| """ |
| _check_right_type(actions, [], "actions", "flag_set") |
| _check_right_type(with_features, [], "with_features", "flag_set") |
| _check_right_type(flag_groups, [], "flag_groups", "flag_set") |
| return FlagSetInfo( |
| actions = actions, |
| with_features = with_features, |
| flag_groups = flag_groups, |
| type_name = "flag_set", |
| ) |
| |
| FeatureInfo = provider(fields = [ |
| "name", |
| "enabled", |
| "flag_sets", |
| "env_sets", |
| "requires", |
| "implies", |
| "provides", |
| "type_name", |
| ]) |
| |
| def feature( |
| name, |
| enabled = False, |
| flag_sets = [], |
| env_sets = [], |
| requires = [], |
| implies = [], |
| provides = []): |
| """ Contains all flag specifications for one feature. |
| |
| Args: |
| name: The feature's name. It is possible to introduce a feature without |
| a change to Bazel by adding a 'feature' section to the toolchain |
| and adding the corresponding string as feature in the BUILD file. |
| enabled: If 'True', this feature is enabled unless a rule type |
| explicitly marks it as unsupported. |
| flag_sets: A FlagSet list - If the given feature is enabled, the flag |
| sets will be applied for the actions are specified for. |
| env_sets: an EnvSet list - If the given feature is enabled, the env |
| sets will be applied for the actions they are specified for. |
| requires: A list of feature sets defining when this feature is |
| supported by the toolchain. The feature is supported if any of the |
| feature sets fully apply, that is, when all features of a feature |
| set are enabled. |
| If 'requires' is omitted, the feature is supported independently of |
| which other features are enabled. |
| Use this for example to filter flags depending on the build mode |
| enabled (opt / fastbuild / dbg). |
| implies: A string list of features or action configs that are |
| automatically enabled when this feature is enabled. If any of the |
| implied features or action configs cannot be enabled, this feature |
| will (silently) not be enabled either. |
| provides: A list of names this feature conflicts with. |
| A feature cannot be enabled if: |
| - 'provides' contains the name of a different feature or action |
| config that we want to enable. |
| - 'provides' contains the same value as a 'provides' in a |
| different feature or action config that we want to enable. |
| Use this in order to ensure that incompatible features cannot be |
| accidentally activated at the same time, leading to hard to |
| diagnose compiler errors. |
| |
| Returns: |
| A FeatureInfo provider. |
| """ |
| _check_right_type(enabled, True, "enabled", "feature") |
| _check_right_type(flag_sets, [], "flag_sets", "feature") |
| _check_right_type(env_sets, [], "env_sets", "feature") |
| _check_right_type(requires, [], "requires", "feature") |
| _check_right_type(provides, [], "provides", "feature") |
| _check_right_type(implies, [], "implies", "feature") |
| return FeatureInfo( |
| name = name, |
| enabled = enabled, |
| flag_sets = flag_sets, |
| env_sets = env_sets, |
| requires = requires, |
| implies = implies, |
| provides = provides, |
| type_name = "feature", |
| ) |
| |
| ToolPathInfo = provider(fields = ["name", "path", "type_name"]) |
| |
| def tool_path(name, path): |
| """ Tool locations. |
| |
| Args: |
| name: Name of the tool. |
| path: Location of the tool; Can be absolute path (in case of non hermetic |
| toolchain), or path relative to the cc_toolchain's package. |
| |
| Returns: |
| A ToolPathInfo provider. |
| |
| Deprecated: |
| Prefer specifying an ActionConfig for the action that needs the tool. |
| TODO(b/27903698) migrate to ActionConfig. |
| """ |
| _check_is_nonempty_string(name, "name", "tool_path") |
| _check_is_nonempty_string(path, "path", "tool_path") |
| return ToolPathInfo(name = name, path = path, type_name = "tool_path") |
| |
| ToolInfo = provider(fields = ["path", "with_features", "execution_requirements", "type_name"]) |
| |
| def tool(path, with_features = [], execution_requirements = []): |
| """ Describes a tool associated with a crosstool action config. |
| |
| Args: |
| path: Location of the tool; Can be absolute path (in case of non hermetic |
| toolchain), or path relative to the cc_toolchain's package. |
| with_features: A list of feature sets defining when this tool is |
| applicable. The tool will used when any one of the feature sets |
| evaluate to true. (That is, when when every 'feature' is enabled, |
| and every 'not_feature' is not enabled.) |
| If 'with_feature' is omitted, the tool will apply for any feature |
| configuration. |
| execution_requirements: Requirements on the execution environment for |
| the execution of this tool, to be passed as out-of-band "hints" to |
| the execution backend. |
| Ex. "requires-darwin" |
| |
| Returns: |
| A ToolInfo provider. |
| """ |
| _check_is_nonempty_string(path, "path", "tool") |
| _check_right_type(with_features, [], "with_features", "tool") |
| _check_right_type(execution_requirements, [], "execution_requirements", "tool") |
| return ToolInfo( |
| path = path, |
| with_features = with_features, |
| execution_requirements = execution_requirements, |
| type_name = "tool", |
| ) |
| |
| ActionConfigInfo = provider(fields = [ |
| "config_name", |
| "action_name", |
| "enabled", |
| "tools", |
| "flag_sets", |
| "implies", |
| "type_name", |
| ]) |
| |
| def action_config( |
| action_name, |
| enabled = False, |
| tools = [], |
| flag_sets = [], |
| implies = []): |
| """ Configuration of a Bazel action. |
| |
| An action config corresponds to a Bazel action, and allows selection of |
| a tool based on activated features. |
| Action config activation occurs by the same semantics as features: a |
| feature can 'require' or 'imply' an action config in the same way that it |
| would another feature. |
| |
| Args: |
| action_name: The name of the Bazel action that this config applies to, |
| ex. 'c-compile' or 'c-module-compile'. |
| enabled: If 'True', this action is enabled unless a rule type |
| explicitly marks it as unsupported. |
| tools: The tool applied to the action will be the first Tool with a |
| feature set that matches the feature configuration. An error will |
| be thrown if no tool matches a provided feature configuration - for |
| that reason, it's a good idea to provide a default tool with an |
| empty feature set. |
| flag_sets: If the given action config is enabled, the flag sets will be |
| applied to the corresponding action. |
| implies: A list of features or action configs that are automatically |
| enabled when this action config is enabled. If any of the implied |
| features or action configs cannot be enabled, this action config |
| will (silently) not be enabled either. |
| |
| Returns: |
| An ActionConfigInfo provider. |
| """ |
| _check_is_nonempty_string(action_name, "name", "action_config") |
| _check_right_type(enabled, True, "enabled", "action_config") |
| _check_right_type(tools, [], "tools", "action_config") |
| _check_right_type(flag_sets, [], "flag_sets", "action_config") |
| _check_right_type(implies, [], "implies", "action_config") |
| return ActionConfigInfo( |
| action_name = action_name, |
| enabled = enabled, |
| tools = tools, |
| flag_sets = flag_sets, |
| implies = implies, |
| type_name = "action_config", |
| ) |
| |
| ArtifactNamePatternInfo = provider(fields = [ |
| "category_name", |
| "prefix", |
| "extension", |
| "type_name", |
| ]) |
| |
| def artifact_name_pattern(category_name, prefix, extension): |
| """ The name for an artifact of a given category of input or output artifacts to an action. |
| |
| Args: |
| category_name: The category of artifacts that this selection applies |
| to. This field is compared against a list of categories defined |
| in bazel. Example categories include "linked_output" or |
| "debug_symbols". An error is thrown if no category is matched. |
| prefix: The prefix for creating the artifact for this selection. |
| Together with the extension it is used to create an artifact name |
| based on the target name. |
| extension: The extension for creating the artifact for this selection. |
| Together with the prefix it is used to create an artifact name |
| based on the target name. |
| |
| Returns: |
| An ArtifactNamePatternInfo provider |
| """ |
| _check_is_nonempty_string(category_name, "category_name", "artifact_name_pattern") |
| _check_is_none_or_right_type(prefix, "", "prefix", "artifact_name_pattern") |
| _check_is_none_or_right_type(extension, "", "extension", "artifact_name_pattern") |
| return ArtifactNamePatternInfo( |
| category_name = category_name, |
| prefix = prefix, |
| extension = extension, |
| type_name = "artifact_name_pattern", |
| ) |
