rules-resources.md

Rules related to Apple resources and resource bundles.

apple_bundle_import

apple_bundle_import(name, bundle_imports)

This rule encapsulates an already-built bundle. It is defined by a list of files in exactly one .bundle directory. apple_bundle_import targets need to be added to library targets through the data attribute, or to other resource targets (i.e. apple_resource_bundle and apple_resource_group) through the resources attribute.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
bundle_imports	The list of files under a .bundle directory to be propagated to the top-level bundling target.	List of labels	required

apple_core_data_model

apple_core_data_model(name, srcs, swift_version)

This rule takes a Core Data model definition from a .xcdatamodeld bundle and generates Swift or Objective-C source files that can be added as a dependency to a swift_library target.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	-	List of labels	required
swift_version	Target Swift version for generated classes.	String	optional	""

apple_intent_library

apple_intent_library(name, src, class_prefix, class_visibility, header_name, language,
                     swift_version)

This rule supports the integration of Intents .intentdefinition files into Apple rules. It takes a single .intentdefinition file and creates a target that can be added as a dependency from objc_library or swift_library targets. It accepts the regular objc_library attributes too. This target generates a header named <target_name>.h that can be imported from within the package where this target resides. For example, if this target's label is //my/package:intent, you can import the header as #import "my/package/intent.h".

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
src	Label to a single .intentdefinition files from which to generate sources files.	Label	required
class_prefix	Class prefix to use for the generated classes.	String	optional	""
class_visibility	Visibility attribute for the generated classes ("public", "private", "project").	String	optional	""
header_name	Name of the public header file (only when using Objective-C).	String	optional	""
language	Language of generated classes ("Objective-C", "Swift")	String	required
swift_version	Version of Swift to use for the generated classes.	String	optional	""

apple_metal_library

apple_metal_library(name, srcs, out, hdrs, copts, includes)

Compiles Metal shader language sources into a Metal library.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	A list of .metal source files that will be compiled into the library.	List of labels	required
out	An output .metallib filename. Defaults to default.metallib if unspecified.	String	optional	"default.metallib"
hdrs	A list of headers to make importable when compiling the metal library.	List of labels	optional	[]
copts	A list of compiler options passed to the metal compiler for each source.	List of strings	optional	[]
includes	A list of header search paths.	List of strings	optional	[]

apple_precompiled_resource_bundle

apple_precompiled_resource_bundle(name, resources, bundle_id, bundle_name, infoplists,
                                  strip_structured_resources_prefixes, structured_resources)

This rule encapsulates a target which is provided to dependers as a bundle. An apple_precompiled_resource_bundle's resources are put in a resource bundle in the top level Apple bundle dependent. apple_precompiled_resource_bundle targets need to be added to library targets through the data attribute.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
resources	Files to include in the resource bundle. Files that are processable resources, like .xib, .storyboard, .strings, .png, and others, will be processed by the Apple bundling rules that have those files as dependencies. Other file types that are not processed will be copied verbatim. These files are placed in the root of the resource bundle (e.g. Payload/foo.app/bar.bundle/...) in most cases. However, if they appear to be localized (i.e. are contained in a directory called *.lproj), they will be placed in a directory of the same name in the app bundle. You can also add other apple_precompiled_resource_bundle and apple_bundle_import targets into resources, and the resource bundle structures will be propagated into the final bundle.	List of labels	optional	[]
bundle_id	The bundle ID for this target. It will replace $(PRODUCT_BUNDLE_IDENTIFIER) found in the files from defined in the infoplists paramter.	String	optional	""
bundle_name	The desired name of the bundle (without the .bundle extension). If this attribute is not set, then the name of the target will be used instead.	String	optional	""
infoplists	A list of .plist files that will be merged to form the Info.plist that represents the extension. At least one file must be specified. Please see Info.plist Handling for what is supported. Duplicate keys between infoplist files will cause an error if and only if the values conflict. Bazel will perform variable substitution on the Info.plist file for the following values (if they are strings in the top-level dict of the plist): ${BUNDLE_NAME}: This target's name and bundle suffix (.bundle or .app) in the form name.suffix. ${PRODUCT_NAME}: This target's name. ${TARGET_NAME}: This target's name. The key in ${} may be suffixed with :rfc1034identifier (for example ${PRODUCT_NAME::rfc1034identifier}) in which case Bazel will replicate Xcode's behavior and replace non-RFC1034-compliant characters with -.	List of labels	optional	[]
strip_structured_resources_prefixes	A list of prefixes to strip from the paths of structured resources. For each structured resource, if the path starts with one of these prefixes, the first matching prefix will be removed from the path when the resource is placed in the bundle root. This is useful for removing intermediate directories from the resource paths. For example, if structured_resources contains ["intermediate/res/foo.png"], and strip_structured_resources_prefixes contains ["intermediate"], res/foo.png will end up inside the bundle.	List of strings	optional	[]
structured_resources	Files to include in the final resource bundle. They are not processed or compiled in any way besides the processing done by the rules that actually generate them. These files are placed in the bundle root in the same structure passed to this argument, so ["res/foo.png"] will end up in res/foo.png inside the bundle.	List of labels	optional	[]

apple_resource_bundle

apple_resource_bundle(name, resources, bundle_id, bundle_name, infoplists,
                      strip_structured_resources_prefixes, structured_resources)

This rule encapsulates a target which is provided to dependers as a bundle. An apple_resource_bundle's resources are put in a resource bundle in the top level Apple bundle dependent. apple_resource_bundle targets need to be added to library targets through the data attribute.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
resources	Files to include in the resource bundle. Files that are processable resources, like .xib, .storyboard, .strings, .png, and others, will be processed by the Apple bundling rules that have those files as dependencies. Other file types that are not processed will be copied verbatim. These files are placed in the root of the resource bundle (e.g. Payload/foo.app/bar.bundle/...) in most cases. However, if they appear to be localized (i.e. are contained in a directory called *.lproj), they will be placed in a directory of the same name in the app bundle. You can also add other apple_resource_bundle and apple_bundle_import targets into resources, and the resource bundle structures will be propagated into the final bundle.	List of labels	optional	[]
bundle_id	The bundle ID for this target. It will replace $(PRODUCT_BUNDLE_IDENTIFIER) found in the files from defined in the infoplists paramter.	String	optional	""
bundle_name	The desired name of the bundle (without the .bundle extension). If this attribute is not set, then the name of the target will be used instead.	String	optional	""
infoplists	A list of .plist files that will be merged to form the Info.plist that represents the extension. At least one file must be specified. Please see Info.plist Handling for what is supported. Duplicate keys between infoplist files will cause an error if and only if the values conflict. Bazel will perform variable substitution on the Info.plist file for the following values (if they are strings in the top-level dict of the plist): ${BUNDLE_NAME}: This target's name and bundle suffix (.bundle or .app) in the form name.suffix. ${PRODUCT_NAME}: This target's name. ${TARGET_NAME}: This target's name. The key in ${} may be suffixed with :rfc1034identifier (for example ${PRODUCT_NAME::rfc1034identifier}) in which case Bazel will replicate Xcode's behavior and replace non-RFC1034-compliant characters with -.	List of labels	optional	[]
strip_structured_resources_prefixes	A list of prefixes to strip from the paths of structured resources. For each structured resource, if the path starts with one of these prefixes, the first matching prefix will be removed from the path when the resource is placed in the bundle root. This is useful for removing intermediate directories from the resource paths. For example, if structured_resources contains ["intermediate/res/foo.png"], and strip_structured_resources_prefixes contains ["intermediate"], res/foo.png will end up inside the bundle.	List of strings	optional	[]
structured_resources	Files to include in the final resource bundle. They are not processed or compiled in any way besides the processing done by the rules that actually generate them. These files are placed in the bundle root in the same structure passed to this argument, so ["res/foo.png"] will end up in res/foo.png inside the bundle.	List of labels	optional	[]

apple_resource_group

apple_resource_group(name, resources, strip_structured_resources_prefixes, structured_resources)

This rule encapsulates a target which provides resources to dependents. An apple_resource_group's resources and structured_resources are put in the top-level Apple bundle target. apple_resource_group targets need to be added to library targets through the data attribute, or to other apple_resource_bundle or apple_resource_group targets through the resources attribute.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
resources	Files to include in the final bundle that depends on this target. Files that are processable resources, like .xib, .storyboard, .strings, .png, and others, will be processed by the Apple bundling rules that have those files as dependencies. Other file types that are not processed will be copied verbatim. These files are placed in the root of the final bundle (e.g. Payload/foo.app/...) in most cases. However, if they appear to be localized (i.e. are contained in a directory called *.lproj), they will be placed in a directory of the same name in the app bundle. You can also add apple_resource_bundle and apple_bundle_import targets into resources, and the resource bundle structures will be propagated into the final bundle.	List of labels	optional	[]
strip_structured_resources_prefixes	A list of prefixes to strip from the paths of structured resources. For each structured resource, if the path starts with one of these prefixes, the first matching prefix will be removed from the path when the resource is placed in the bundle root. This is useful for removing intermediate directories from the resource paths. For example, if structured_resources contains ["intermediate/res/foo.png"], and strip_structured_resources_prefixes contains ["intermediate"], res/foo.png will end up inside the bundle.	List of strings	optional	[]
structured_resources	Files to include in the final application bundle. They are not processed or compiled in any way besides the processing done by the rules that actually generate them. These files are placed in the bundle root in the same structure passed to this argument, so ["res/foo.png"] will end up in res/foo.png inside the bundle.	List of labels	optional	[]

apple_core_ml_library

apple_core_ml_library(name, mlmodel, kwargs)

Macro to orchestrate an objc_library with generated sources for mlmodel files.

PARAMETERS

Name	Description	Default Value
name	-	none
mlmodel	-	none
kwargs	-	none

objc_intent_library

objc_intent_library(name, src, class_prefix, testonly, kwargs)

Macro to orchestrate an objc_library with generated sources for intentdefiniton files.

PARAMETERS

Name	Description	Default Value
name	-	none
src	-	none
class_prefix	-	None
testonly	-	False
kwargs	-	none

resources_common.bucketize

resources_common.bucketize(allowed_buckets, owner, parent_dir_param, resources, swift_module)

Separates the given resources into resource bucket types and returns an AppleResourceInfo.

This method wraps _bucketize_data and returns its tuple as an immutable Starlark structure to help propagate the structure of the Apple bundle resources to the bundler.

PARAMETERS

Name	Description	Default Value
allowed_buckets	List of buckets allowed for bucketing. Files that do not fall into these buckets will instead be placed into the "unprocessed" bucket. Defaults to None which means all buckets are allowed.	None
owner	An optional string that has a unique identifier to the target that should own the resources. If an owner should be passed, it's usually equal to str(ctx.label).	None
parent_dir_param	Either a string/None or a struct used to calculate the value of parent_dir for each resource. If it is a struct, it will be considered a partial context, and will be invoked with partial.call().	None
resources	List of resources to bucketize.	none
swift_module	The Swift module name to associate to these resources.	None

RETURNS

An AppleResourceInfo provider with resources bucketized according to type.

resources_common.bucketize_data

resources_common.bucketize_data(allowed_buckets, owner, parent_dir_param, resources, swift_module)

Separates the given resources into resource bucket types.

This method takes a list of resources and constructs a tuple object for each, placing it inside the correct bucket.

The parent_dir is calculated from the parent_dir_param object. This object can either be None (the default), a string object, or a function object. If a function is provided, it should accept only 1 parameter, which will be the File object representing the resource to bucket. This mechanism gives us a simpler way to manage multiple use cases. For example, when used to bucketize structured resources, the parent_dir_param can be a function that returns the relative path to the owning package; or in an objc_library it can be None, signaling that these resources should be placed in the root level.

If no bucket was detected based on the short path for a specific resource, it will be placed into the "unprocessed" bucket. Resources in this bucket will not be processed and will be copied as is. Once all resources have been placed in buckets, each of the lists will be minimized.

Finally, it will return a AppleResourceInfo provider with the resources bucketed per type.

PARAMETERS

Name	Description	Default Value
allowed_buckets	List of buckets allowed for bucketing. Files that do not fall into these buckets will instead be placed into the "unprocessed" bucket. Defaults to None which means all buckets are allowed.	None
owner	An optional string that has a unique identifier to the target that should own the resources. If an owner should be passed, it's usually equal to str(ctx.label).	None
parent_dir_param	Either a string/None or a struct used to calculate the value of parent_dir for each resource. If it is a struct, it will be considered a partial context, and will be invoked with partial.call().	None
resources	List of resources to bucketize.	none
swift_module	The Swift module name to associate to these resources.	None

RETURNS

A tuple with a list of owners, a list of "unowned" resources, and a dictionary with bucketized resources organized by resource type.

resources_common.bucketize_typed

resources_common.bucketize_typed(resources, bucket_type, owner, parent_dir_param)

Collects and bucketizes a specific type of resource and returns an AppleResourceInfo.

Adds the given resources directly into a tuple under the field named in bucket_type. This avoids the sorting mechanism that bucketize does, while grouping resources together using parent_dir_param when available.

PARAMETERS

Name	Description	Default Value
resources	List of resources to place in bucket_type or Dictionary of resources keyed by target to place in bucket_type. This dictionary is supported by the resources.collect() API.	none
bucket_type	The AppleResourceInfo field under which to collect the resources.	none
owner	An optional string that has a unique identifier to the target that should own the resources. If an owner should be passed, it's usually equal to str(ctx.label).	None
parent_dir_param	Either a string/None or a struct used to calculate the value of parent_dir for each resource. If it is a struct, it will be considered a partial context, and will be invoked with partial.call().	None

RETURNS

An AppleResourceInfo provider with resources in the given bucket.

resources_common.bucketize_typed_data

resources_common.bucketize_typed_data(bucket_type, owner, parent_dir_param, resources)

Collects and bucketizes a specific type of resource.

Adds the given resources directly into a tuple under the field named in bucket_type. This avoids the sorting mechanism that bucketize does, while grouping resources together using parent_dir_param when available.

PARAMETERS

Name	Description	Default Value
bucket_type	The AppleResourceInfo field under which to collect the resources.	none
owner	An optional string that has a unique identifier to the target that should own the resources. If an owner should be passed, it's usually equal to str(ctx.label).	None
parent_dir_param	Either a string/None or a struct used to calculate the value of parent_dir for each resource. If it is a struct, it will be considered a partial context, and will be invoked with partial.call().	None
resources	List of resources to place in bucket_type or Dictionary of resources keyed by target to place in bucket_type. This dictionary is supported by the resources.collect() API.	none

RETURNS

A tuple with a list of owners, a list of "unowned" resources, and a dictionary with bucketized resources that are all placed within a single bucket defined by bucket_type.

resources_common.bundle_relative_parent_dir

resources_common.bundle_relative_parent_dir(resource, extension)

Returns the bundle relative path to the resource rooted at the bundle.

Looks for the first instance of a folder with the suffix specified by extension, and then returns the directory path to the file within the bundle. For example, for a resource with path my/package/Contents.bundle/directory/foo.txt and extension equal to "bundle", it would return Contents.bundle/directory.

PARAMETERS

Name	Description	Default Value
resource	The resource for which to calculate the bundle relative path.	none
extension	The bundle extension to use when finding the relative path.	none

RETURNS

The bundle relative path, rooted at the outermost bundle.

resources_common.collect

resources_common.collect(attr, res_attrs, split_attr_keys)

Collects all resource attributes present in the given attributes.

Iterates over the given res_attrs attributes collecting files to be processed as resources. These are all placed into a list, and then returned.

PARAMETERS

Name	Description	Default Value
attr	The attributes object on the current context. Can be either a ctx.attr/ctx.rule.attr -like struct that has targets/lists as its values, or a ctx.split_attr-like struct with the dictionary fan-out corresponding to split key.	none
res_attrs	List of attributes to iterate over collecting resources.	[]
split_attr_keys	If defined, a list of 1:2+ transition keys to merge values from.	[]

RETURNS

A dictionary keyed by target from the rule attr with the list of all collected resources.

resources_common.deduplicate

resources_common.deduplicate(resources_provider, avoid_providers, field_handler, default_owner)

PARAMETERS

Name	Description	Default Value
resources_provider	-	none
avoid_providers	-	none
field_handler	-	none
default_owner	-	None

resources_common.merge_providers

resources_common.merge_providers(default_owner, providers, validate_all_resources_owned)

Merges multiple AppleResourceInfo providers into one.

PARAMETERS

Name	Description	Default Value
default_owner	The default owner to be used for resources which have a None value in the owners dictionary. May be None, in which case no owner is marked.	None
providers	The list of providers to merge. This method will fail unless there is at least 1 provider in the list.	none
validate_all_resources_owned	Whether to validate that all resources are owned. This is useful for top-level rules to ensure that the resources in AppleResourceInfo that they are propagating are fully owned. If default_owner is set, this attribute does nothing, as by definition the resources will all have a default owner.	False

RETURNS

A AppleResourceInfo provider with the results of the merge of the given providers.

resources_common.minimize

resources_common.minimize(bucket)

Minimizes the given list of tuples into the smallest subset possible.

Takes the list of tuples that represent one resource bucket, and minimizes it so that 2 tuples with resources that should be placed under the same location are merged into 1 tuple.

For tuples to be merged, they need to have the same parent_dir and swift_module.

PARAMETERS

Name	Description	Default Value
bucket	List of tuples to be minimized.	none

RETURNS

A list of minimized tuples.

resources_common.nest_in_bundle

resources_common.nest_in_bundle(provider_to_nest, nesting_bundle_dir)

Nests resources in a AppleResourceInfo provider under a new parent bundle directory.

This method is mostly used by rules that create resource bundles in order to nest other resource bundle targets within themselves. For instance, apple_resource_bundle supports nesting other bundles through the resources attribute. In these use cases, the dependency bundles are added as nested bundles into the dependent bundle.

This method prepends the parent_dir field in the buckets with the given nesting_bundle_dir argument.

PARAMETERS

Name	Description	Default Value
provider_to_nest	A AppleResourceInfo provider with the resources to nest.	none
nesting_bundle_dir	The new bundle directory under which to bundle the resources.	none

RETURNS

A new AppleResourceInfo provider with the resources nested under nesting_bundle_dir.

resources_common.populated_resource_fields

resources_common.populated_resource_fields(provider)

Returns a list of field names of the provider's resource buckets that are non empty.

PARAMETERS

Name	Description	Default Value
provider	-	none

resources_common.process_bucketized_data

resources_common.process_bucketized_data(actions, apple_mac_toolchain_info, bucketized_owners,
                                         buckets, bundle_id, output_discriminator,
                                         platform_prerequisites, processing_owner, product_type,
                                         resource_types_to_process, rule_label, unowned_resources)

Registers actions for select resource types, given bucketized groupings of data.

This method performs the same actions as bucketize_data, and further iterates through a subset of resource types to register actions to process them as necessary before returning an AppleResourceInfo. This AppleResourceInfo has an additional field, called "processed", featuring the expected outputs for each of the actions declared in this method.

PARAMETERS

Name	Description	Default Value
actions	The actions provider from ctx.actions.	none
apple_mac_toolchain_info	struct of tools from the shared Apple toolchain.	none
bucketized_owners	A list of tuples indicating the owner of each bucketized resource.	[]
buckets	A dictionary with bucketized resources organized by resource type.	none
bundle_id	The bundle ID to configure for this target.	none
output_discriminator	A string to differentiate between different target intermediate files or None.	None
platform_prerequisites	Struct containing information on the platform being targeted.	none
processing_owner	An optional string that has a unique identifier to the target that should own the resources. If an owner should be passed, it's usually equal to str(ctx.label).	None
product_type	The product type identifier used to describe the current bundle type.	none
resource_types_to_process	A list of bucket types to process.	["infoplists", "plists", "pngs", "strings"]
rule_label	The label of the target being analyzed.	none
unowned_resources	A list of "unowned" resources.	[]

RETURNS

An AppleResourceInfo provider with resources bucketized according to type.

resources_common.runfiles_resources_parent_dir

resources_common.runfiles_resources_parent_dir(resource)

Returns the parent directory of the file.

PARAMETERS

Name	Description	Default Value
resource	The resource for which to calculate the package relative path.	none

RETURNS

The package relative path to the parent directory of the resource.

resources_common.structured_resources_parent_dir

resources_common.structured_resources_parent_dir(parent_dir, resource, strip_prefixes)

Returns the package relative path for the parent directory of a resource.

PARAMETERS

Name	Description	Default Value
parent_dir	Parent directory to prepend to the package relative path.	None
resource	The resource for which to calculate the package relative path.	none
strip_prefixes	A list of prefixes to strip from the package relative path. The first prefix that matches will be used.	[]

RETURNS

The package relative path to the parent directory of the resource.

swift_apple_core_ml_library

swift_apple_core_ml_library(name, mlmodel, kwargs)

Macro to orchestrate a swift_library with generated sources for mlmodel files.

PARAMETERS

Name	Description	Default Value
name	-	none
mlmodel	-	none
kwargs	-	none

swift_intent_library

swift_intent_library(name, src, class_prefix, class_visibility, swift_version, testonly, kwargs)

This macro supports the integration of Intents .intentdefinition files into Apple rules.

It takes a single .intentdefinition file and creates a target that can be added as a dependency from objc_library or swift_library targets.

It accepts the regular swift_library attributes too.

PARAMETERS

Name	Description	Default Value
name	A unique name for the target.	none
src	Reference to the .intentdefiniton file to process.	none
class_prefix	Class prefix to use for the generated classes.	None
class_visibility	Visibility attribute for the generated classes (public, private, project).	None
swift_version	Version of Swift to use for the generated classes.	None
testonly	Set to True to enforce that this library is only used from test code.	False
kwargs	-	none