| // 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.starlarkbuildapi.objc; |
| |
| import com.google.common.collect.ImmutableMap; |
| import com.google.devtools.build.lib.analysis.TransitiveInfoCollection; |
| import com.google.devtools.build.lib.analysis.config.transitions.StarlarkExposedRuleTransitionFactory; |
| import com.google.devtools.build.lib.collect.nestedset.Depset; |
| import com.google.devtools.build.lib.starlarkbuildapi.FileApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.SplitTransitionProviderApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.StarlarkRuleContextApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.apple.ApplePlatformApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.apple.AppleToolchainApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.apple.DottedVersionApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.apple.XcodeConfigInfoApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.ProviderApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.StructApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.cpp.CcInfoApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.platform.ConstraintValueInfoApi; |
| import net.starlark.java.annot.Param; |
| import net.starlark.java.annot.ParamType; |
| import net.starlark.java.annot.StarlarkBuiltin; |
| import net.starlark.java.annot.StarlarkMethod; |
| import net.starlark.java.eval.Dict; |
| import net.starlark.java.eval.EvalException; |
| import net.starlark.java.eval.NoneType; |
| import net.starlark.java.eval.Sequence; |
| import net.starlark.java.eval.StarlarkInt; |
| import net.starlark.java.eval.StarlarkThread; |
| import net.starlark.java.eval.StarlarkValue; |
| |
| /** Interface for a module with useful functions for creating apple-related rule implementations. */ |
| @StarlarkBuiltin( |
| name = "apple_common", |
| doc = "Functions for Starlark to access internals of the apple rule implementations.") |
| public interface AppleCommonApi< |
| FileApiT extends FileApi, |
| ConstraintValueT extends ConstraintValueInfoApi, |
| StarlarkRuleContextT extends StarlarkRuleContextApi<ConstraintValueT>, |
| CcInfoApiT extends CcInfoApi<?>, |
| ObjcProviderApiT extends ObjcProviderApi<?>, |
| XcodeConfigInfoApiT extends XcodeConfigInfoApi<?, ?>, |
| ApplePlatformApiT extends ApplePlatformApi> |
| extends StarlarkValue { |
| |
| @StarlarkMethod( |
| name = "apple_toolchain", |
| doc = "Utilities for resolving items from the apple toolchain.") |
| AppleToolchainApi<?> getAppleToolchain(); |
| |
| @StarlarkMethod( |
| name = "platform_type", |
| doc = |
| "An enum-like struct that contains the following fields corresponding to Apple platform " |
| + "types:<br><ul><li><code>ios</code></li><li><code>macos</code></li>" |
| + "<li><code>tvos</code></li><li><code>watchos</code></li></ul><p>These values can" |
| + " be passed to methods that expect a platform type, like the 'apple' configuration" |
| + " fragment's <a href='apple.html#multi_arch_platform'>multi_arch_platform</a>" |
| + " method.<p>Example:<p><pre class='language-python'>\n" |
| + "ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios)\n" |
| + "</pre>", |
| structField = true) |
| StructApi getPlatformTypeStruct(); |
| |
| @StarlarkMethod( |
| name = "apple_crosstool_transition", |
| doc = "Testing the Apple crosstool transition", |
| documented = false, |
| structField = true) |
| StarlarkExposedRuleTransitionFactory getAppleCrosstoolTransition(); |
| |
| @StarlarkMethod( |
| name = "platform", |
| doc = |
| "An enum-like struct that contains the following fields corresponding to Apple " |
| + "platforms:<br><ul>" |
| + "<li><code>ios_device</code></li>" |
| + "<li><code>ios_simulator</code></li>" |
| + "<li><code>macos</code></li>" |
| + "<li><code>tvos_device</code></li>" |
| + "<li><code>tvos_simulator</code></li>" |
| + "<li><code>watchos_device</code></li>" |
| + "<li><code>watchos_simulator</code></li>" |
| + "</ul><p>" |
| + "These values can be passed to methods that expect a platform, like " |
| + "<a href='XcodeVersionConfig.html#sdk_version_for_platform'>" |
| + "XcodeVersionConfig.sdk_version_for_platform</a>.", |
| structField = true) |
| StructApi getPlatformStruct(); |
| |
| @StarlarkMethod( |
| name = "XcodeProperties", |
| doc = |
| "The constructor/key for the <code>XcodeVersionProperties</code> provider.<p>" |
| + "If a target propagates the <code>XcodeVersionProperties</code> provider," |
| + " use this as the key with which to retrieve it. Example:<br>" |
| + "<pre class='language-python'>\n" |
| + "dep = ctx.attr.deps[0]\n" |
| + "p = dep[apple_common.XcodeVersionProperties]\n" |
| + "</pre>", |
| structField = true) |
| ProviderApi getXcodeVersionPropertiesConstructor(); |
| |
| @StarlarkMethod( |
| name = "XcodeVersionConfig", |
| doc = "The constructor/key for the <code>XcodeVersionConfig</code> provider.", |
| structField = true) |
| ProviderApi getXcodeVersionConfigConstructor(); |
| |
| @StarlarkMethod( |
| // TODO(b/63899207): This currently does not match ObjcProvider.STARLARK_NAME as it requires |
| // a migration of existing Starlark rules. |
| name = "Objc", |
| doc = |
| "The constructor/key for the <code>Objc</code> provider.<p>" |
| + "If a target propagates the <code>Objc</code> provider, use this as the " |
| + "key with which to retrieve it. Example:<br>" |
| + "<pre class='language-python'>\n" |
| + "dep = ctx.attr.deps[0]\n" |
| + "p = dep[apple_common.Objc]\n" |
| + "</pre>", |
| structField = true) |
| ProviderApi getObjcProviderConstructor(); |
| |
| @StarlarkMethod( |
| name = "AppleDynamicFramework", |
| doc = |
| "The constructor/key for the <code>AppleDynamicFramework</code> provider.<p>" |
| + "If a target propagates the <code>AppleDynamicFramework</code> provider, use this " |
| + "as the key with which to retrieve it. Example:<br>" |
| + "<pre class='language-python'>\n" |
| + "dep = ctx.attr.deps[0]\n" |
| + "p = dep[apple_common.AppleDynamicFramework]\n" |
| + "</pre>", |
| structField = true) |
| ProviderApi getAppleDynamicFrameworkConstructor(); |
| |
| @StarlarkMethod( |
| name = "AppleExecutableBinary", |
| doc = |
| "The constructor/key for the <code>AppleExecutableBinary</code> provider.<p>" |
| + "If a target propagates the <code>AppleExecutableBinary</code> provider," |
| + " use this as the key with which to retrieve it. Example:<br>" |
| + "<pre class='language-python'>\n" |
| + "dep = ctx.attr.deps[0]\n" |
| + "p = dep[apple_common.AppleExecutableBinary]\n" |
| + "</pre>", |
| structField = true) |
| ProviderApi getAppleExecutableBinaryConstructor(); |
| |
| @StarlarkMethod( |
| name = "AppleDebugOutputs", |
| doc = |
| "The constructor/key for the <code>AppleDebugOutputs</code> provider.<p>If a target" |
| + " propagates the <code>AppleDebugOutputs</code> provider, use this as the key with" |
| + " which to retrieve it. Example:<br><pre class='language-python'>\n" |
| + "dep = ctx.attr.deps[0]\n" |
| + "p = dep[apple_common.AppleDebugOutputs]\n" |
| + "</pre>", |
| structField = true) |
| ProviderApi getAppleDebugOutputsConstructor(); |
| |
| @StarlarkMethod( |
| name = "apple_host_system_env", |
| doc = |
| "Returns a <a href='dict.html'>dict</a> of environment variables that should be set " |
| + "for actions that need to run build tools on an Apple host system, such as the " |
| + " version of Xcode that should be used. The keys are variable names and the values " |
| + " are their corresponding values.", |
| parameters = { |
| @Param( |
| name = "xcode_config", |
| positional = true, |
| named = false, |
| doc = "A provider containing information about the xcode configuration."), |
| }) |
| ImmutableMap<String, String> getAppleHostSystemEnv(XcodeConfigInfoApiT xcodeConfig); |
| |
| @StarlarkMethod( |
| name = "target_apple_env", |
| doc = |
| "Returns a <code>dict</code> of environment variables that should be set for actions " |
| + "that build targets of the given Apple platform type. For example, this dictionary " |
| + "contains variables that denote the platform name and SDK version with which to " |
| + "build. The keys are variable names and the values are their corresponding values.", |
| parameters = { |
| @Param( |
| name = "xcode_config", |
| positional = true, |
| named = false, |
| doc = "A provider containing information about the xcode configuration."), |
| @Param( |
| name = "platform", |
| positional = true, |
| named = false, |
| doc = "The apple platform."), |
| }) |
| ImmutableMap<String, String> getTargetAppleEnvironment( |
| XcodeConfigInfoApiT xcodeConfig, ApplePlatformApiT platform); |
| |
| @StarlarkMethod( |
| name = "multi_arch_split", |
| doc = |
| "A configuration transition for rule attributes to build dependencies in one or more" |
| + " Apple platforms. <p>Use of this transition requires that the 'platform_type' and" |
| + " 'minimum_os_version' string attributes are defined and mandatory on the" |
| + " rule.</p><p>The value of the platform_type attribute will dictate the target" |
| + " architectures for which dependencies along this configuration transition will" |
| + " be built.</p><p>Options are:</p><ul><li><code>ios</code>: architectures gathered" |
| + " from <code>--ios_multi_cpus</code>.</li><li><code>macos</code>: architectures" |
| + " gathered from <code>--macos_cpus</code>.</li><li><code>tvos</code>:" |
| + " architectures gathered from" |
| + " <code>--tvos_cpus</code>.</li><li><code>watchos</code>: architectures gathered" |
| + " from <code>--watchos_cpus</code>.</li></ul><p>minimum_os_version should be a" |
| + " dotted version string such as '7.3', and is used to set the minimum operating" |
| + " system on the configuration similarly based on platform type. For example," |
| + " specifying platform_type 'ios' and minimum_os_version '8.0' will ensure that" |
| + " dependencies are built with minimum iOS version '8.0'.", |
| structField = true) |
| SplitTransitionProviderApi getMultiArchSplitProvider(); |
| |
| @StarlarkMethod( |
| name = "new_objc_provider", |
| doc = "Creates a new ObjcProvider instance.", |
| parameters = {}, |
| extraKeywords = |
| @Param(name = "kwargs", defaultValue = "{}", doc = "Dictionary of arguments."), |
| useStarlarkThread = true) |
| // This method is registered statically for Starlark, and never called directly. |
| ObjcProviderApi<?> newObjcProvider(Dict<String, Object> kwargs, StarlarkThread thread) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "new_dynamic_framework_provider", |
| doc = "Creates a new AppleDynamicFramework provider instance.", |
| parameters = { |
| @Param( |
| name = "binary", |
| allowedTypes = { |
| @ParamType(type = FileApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = "The dylib binary artifact of the dynamic framework."), |
| @Param( |
| name = "cc_info", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "A CcInfo which contains information about the transitive dependencies " |
| + "linked into the binary."), |
| @Param( |
| name = "objc", |
| named = true, |
| positional = false, |
| doc = |
| "An ObjcProvider which contains information about the transitive " |
| + "dependencies linked into the binary."), |
| @Param( |
| name = "framework_dirs", |
| allowedTypes = { |
| @ParamType(type = Depset.class, generic1 = String.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "The framework path names used as link inputs in order to link against the dynamic " |
| + "framework."), |
| @Param( |
| name = "framework_files", |
| allowedTypes = { |
| @ParamType(type = Depset.class, generic1 = FileApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "The full set of artifacts that should be included as inputs to link against the " |
| + "dynamic framework") |
| }) |
| AppleDynamicFrameworkInfoApi<?> newDynamicFrameworkProvider( |
| Object dylibBinary, |
| Object depsCcInfo, |
| ObjcProviderApiT depsObjcProvider, |
| Object dynamicFrameworkDirs, |
| Object dynamicFrameworkFiles) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "new_executable_binary_provider", |
| doc = "Creates a new AppleExecutableBinaryInfo provider instance.", |
| parameters = { |
| @Param( |
| name = "binary", |
| allowedTypes = { |
| @ParamType(type = FileApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = "The binary artifact of the executable."), |
| @Param( |
| name = "cc_info", |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "A CcInfo which contains information about the transitive dependencies " |
| + "linked into the binary."), |
| @Param( |
| name = "objc", |
| named = true, |
| positional = false, |
| doc = |
| "An ObjcProvider which contains information about the transitive " |
| + "dependencies linked into the binary.") |
| }) |
| AppleExecutableBinaryApi newExecutableBinaryProvider( |
| Object executableBinary, Object depsCcInfo, ObjcProviderApiT depsObjcProvider) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "link_multi_arch_binary", |
| doc = |
| "Links a (potentially multi-architecture) binary targeting Apple platforms. This " |
| + "method comprises a bulk of the logic of the Starlark <code>apple_binary</code> " |
| + "rule in the rules_apple domain and exists to aid in the migration of its " |
| + "linking logic to Starlark in rules_apple.\n" |
| + "<p>This API is <b>highly experimental</b> and subject to change at any time. Do " |
| + "not depend on the stability of this function at this time.", |
| parameters = { |
| @Param(name = "ctx", named = true, positional = false, doc = "The Starlark rule context."), |
| @Param( |
| name = "avoid_deps", |
| allowedTypes = { |
| @ParamType(type = Sequence.class, generic1 = TransitiveInfoCollection.class), |
| @ParamType(type = NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| defaultValue = "None", |
| doc = |
| "A list of <code>Target</code>s that are in the dependency graph of the binary but" |
| + " whose libraries should not be linked into the binary. This is the case for" |
| + " dependencies that will be found at runtime in another image, such as the" |
| + " bundle loader or any dynamic libraries/frameworks that will be loaded by" |
| + " this binary."), |
| @Param( |
| name = "extra_linkopts", |
| allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)}, |
| named = true, |
| positional = false, |
| defaultValue = "[]", |
| doc = "Extra linkopts to be passed to the linker action."), |
| @Param( |
| name = "extra_link_inputs", |
| allowedTypes = {@ParamType(type = Sequence.class, generic1 = FileApi.class)}, |
| named = true, |
| positional = false, |
| defaultValue = "[]", |
| doc = "Extra files to pass to the linker action."), |
| @Param( |
| name = "stamp", |
| named = true, |
| positional = false, |
| defaultValue = "-1", |
| doc = |
| "Whether to include build information in the linked binary. If 1, build " |
| + "information is always included. If 0, build information is always excluded. " |
| + "If -1 (the default), then the behavior is determined by the --[no]stamp " |
| + "flag. This should be set to 0 when generating the executable output for " |
| + "test rules."), |
| }, |
| useStarlarkThread = true) |
| // TODO(b/70937317): Iterate on, improve, and solidify this API. |
| StructApi linkMultiArchBinary( |
| StarlarkRuleContextT starlarkRuleContext, |
| Object avoidDeps, // Sequence<TransitiveInfoCollection> expected. |
| Sequence<?> extraLinkopts, // <String> expected. |
| Sequence<?> extraLinkInputs, // <? extends FileApi> expected. |
| StarlarkInt stamp, |
| StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "link_multi_arch_static_library", |
| doc = |
| "Links a (potentially multi-architecture) static library targeting Apple platforms." |
| + " This method comprises a part of the Starlark <code>apple_static_library</code>" |
| + " rule logic, in the rules_apple domain and exists to aid in the migration of its" |
| + " linking logic to Starlark in rules_apple.\n" |
| + "<p>This API is <b>highly experimental</b> and subject to change at any time." |
| + " Do not depend on the stability of this function at this time.", |
| parameters = { |
| @Param(name = "ctx", named = true, positional = false, doc = "The Starlark rule context."), |
| }, |
| useStarlarkThread = true) |
| StructApi linkMultiArchStaticLibrary( |
| StarlarkRuleContextT starlarkRuleContext, StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "dotted_version", |
| doc = "Creates a new <a href=\"DottedVersion.html\">DottedVersion</a> instance.", |
| parameters = { |
| @Param(name = "version", doc = "The string representation of the DottedVersion.") |
| }) |
| DottedVersionApi<?> dottedVersion(String version) throws EvalException; |
| } |