Extensions > API reference > native

native

A built-in module to support native rules and other package helper functions. All native rules appear as functions in this module, e.g. native.cc_library. Note that the native module is only available in the loading phase (i.e. for macros, not for rule implementations). Attributes will ignore None values, and treat them as if the attribute was unset.
The following functions are also available:

existing_rule

unknown native.existing_rule(name)

Returns a new mutable dict that describes the attributes of a rule instantiated in this thread's package, or None if no rule instance of that name exists.

The dict contains an entry for each attribute, except private ones, whose names do not start with a letter. In addition, the dict contains entries for the rule instance's name and kind (for example, 'cc_binary').

The values of the dict represent attribute values as follows:

• Attributes of type str, int, and bool are represented as is.
• Labels are converted to strings of the form ':foo' for targets in the same package or '//pkg:name' for targets in a different package.
• Lists are represented as tuples, and dicts are converted to new, mutable dicts. Their elements are recursively converted in the same fashion.
• select values are returned as is.
• Attributes for which no value was specified during rule instantiation and whose default value is computed are excluded from the result. (Computed defaults cannot be computed until the analysis phase.).

If possible, avoid using this function. It makes BUILD files brittle and order-dependent. Also, beware that it differs subtly from the two other conversions of rule attribute values from internal form to Starlark: one used by computed defaults, the other used by ctx.attr.foo.

Parameters

Parameter	Description
name	string The name of the target.

existing_rules

dict native.existing_rules()

Returns a new mutable dict describing the rules so far instantiated in this thread's package. Each dict entry maps the name of the rule instance to the result that would be returned by existing_rule(name).

Note: If possible, avoid using this function. It makes BUILD files brittle and order-dependent, and it may be expensive especially if called within a loop.

exports_files

None native.exports_files(srcs, visibility=None, licenses=None)

Specifies a list of files belonging to this package that are exported to other packages.

Parameters

Parameter	Description
srcs	sequence of strings The list of files to export.
visibility	sequence A visibility declaration can to be specified. The files will be visible to the targets specified. If no visibility is specified, the files will be visible to every package.
licenses	sequence of strings Licenses to be specified.

glob

sequence native.glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)

Glob returns a list of every file in the current package that:

• Matches at least one pattern in include.
• Does not match any of the patterns in exclude (default []).

If the exclude_directories argument is enabled (set to 1), files of type directory will be omitted from the results (default 1).

Parameters

Parameter	Description
include	sequence of strings The list of glob patterns to include.
exclude	sequence of strings The list of glob patterns to exclude.
exclude_directories	int A flag whether to exclude directories or not.
allow_empty	Whether we allow glob patterns to match nothing. If `allow_empty` is False, each individual include pattern must match something and also the final result must be non-empty (after the matches of the `exclude` patterns are excluded).

package_group

None native.package_group(name, packages=[], includes=[])

This function defines a set of packages and assigns a label to the group. The label can be referenced in visibility attributes.

Parameters

Parameter	Description
name	string The unique name for this rule.
packages	sequence of strings A complete enumeration of packages in this group.
includes	sequence of strings Other package groups that are included in this one.

package_name

string native.package_name()

The name of the package being evaluated. For example, in the BUILD file some/package/BUILD, its value will be some/package. If the BUILD file calls a function defined in a .bzl file, package_name() will match the caller BUILD file package. This function is equivalent to the deprecated variable PACKAGE_NAME.

repository_name

string native.repository_name()

The name of the repository the rule or build extension is called from. For example, in packages that are called into existence by the WORKSPACE stanza local_repository(name='local', path=...) it will be set to @local. In packages in the main repository, it will be set to @. This function is equivalent to the deprecated variable REPOSITORY_NAME.