| // 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. |
| |
| package com.google.devtools.build.lib.skylarkbuildapi.cpp; |
| |
| import com.google.devtools.build.lib.cmdline.Label; |
| import com.google.devtools.build.lib.collect.nestedset.Depset; |
| import com.google.devtools.build.lib.skylarkbuildapi.FileApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.StarlarkActionFactoryApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.StarlarkRuleContextApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.core.ProviderApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.platform.ConstraintValueInfoApi; |
| import com.google.devtools.build.lib.syntax.Dict; |
| import com.google.devtools.build.lib.syntax.EvalException; |
| import com.google.devtools.build.lib.syntax.NoneType; |
| import com.google.devtools.build.lib.syntax.Sequence; |
| import com.google.devtools.build.lib.syntax.StarlarkSemantics.FlagIdentifier; |
| import com.google.devtools.build.lib.syntax.StarlarkThread; |
| import com.google.devtools.build.lib.syntax.StarlarkValue; |
| import com.google.devtools.build.lib.syntax.Tuple; |
| import net.starlark.java.annot.Param; |
| import net.starlark.java.annot.ParamType; |
| import net.starlark.java.annot.StarlarkBuiltin; |
| import net.starlark.java.annot.StarlarkMethod; |
| |
| /** Utilites related to C++ support. */ |
| @StarlarkBuiltin( |
| name = "cc_common", |
| doc = "Utilities for C++ compilation, linking, and command line generation.") |
| public interface CcModuleApi< |
| StarlarkActionFactoryT extends StarlarkActionFactoryApi, |
| FileT extends FileApi, |
| CcToolchainProviderT extends CcToolchainProviderApi<?>, |
| FeatureConfigurationT extends FeatureConfigurationApi, |
| CompilationContextT extends CcCompilationContextApi<FileT>, |
| LinkerInputT extends LinkerInputApi<LibraryToLinkT, FileT>, |
| LinkingContextT extends CcLinkingContextApi<?>, |
| LibraryToLinkT extends LibraryToLinkApi<FileT>, |
| CcToolchainVariablesT extends CcToolchainVariablesApi, |
| ConstraintValueT extends ConstraintValueInfoApi, |
| StarlarkRuleContextT extends StarlarkRuleContextApi<ConstraintValueT>, |
| CcToolchainConfigInfoT extends CcToolchainConfigInfoApi, |
| CompilationOutputsT extends CcCompilationOutputsApi<FileT>> |
| extends StarlarkValue { |
| |
| @StarlarkMethod( |
| name = "CcToolchainInfo", |
| doc = |
| "The key used to retrieve the provider that contains information about the C++ " |
| + "toolchain being used", |
| structField = true) |
| ProviderApi getCcToolchainProvider(); |
| |
| @Deprecated |
| @StarlarkMethod( |
| name = "do_not_use_tools_cpp_compiler_present", |
| doc = |
| "Do not use this field, its only puprose is to help with migration from " |
| + "config_setting.values{'compiler') to " |
| + "config_settings.flag_values{'@bazel_tools//tools/cpp:compiler'}", |
| structField = true) |
| default void compilerFlagExists() {} |
| |
| @StarlarkMethod( |
| name = "configure_features", |
| doc = "Creates a feature_configuration instance. Requires the cpp configuration fragment.", |
| parameters = { |
| @Param( |
| name = "ctx", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| type = StarlarkRuleContextApi.class, |
| doc = "The rule context."), |
| @Param( |
| name = "cc_toolchain", |
| doc = "cc_toolchain for which we configure features.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class), |
| @Param( |
| name = "requested_features", |
| doc = "List of features to be enabled.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| @Param( |
| name = "unsupported_features", |
| doc = "List of features that are unsupported by the current rule.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| }) |
| FeatureConfigurationT configureFeatures( |
| Object ruleContextOrNone, |
| CcToolchainProviderT toolchain, |
| Sequence<?> requestedFeatures, // <String> expected |
| Sequence<?> unsupportedFeatures) // <String> expected |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "get_tool_for_action", |
| doc = "Returns tool path for given action.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "action_name", |
| doc = |
| "Name of the action. Has to be one of the names in " |
| + "@bazel_tools//tools/build_defs/cc:action_names.bzl " |
| + "(https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/" |
| + "action_names.bzl)", |
| named = true, |
| positional = false), |
| }) |
| String getToolForAction(FeatureConfigurationT featureConfiguration, String actionName); |
| |
| @StarlarkMethod( |
| name = "get_execution_requirements", |
| doc = "Returns execution requirements for given action.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "action_name", |
| doc = |
| "Name of the action. Has to be one of the names in " |
| + "@bazel_tools//tools/build_defs/cc:action_names.bzl " |
| + "(https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/" |
| + "action_names.bzl)", |
| named = true, |
| positional = false), |
| }) |
| Sequence<String> getExecutionRequirements( |
| FeatureConfigurationT featureConfiguration, String actionName); |
| |
| @StarlarkMethod( |
| name = "is_enabled", |
| doc = "Returns True if given feature is enabled in the feature configuration.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "feature_name", |
| doc = "Name of the feature.", |
| named = true, |
| positional = false), |
| }) |
| boolean isEnabled(FeatureConfigurationT featureConfiguration, String featureName); |
| |
| @StarlarkMethod( |
| name = "action_is_enabled", |
| doc = "Returns True if given action_config is enabled in the feature configuration.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "action_name", |
| doc = "Name of the action_config.", |
| named = true, |
| positional = false), |
| }) |
| boolean actionIsEnabled(FeatureConfigurationT featureConfiguration, String actionName); |
| |
| @StarlarkMethod( |
| name = "get_memory_inefficient_command_line", |
| doc = |
| "Returns flattened command line flags for given action, using given variables for " |
| + "expansion. Flattens nested sets and ideally should not be used, or at least " |
| + "should not outlive analysis. Work on memory efficient function returning Args is " |
| + "ongoing.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "action_name", |
| doc = |
| "Name of the action. Has to be one of the names in " |
| + "@bazel_tools//tools/build_defs/cc:action_names.bzl " |
| + "(https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/" |
| + "action_names.bzl)", |
| named = true, |
| positional = false), |
| @Param( |
| name = "variables", |
| doc = "Build variables to be used for template expansions.", |
| named = true, |
| positional = false, |
| type = CcToolchainVariablesApi.class), |
| }) |
| Sequence<String> getCommandLine( |
| FeatureConfigurationT featureConfiguration, |
| String actionName, |
| CcToolchainVariablesT variables) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "get_environment_variables", |
| doc = "Returns environment variables to be set for given action.", |
| parameters = { |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "action_name", |
| doc = |
| "Name of the action. Has to be one of the names in " |
| + "@bazel_tools//tools/build_defs/cc:action_names.bzl " |
| + "(https://github.com/bazelbuild/bazel/blob/master/tools/build_defs/cc/" |
| + "action_names.bzl)", |
| named = true, |
| positional = false), |
| @Param( |
| name = "variables", |
| doc = "Build variables to be used for template expansion.", |
| positional = false, |
| named = true, |
| type = CcToolchainVariablesApi.class), |
| }) |
| Dict<String, String> getEnvironmentVariable( |
| FeatureConfigurationT featureConfiguration, |
| String actionName, |
| CcToolchainVariablesT variables) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "create_compile_variables", |
| doc = "Returns variables used for compilation actions.", |
| parameters = { |
| @Param( |
| name = "cc_toolchain", |
| doc = "cc_toolchain for which we are creating build variables.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class), |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "source_file", |
| doc = |
| "Optional source file for the compilation. Please prefer passing source_file here " |
| + "over appending it to the end of the command line generated from " |
| + "cc_common.get_memory_inefficient_command_line, as then it's in the power of " |
| + "the toolchain author to properly specify and position compiler flags.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true), |
| @Param( |
| name = "output_file", |
| doc = |
| "Optional output file of the compilation. Please prefer passing output_file here " |
| + "over appending it to the end of the command line generated from " |
| + "cc_common.get_memory_inefficient_command_line, as then it's in the power of " |
| + "the toolchain author to properly specify and position compiler flags.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true), |
| @Param( |
| name = "user_compile_flags", |
| doc = "List of additional compilation flags (copts).", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = { |
| @ParamType(type = NoneType.class), |
| @ParamType(type = Sequence.class), |
| }), |
| @Param( |
| name = "include_directories", |
| doc = "Depset of include directories.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "quote_include_directories", |
| doc = "Depset of quote include directories.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "system_include_directories", |
| doc = "Depset of system include directories.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "framework_include_directories", |
| doc = "Depset of framework include directories.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "preprocessor_defines", |
| doc = "Depset of preprocessor defines.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "thinlto_index", |
| doc = "LTO index file path.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = String.class)}), |
| @Param( |
| name = "thinlto_input_bitcode_file", |
| doc = "Bitcode file that is input to LTO backend.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = String.class)}), |
| @Param( |
| name = "thinlto_output_object_file", |
| doc = "Object file that is output by LTO backend.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = String.class)}), |
| @Param( |
| name = "use_pic", |
| doc = "When true the compilation will generate position independent code.", |
| positional = false, |
| named = true, |
| defaultValue = "False"), |
| // TODO(b/65151735): Remove once we migrate crosstools to features |
| @Param( |
| name = "add_legacy_cxx_options", |
| doc = "Unused.", |
| named = true, |
| positional = false, |
| defaultValue = "False") |
| }) |
| CcToolchainVariablesT getCompileBuildVariables( |
| CcToolchainProviderT ccToolchainProvider, |
| FeatureConfigurationT featureConfiguration, |
| Object sourceFile, |
| Object outputFile, |
| Object userCompileFlags, |
| Object includeDirs, |
| Object quoteIncludeDirs, |
| Object systemIncludeDirs, |
| Object frameworkIncludeDirs, |
| Object defines, |
| Object thinLtoIndex, |
| Object thinLtoInputBitcodeFile, |
| Object thinLtoOutputObjectFile, |
| boolean usePic, |
| boolean addLegacyCxxOptions) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "create_link_variables", |
| doc = "Returns link variables used for linking actions.", |
| parameters = { |
| @Param( |
| name = "cc_toolchain", |
| doc = "cc_toolchain for which we are creating build variables.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class), |
| @Param( |
| name = "feature_configuration", |
| doc = "Feature configuration to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "library_search_directories", |
| doc = "Depset of directories where linker will look for libraries at link time.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "runtime_library_search_directories", |
| doc = "Depset of directories where loader will look for libraries at runtime.", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "user_link_flags", |
| doc = "List of additional link flags (linkopts).", |
| positional = false, |
| named = true, |
| defaultValue = "None", |
| noneable = true, |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Sequence.class)}), |
| @Param( |
| name = "output_file", |
| doc = "Optional output file path.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true), |
| @Param( |
| name = "param_file", |
| doc = "Optional param file path.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true), |
| @Param( |
| name = "def_file", |
| doc = "Optional .def file path.", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| noneable = true), |
| // TODO(b/65151735): Remove once we migrate crosstools to features |
| @Param( |
| name = "is_using_linker", |
| doc = |
| "True when using linker, False when archiver. Caller is responsible for keeping " |
| + "this in sync with action name used (is_using_linker = True for linking " |
| + "executable or dynamic library, is_using_linker = False for archiving static " |
| + "library).", |
| named = true, |
| positional = false, |
| defaultValue = "True"), |
| // TODO(b/65151735): Remove once we migrate crosstools to features |
| @Param( |
| name = "is_linking_dynamic_library", |
| doc = |
| "True when creating dynamic library, False when executable or static library. " |
| + "Caller is responsible for keeping this in sync with action name used. " |
| + "" |
| + "This field will be removed once b/65151735 is fixed.", |
| named = true, |
| positional = false, |
| defaultValue = "False"), |
| @Param( |
| name = "must_keep_debug", |
| doc = |
| "When set to True, bazel will expose 'strip_debug_symbols' variable, which is " |
| + "usually used to use the linker to strip debug symbols from the output file.", |
| named = true, |
| positional = false, |
| defaultValue = "True"), |
| @Param( |
| name = "use_test_only_flags", |
| doc = "When set to true, 'is_cc_test' variable will be set.", |
| named = true, |
| positional = false, |
| defaultValue = "False"), |
| // TODO(b/65151735): Remove once we migrate crosstools to features |
| @Param( |
| name = "is_static_linking_mode", |
| doc = "Unused.", |
| named = true, |
| positional = false, |
| defaultValue = "True"), |
| }) |
| CcToolchainVariablesT getLinkBuildVariables( |
| CcToolchainProviderT ccToolchainProvider, |
| FeatureConfigurationT featureConfiguration, |
| Object librarySearchDirectories, |
| Object runtimeLibrarySearchDirectories, |
| Object userLinkFlags, |
| Object outputFile, |
| Object paramFile, |
| Object defFile, |
| boolean isUsingLinkerNotArchiver, |
| boolean isCreatingSharedLibrary, |
| boolean mustKeepDebug, |
| boolean useTestOnlyFlags, |
| boolean isStaticLinkingMode) |
| throws EvalException; |
| |
| @StarlarkMethod(name = "empty_variables", documented = false) |
| CcToolchainVariablesT getVariables(); |
| |
| @StarlarkMethod( |
| name = "create_library_to_link", |
| doc = "Creates <code>LibraryToLink</code>", |
| useStarlarkThread = true, |
| parameters = { |
| @Param( |
| name = "actions", |
| type = StarlarkActionFactoryApi.class, |
| positional = false, |
| named = true, |
| doc = "<code>actions</code> object."), |
| @Param( |
| name = "feature_configuration", |
| doc = "<code>feature_configuration</code> to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "cc_toolchain", |
| doc = "<code>CcToolchainInfo</code> provider to be used.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class), |
| @Param( |
| name = "static_library", |
| doc = "<code>File</code> of static library to be linked.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| type = FileApi.class), |
| @Param( |
| name = "pic_static_library", |
| doc = "<code>File</code> of pic static library to be linked.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| type = FileApi.class), |
| @Param( |
| name = "dynamic_library", |
| doc = |
| "<code>File</code> of dynamic library to be linked. Always used for runtime " |
| + "and used for linking if <code>interface_library</code> is not passed.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| type = FileApi.class), |
| @Param( |
| name = "interface_library", |
| doc = "<code>File</code> of interface library to be linked.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| type = FileApi.class), |
| @Param( |
| name = "alwayslink", |
| doc = "Whether to link the static library/objects in the --whole_archive block.", |
| positional = false, |
| named = true, |
| defaultValue = "False"), |
| @Param( |
| name = "dynamic_library_symlink_path", |
| doc = |
| "Override the default path of the dynamic library link in the solib directory. " |
| + "Empty string to use the default.", |
| positional = false, |
| named = true, |
| type = String.class, |
| defaultValue = "''"), |
| @Param( |
| name = "interface_library_symlink_path", |
| doc = |
| "Override the default path of the interface library link in the solib directory. " |
| + "Empty string to use the default.", |
| positional = false, |
| named = true, |
| type = String.class, |
| defaultValue = "''"), |
| }) |
| LibraryToLinkT createLibraryLinkerInput( |
| Object actions, |
| Object featureConfiguration, |
| Object ccToolchainProvider, |
| Object staticLibrary, |
| Object picStaticLibrary, |
| Object dynamicLibrary, |
| Object interfaceLibrary, |
| boolean alwayslink, |
| String dynamicLibraryPath, |
| String interfaceLibraryPath, |
| StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "create_linker_input", |
| doc = "Creates a <code>LinkingContext</code>.", |
| useStarlarkThread = true, |
| parameters = { |
| @Param( |
| name = "owner", |
| doc = "The label of the target that produced all files used in this input.", |
| positional = false, |
| named = true, |
| type = Label.class), |
| @Param( |
| name = "libraries", |
| doc = "List of <code>LibraryToLink</code>.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "user_link_flags", |
| doc = "List of user link flags passed as strings.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "additional_inputs", |
| doc = "For additional inputs to the linking action, e.g.: linking scripts.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| }) |
| LinkerInputT createLinkerInput( |
| Label owner, |
| Object librariesToLinkObject, |
| Object userLinkFlagsObject, |
| Object nonCodeInputs, |
| StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "check_experimental_cc_shared_library", |
| doc = "DO NOT USE. This is to guard use of cc_shared_library.", |
| useStarlarkThread = true, |
| documented = false) |
| void checkExperimentalCcSharedLibrary(StarlarkThread thread) throws EvalException; |
| |
| @StarlarkMethod( |
| name = "check_experimental_starlark_cc_import", |
| doc = "DO NOT USE. This is to guard use of cc_import.bzl", |
| documented = false, |
| parameters = { |
| @Param( |
| name = "actions", |
| type = StarlarkActionFactoryApi.class, |
| positional = false, |
| named = true, |
| doc = "<code>actions</code> object."), |
| }) |
| void checkExperimentalStarlarkCcImport(StarlarkActionFactoryT starlarkActionFactoryApi) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "create_linking_context", |
| doc = "Creates a <code>LinkingContext</code>.", |
| useStarlarkThread = true, |
| parameters = { |
| @Param( |
| name = "linker_inputs", |
| doc = "Depset of <code>LinkerInput</code>.", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Depset.class)}), |
| @Param( |
| name = "libraries_to_link", |
| doc = "List of <code>LibraryToLink</code>.", |
| positional = false, |
| named = true, |
| disableWithFlag = FlagIdentifier.INCOMPATIBLE_REQUIRE_LINKER_INPUT_CC_API, |
| noneable = true, |
| defaultValue = "None", |
| valueWhenDisabled = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Sequence.class)}), |
| @Param( |
| name = "user_link_flags", |
| doc = "List of user link flags passed as strings.", |
| positional = false, |
| named = true, |
| disableWithFlag = FlagIdentifier.INCOMPATIBLE_REQUIRE_LINKER_INPUT_CC_API, |
| noneable = true, |
| defaultValue = "None", |
| valueWhenDisabled = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Sequence.class)}), |
| @Param( |
| name = "additional_inputs", |
| doc = "For additional inputs to the linking action, e.g.: linking scripts.", |
| positional = false, |
| named = true, |
| disableWithFlag = FlagIdentifier.INCOMPATIBLE_REQUIRE_LINKER_INPUT_CC_API, |
| noneable = true, |
| defaultValue = "None", |
| valueWhenDisabled = "None", |
| allowedTypes = {@ParamType(type = NoneType.class), @ParamType(type = Sequence.class)}), |
| }) |
| LinkingContextT createCcLinkingInfo( |
| Object linkerInputs, |
| Object librariesToLinkObject, |
| Object userLinkFlagsObject, |
| Object nonCodeInputs, // <FileT> expected |
| StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "merge_cc_infos", |
| doc = "Merges multiple <code>CcInfo</code>s into one.", |
| parameters = { |
| @Param( |
| name = "direct_cc_infos", |
| doc = |
| "List of <code>CcInfo</code>s to be merged, whose headers will be exported by " |
| + "the direct fields in the returned provider.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| @Param( |
| name = "cc_infos", |
| doc = |
| "List of <code>CcInfo</code>s to be merged, whose headers will not be exported " |
| + "by the direct fields in the returned provider.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class) |
| }) |
| CcInfoApi<FileT> mergeCcInfos( |
| Sequence<?> directCcInfos, // <CcInfoApi> expected |
| Sequence<?> ccInfos) // <CcInfoApi> expected |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "create_compilation_context", |
| doc = "Creates a <code>CompilationContext</code>.", |
| parameters = { |
| @Param( |
| name = "headers", |
| doc = "Set of headers needed to compile this target", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "system_includes", |
| doc = |
| "Set of search paths for header files referenced by angle brackets, i.e. " |
| + "#include <foo/bar/header.h>. They can be either relative to the exec " |
| + "root or absolute. Usually passed with -isystem", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "includes", |
| doc = |
| "Set of search paths for header files referenced both by angle bracket and quotes." |
| + "Usually passed with -I", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "quote_includes", |
| doc = |
| "Set of search paths for header files referenced by quotes, i.e. " |
| + "#include \"foo/bar/header.h\". They can be either relative to the exec " |
| + "root or absolute. Usually passed with -iquote", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "framework_includes", |
| doc = "Set of framework search paths for header files (Apple platform only)", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "defines", |
| doc = |
| "Set of defines needed to compile this target. Each define is a string. Propagated" |
| + " transitively to dependents.", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| @Param( |
| name = "local_defines", |
| doc = |
| "Set of defines needed to compile this target. Each define is a string. Not" |
| + " propagated transitively to dependents.", |
| positional = false, |
| named = true, |
| defaultValue = "unbound", |
| type = Object.class), |
| }) |
| CompilationContextT createCcCompilationContext( |
| Object headers, |
| Object systemIncludes, |
| Object includes, |
| Object quoteIncludes, |
| Object frameworkIncludes, |
| Object defines, |
| Object localDefines) |
| throws EvalException; |
| |
| // TODO(b/65151735): Remove when cc_flags is entirely set from features. |
| // This should only be called from the cc_flags_supplier rule. |
| @StarlarkMethod( |
| name = "legacy_cc_flags_make_variable_do_not_use", |
| documented = false, |
| parameters = { |
| @Param( |
| name = "cc_toolchain", |
| doc = "C++ toolchain provider to be used.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class) |
| }) |
| String legacyCcFlagsMakeVariable(CcToolchainProviderT ccToolchain); |
| |
| @StarlarkMethod( |
| name = "is_cc_toolchain_resolution_enabled_do_not_use", |
| documented = false, |
| parameters = { |
| @Param( |
| name = "ctx", |
| positional = false, |
| named = true, |
| type = StarlarkRuleContextApi.class, |
| doc = "The rule context."), |
| }, |
| doc = "Returns true if the --incompatible_enable_cc_toolchain_resolution flag is enabled.") |
| boolean isCcToolchainResolutionEnabled(StarlarkRuleContextT ruleContext); |
| |
| @StarlarkMethod( |
| name = "create_cc_toolchain_config_info", |
| doc = "Creates a <code>CcToolchainConfigInfo</code> provider", |
| parameters = { |
| @Param( |
| name = "ctx", |
| positional = false, |
| named = true, |
| type = StarlarkRuleContextApi.class, |
| doc = "The rule context."), |
| @Param( |
| name = "features", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "A list of <a href=\"https://github.com/bazelbuild/bazel/blob/master/tools/cpp/" |
| + "cc_toolchain_config_lib.bzl#L336\">features</a>."), |
| @Param( |
| name = "action_configs", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "A list of <a href=\"https://github.com/bazelbuild/bazel/blob/master/tools/cpp/" |
| + "cc_toolchain_config_lib.bzl#L461\">action_configs</a>."), |
| @Param( |
| name = "artifact_name_patterns", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "A list of <a href=\"https://github.com/bazelbuild/bazel/blob/master/tools/cpp/" |
| + "cc_toolchain_config_lib.bzl#L516\">artifact_name_patterns</a>."), |
| @Param( |
| name = "cxx_builtin_include_directories", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "<p>Built-in include directories for C++ compilation. These should be the exact " |
| + "paths used by the compiler, and are generally relative to the exec root.</p>" |
| + "<p>The paths used by the compiler can be determined by 'gcc -E -xc++ - -v'." |
| + "</p><p>We currently use the C++ paths also for C compilation, which is safe " |
| + "as long as there are no name clashes between C++ and C header files.</p>" |
| + "<p>Relative paths are resolved relative to the configuration file directory." |
| + "</p><p>If the compiler has --sysroot support, then these paths should use " |
| + "%sysroot% rather than the include path, and specify the sysroot attribute " |
| + "in order to give blaze the information necessary to make the correct " |
| + "replacements.</p>"), |
| @Param( |
| name = "toolchain_identifier", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = |
| "<p>The unique identifier of the toolchain within the crosstool release. It must " |
| + "be possible to use this as a directory name in a path.</p>" |
| + "<p>It has to match the following regex: [a-zA-Z_][\\.\\- \\w]*</p>"), |
| @Param( |
| name = "host_system_name", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The system name which is required by the toolchain to run."), |
| @Param( |
| name = "target_system_name", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The GNU System Name."), |
| @Param( |
| name = "target_cpu", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The target architecture string."), |
| @Param( |
| name = "target_libc", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The libc version string (e.g. \"glibc-2.2.2\")."), |
| @Param( |
| name = "compiler", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The compiler version string (e.g. \"gcc-4.1.1\")."), |
| @Param( |
| name = "abi_version", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The abi in use, which is a gcc version. E.g.: \"gcc-3.4\""), |
| @Param( |
| name = "abi_libc_version", |
| positional = false, |
| type = String.class, |
| named = true, |
| doc = "The glibc version used by the abi we're using."), |
| @Param( |
| name = "tool_paths", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "A list of <a href=\"https://github.com/bazelbuild/bazel/blob/master/tools/cpp/" |
| + "cc_toolchain_config_lib.bzl#L400\">tool_paths</a>."), |
| @Param( |
| name = "make_variables", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class, |
| doc = |
| "A list of <a href=\"https://github.com/bazelbuild/bazel/blob/master/tools/cpp/" |
| + "cc_toolchain_config_lib.bzl#L86\">make_variables</a>."), |
| @Param( |
| name = "builtin_sysroot", |
| positional = false, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)}, |
| named = true, |
| doc = |
| "The built-in sysroot. If this attribute is not present, Bazel does not " |
| + "allow using a different sysroot, i.e. through the --grte_top option."), |
| @Param( |
| name = "cc_target_os", |
| positional = false, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)}, |
| named = true, |
| doc = "Internal purpose only, do not use."), |
| }) |
| CcToolchainConfigInfoT ccToolchainConfigInfoFromStarlark( |
| StarlarkRuleContextT starlarkRuleContext, |
| Sequence<?> features, // <StructApi> expected |
| Sequence<?> actionConfigs, // <StructApi> expected |
| Sequence<?> artifactNamePatterns, // <StructApi> expected |
| Sequence<?> cxxBuiltInIncludeDirectories, // <String> expected |
| String toolchainIdentifier, |
| String hostSystemName, |
| String targetSystemName, |
| String targetCpu, |
| String targetLibc, |
| String compiler, |
| String abiVersion, |
| String abiLibcVersion, |
| Sequence<?> toolPaths, // <StructApi> expected |
| Sequence<?> makeVariables, // <StructApi> expected |
| Object builtinSysroot, |
| Object ccTargetOs) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "create_linking_context_from_compilation_outputs", |
| doc = |
| "Should be used for creating library rules that can propagate information downstream in" |
| + " order to be linked later by a top level rule that does transitive linking to" |
| + " create an executable or dynamic library. Returns tuple of " |
| + "(<code>CcLinkingContext</code>, <code>CcLinkingOutputs</code>).", |
| useStarlarkThread = true, |
| parameters = { |
| @Param( |
| name = "actions", |
| type = StarlarkActionFactoryApi.class, |
| positional = false, |
| named = true, |
| doc = "<code>actions</code> object."), |
| @Param( |
| name = "feature_configuration", |
| doc = "<code>feature_configuration</code> to be queried.", |
| positional = false, |
| named = true, |
| type = FeatureConfigurationApi.class), |
| @Param( |
| name = "cc_toolchain", |
| doc = "<code>CcToolchainInfo</code> provider to be used.", |
| positional = false, |
| named = true, |
| type = CcToolchainProviderApi.class), |
| @Param( |
| name = "compilation_outputs", |
| doc = "Compilation outputs containing object files to link.", |
| positional = false, |
| named = true, |
| type = CcCompilationOutputsApi.class), |
| @Param( |
| name = "user_link_flags", |
| doc = "Additional list of linking options.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| @Param( |
| name = "linking_contexts", |
| doc = |
| "Libraries from dependencies. These libraries will be linked into the output " |
| + "artifact of the link() call, be it a binary or a library.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| @Param( |
| name = "name", |
| doc = |
| "This is used for naming the output artifacts of actions created by this " |
| + "method.", |
| positional = false, |
| named = true, |
| type = String.class), |
| @Param( |
| name = "language", |
| doc = "Only C++ supported for now. Do not use this parameter.", |
| positional = false, |
| named = true, |
| defaultValue = "'c++'", |
| type = String.class), |
| @Param( |
| name = "alwayslink", |
| doc = "Whether this library should always be linked.", |
| positional = false, |
| named = true, |
| defaultValue = "False", |
| type = Boolean.class), |
| @Param( |
| name = "additional_inputs", |
| doc = "For additional inputs to the linking action, e.g.: linking scripts.", |
| positional = false, |
| named = true, |
| defaultValue = "[]", |
| type = Sequence.class), |
| @Param( |
| name = "disallow_static_libraries", |
| doc = "Whether static libraries should be created.", |
| positional = false, |
| named = true, |
| defaultValue = "False", |
| type = Boolean.class), |
| @Param( |
| name = "disallow_dynamic_library", |
| doc = "Whether a dynamic library should be created.", |
| positional = false, |
| named = true, |
| defaultValue = "False", |
| type = Boolean.class), |
| @Param( |
| name = "grep_includes", |
| positional = false, |
| named = true, |
| noneable = true, |
| defaultValue = "None", |
| allowedTypes = {@ParamType(type = FileApi.class), @ParamType(type = NoneType.class)}), |
| }) |
| Tuple<Object> createLinkingContextFromCompilationOutputs( |
| StarlarkActionFactoryT starlarkActionFactoryApi, |
| FeatureConfigurationT starlarkFeatureConfiguration, |
| CcToolchainProviderT starlarkCcToolchainProvider, |
| CompilationOutputsT compilationOutputs, |
| Sequence<?> userLinkFlags, // <String> expected |
| Sequence<?> linkingContexts, // <LinkingContextT> expected |
| String name, |
| String language, |
| boolean alwayslink, |
| Sequence<?> additionalInputs, // <FileT> expected |
| boolean disallowStaticLibraries, |
| boolean disallowDynamicLibraries, |
| Object grepIncludes, |
| StarlarkThread thread) |
| throws InterruptedException, EvalException; |
| } |
