From 5aab0a3fb3738ef1c8a7f170d27a6ea04dc479bc Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Fri, 30 Apr 2021 14:12:30 -0700 Subject: [PATCH 1/2] Update rules.md to match generated --- doc/rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rules.md b/doc/rules.md index f8cd92984..cfdd59204 100644 --- a/doc/rules.md +++ b/doc/rules.md @@ -251,7 +251,7 @@ Compiles and links Swift code into a static library and Swift module. | data | The list of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it. | List of labels | optional | [] | | defines | A list of defines to add to the compilation command line.

Note that unlike C-family languages, Swift defines do not have values; they are simply identifiers that are either defined or undefined. So strings in this list should be simple identifiers, **not** name=value pairs.

Each string is prepended with -D and added to the command line. Unlike copts, these flags are added for the target and every target that depends on it, so use this attribute with caution. It is preferred that you add defines directly to copts, only using this feature in the rare case that a library needs to propagate a symbol up to those that depend on it. | List of strings | optional | [] | | deps | A list of targets that are dependencies of the target being built, which will be linked into that target.

If the Swift toolchain supports implementation-only imports (private_deps on swift_library), then targets in deps are treated as regular (non-implementation-only) imports that are propagated both to their direct and indirect (transitive) dependents.

Allowed kinds of dependencies are:

* swift_c_module, swift_import and swift_library (or anything propagating SwiftInfo)

* cc_library (or anything propagating CcInfo)

Additionally, on platforms that support Objective-C interop, objc_library targets (or anything propagating the apple_common.Objc provider) are allowed as dependencies. On platforms that do not support Objective-C interop (such as Linux), those dependencies will be **ignored.** | List of labels | optional | [] | -| generated_header_name | The name of the generated Objective-C interface header. This name must end with a .h extension and cannot contain any path separators.

If this attribute is not specified, then the default behavior is to name the header ${target_name}-Swift.h.

This attribute is ignored if the toolchain does not support generating headers or if the target has the swift.no_generated_header feature enabled. | String | optional | "" | +| generated_header_name | The name of the generated Objective-C interface header. This name must end with a .h extension and cannot contain any path separators.

If this attribute is not specified, then the default behavior is to name the header ${target_name}-Swift.h.

This attribute is ignored if the toolchain does not support generating headers. | String | optional | "" | | generates_header | If True, an Objective-C header will be generated for this target, in the same build package where the target is defined. By default, the name of the header is ${target_name}-Swift.h; this can be changed using the generated_header_name attribute.

Targets should only set this attribute to True if they export Objective-C APIs. A header generated for a target that does not export Objective-C APIs will be effectively empty (except for a large amount of prologue and epilogue code) and this is generally wasteful because the extra file needs to be propagated in the build graph and, when explicit modules are enabled, extra actions must be executed to compile the Objective-C module for the generated header. | Boolean | optional | False | | linkopts | Additional linker options that should be passed to the linker for the binary that depends on this target. These strings are subject to $(location ...) and ["Make" variable](https://docs.bazel.build/versions/master/be/make-variables.html) expansion. | List of strings | optional | [] | | module_name | The name of the Swift module being built.

If left unspecified, the module name will be computed based on the target's build label, by stripping the leading // and replacing /, :, and other non-identifier characters with underscores. | String | optional | "" | From 1e1aeb08d36347318f239fa5fac596729940d136 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Fri, 30 Apr 2021 14:17:31 -0700 Subject: [PATCH 2/2] docs: providers.md now generated from sources --- doc/BUILD.bazel | 58 ++++++-- doc/providers.md | 335 ++++++++++++----------------------------------- 2 files changed, 135 insertions(+), 258 deletions(-) diff --git a/doc/BUILD.bazel b/doc/BUILD.bazel index 3a7d71565..4e3f25efe 100644 --- a/doc/BUILD.bazel +++ b/doc/BUILD.bazel @@ -13,9 +13,16 @@ _RULES_SYMBOLS = [ "swift_test", ] +_PROVIDERS_SYMBOLS = [ + "SwiftInfo", + "SwiftToolchainInfo", + "SwiftProtoInfo", + "SwiftUsageInfo", +] + write_file( - name = "gen_header", - out = "header.vm", + name = "rules_header", + out = "rules_header.vm", content = [ "", "", @@ -27,19 +34,54 @@ write_file( ], ) +write_file( + name = "providers_header", + out = "providers_header.vm", + content = [ + "", + "", + "The providers described below are propagated and required by various Swift", + "build rules. Clients interested in writing custom rules that interface", + "with the rules in this package should use these providers to communicate", + "with the Swift build rules as needed.", + "", + "On this page:", + "", + ] + [" * [{0}](#{0})".format(r) for r in _PROVIDERS_SYMBOLS] + [ + "", + ], +) + stardoc( - name = "doc", - out = "swift.md", - header_template = ":header.vm", + name = "rules_doc", + out = "rules.md_", + header_template = ":rules_header.vm", input = "//swift:swift.bzl", symbol_names = _RULES_SYMBOLS, deps = ["//swift"], ) +stardoc( + name = "providers_doc", + out = "providers.md_", + header_template = ":providers_header.vm", + input = "//swift:swift.bzl", + symbol_names = _PROVIDERS_SYMBOLS, + deps = ["//swift"], +) + # To make this test pass, run -# bazel build doc:all && cp bazel-bin/doc/swift.md doc/rules.md +# bazel build doc:all && cp bazel-bin/doc/rules.md_ doc/rules.md diff_test( - name = "test", - file1 = "swift.md", + name = "test_rules", + file1 = "rules.md_", file2 = "rules.md", ) + +# To make this test pass, run +# bazel build doc:all && cp bazel-bin/doc/providers.md_ doc/providers.md +diff_test( + name = "test_providers", + file1 = "providers.md_", + file2 = "providers.md", +) diff --git a/doc/providers.md b/doc/providers.md index 6e68f71ab..8965560ac 100644 --- a/doc/providers.md +++ b/doc/providers.md @@ -1,8 +1,4 @@ -# Providers - - - - + The providers described below are propagated and required by various Swift build rules. Clients interested in writing custom rules that interface @@ -15,9 +11,15 @@ On this page: * [SwiftToolchainInfo](#SwiftToolchainInfo) * [SwiftProtoInfo](#SwiftProtoInfo) * [SwiftUsageInfo](#SwiftUsageInfo) - + + + ## SwiftInfo +
+SwiftInfo(direct_modules, transitive_modules)
+
+ Contains information about the compiled artifacts of a Swift module. This provider contains a large number of fields and many custom rules may not @@ -25,260 +27,93 @@ need to set all of them. Instead of constructing a `SwiftInfo` provider directly, consider using the `swift_common.create_swift_info` function, which has reasonable defaults for any fields not explicitly set. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
direct_defines

List of strings. The values specified by the defines attribute of the -library that directly propagated this provider.

direct_modules

List of values returned from swift_common.create_module. The modules (both -Swift and C/Objective-C) emitted by the library that propagated this provider.

direct_swiftdocs

List of Files. The Swift documentation (.swiftdoc) files for the library -that directly propagated this provider.

direct_swiftmodules

List of Files. The Swift modules (.swiftmodule) for the library that -directly propagated this provider.

module_name

String. The name of the Swift module represented by the target that directly -propagated this provider.

-

This field will be equal to the explicitly assigned module name (if present); -otherwise, it will be equal to the autogenerated module name.

swift_version

String. The version of the Swift language that was used when compiling the -propagating target; that is, the value passed via the -swift-version compiler -flag. This will be None if the flag was not set.

transitive_defines

Depset of strings. The transitive defines specified for the library that -propagated this provider and all of its dependencies.

transitive_generated_headers

Depset of Files. The transitive generated header files that can be used by -Objective-C sources to interop with the transitive Swift libraries.

transitive_modulemaps

Depset of Files. The transitive module map files that will be passed to -Clang using the -fmodule-map-file option.

-

This field is deprecated; use transitive_modules instead.

transitive_modules

Depset of values returned from swift_common.create_module. The transitive -modules (both Swift and C/Objective-C) emitted by the library that propagated -this provider and all of its dependencies.

transitive_swiftdocs

Depset of Files. The transitive Swift documentation (.swiftdoc) files -emitted by the library that propagated this provider and all of its -dependencies.

transitive_swiftinterfaces

Depset of Files. The transitive Swift interface (.swiftinterface) files -emitted by the library that propagated this provider and all of its -dependencies.

transitive_swiftmodules

Depset of Files. The transitive Swift modules (.swiftmodule) emitted by -the library that propagated this provider and all of its dependencies.

- - - + +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| direct_modules | List of values returned from swift_common.create_module. The modules (both Swift and C/Objective-C) emitted by the library that propagated this provider. | +| transitive_modules | Depset of values returned from swift_common.create_module. The transitive modules (both Swift and C/Objective-C) emitted by the library that propagated this provider and all of its dependencies. | + + + + +## SwiftProtoInfo + +
+SwiftProtoInfo(module_mappings, pbswift_files)
+
+ +Propagates Swift-specific information about a `proto_library`. + +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| module_mappings | Sequence of structs. Each struct contains module_name and proto_file_paths fields that denote the transitive mappings from .proto files to Swift modules. This allows messages that reference messages in other libraries to import those modules in generated code. | +| pbswift_files | Depset of Files. The transitive Swift source files (.pb.swift) generated from the .proto files. | + + + + ## SwiftToolchainInfo +
+SwiftToolchainInfo(action_configs, all_files, cc_toolchain_info, cpu,
+                   generated_header_module_implicit_deps_providers, implicit_deps_providers,
+                   linker_opts_producer, linker_supports_filelist, object_format, requested_features,
+                   root_dir, supports_objc_interop, swift_worker, system_name, test_configuration,
+                   tool_configs, unsupported_features)
+
+ + Propagates information about a Swift toolchain to compilation and linking rules that use the toolchain. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
action_configs

This field is an internal implementation detail of the build rules.

all_files

A depset of Files containing all the Swift toolchain files (tools, -libraries, and other resource files) so they can be passed as tools to actions -using this toolchain.

cc_toolchain_info

The cc_common.CcToolchainInfo provider from the Bazel C++ toolchain that this -Swift toolchain depends on.

command_line_copts

List of strings. Flags that were passed to Bazel using the --swiftcopt -command line flag. These flags have the highest precedence; they are added to -compilation command lines after the toolchain default flags -(SwiftToolchainInfo.swiftc_copts) and after flags specified in the copts -attributes of Swift targets.

cpu

String. The CPU architecture that the toolchain is targeting.

linker_opts_producer

Skylib partial. A partial function that returns the flags that should be -passed to Clang to link a binary or test target with the Swift runtime -libraries.

-

The partial should be called with two arguments:

-
    -
  • is_static: A Boolean value indicating whether to link against the static -or dynamic runtime libraries.
    • -
  • is_test: A Boolean value indicating whether the target being linked is a -test target.
    • -
object_format

String. The object file format of the platform that the toolchain is -targeting. The currently supported values are "elf" and "macho".

optional_implicit_deps

List of Targets. Library targets that should be added as implicit -dependencies of any swift_library, swift_binary, or swift_test target that -does not have the feature swift.minimal_deps applied.

requested_features

List of strings. Features that should be implicitly enabled by default for -targets built using this toolchain, unless overridden by the user by listing -their negation in the features attribute of a target/package or in the ---features command line flag.

-

These features determine various compilation and debugging behaviors of the -Swift build rules, and they are also passed to the C++ APIs used when linking -(so features defined in CROSSTOOL may be used here).

required_implicit_deps

List of Targets. Library targets that should be unconditionally added as -implicit dependencies of any swift_library, swift_binary, or swift_test -target.

root_dir

String. The workspace-relative root directory of the toolchain.

supports_objc_interop

Boolean. Indicates whether or not the toolchain supports Objective-C interop.

swift_worker

File. The executable representing the worker executable used to invoke the -compiler and other Swift tools (for both incremental and non-incremental -compiles).

system_name

String. The name of the operating system that the toolchain is targeting.

test_configuration

Struct containing two fields:

-
    -
  • env: A dict of environment variables to be set when running tests -that were built with this toolchain.
    • -
  • execution_requirements: A dict of execution requirements for tests -that were built with this toolchain.
    • -
-

This is used, for example, with Xcode-based toolchains to ensure that the -xctest helper and coverage tools are found in the correct developer -directory when running tests.

tool_configs

This field is an internal implementation detail of the build rules.

unsupported_features

List of strings. Features that should be implicitly disabled by default for -targets built using this toolchain, unless overridden by the user by listing -them in the features attribute of a target/package or in the --features -command line flag.

-

These features determine various compilation and debugging behaviors of the -Swift build rules, and they are also passed to the C++ APIs used when linking -(so features defined in CROSSTOOL may be used here).

- - - -## SwiftProtoInfo -Propagates Swift-specific information about a `proto_library`. +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| action_configs | This field is an internal implementation detail of the build rules. | +| all_files | A depset of Files containing all the Swift toolchain files (tools, libraries, and other resource files) so they can be passed as tools to actions using this toolchain. | +| cc_toolchain_info | The cc_common.CcToolchainInfo provider from the Bazel C++ toolchain that this Swift toolchain depends on. | +| cpu | String. The CPU architecture that the toolchain is targeting. | +| generated_header_module_implicit_deps_providers | A struct with the following fields, which are providers from targets that should be treated as compile-time inputs to actions that precompile the explicit module for the generated Objective-C header of a Swift module:

* cc_infos: A list of CcInfo providers from targets specified as the toolchain's implicit dependencies. * objc_infos: A list of apple_common.Objc providers from targets specified as the toolchain's implicit dependencies. * swift_infos: A list of SwiftInfo providers from targets specified as the toolchain's implicit dependencies.

This is used to provide modular dependencies for the fixed inclusions (Darwin, Foundation) that are unconditionally emitted in those files.

For ease of use, this field is never None; it will always be a valid struct containing the fields described above, even if those lists are empty. | +| implicit_deps_providers | A struct with the following fields, which represent providers from targets that should be added as implicit dependencies of any Swift compilation or linking target (but not to precompiled explicit C/Objective-C modules):

* cc_infos: A list of CcInfo providers from targets specified as the toolchain's implicit dependencies. * objc_infos: A list of apple_common.Objc providers from targets specified as the toolchain's implicit dependencies. * swift_infos: A list of SwiftInfo providers from targets specified as the toolchain's implicit dependencies.

For ease of use, this field is never None; it will always be a valid struct containing the fields described above, even if those lists are empty. | +| linker_opts_producer | Skylib partial. A partial function that returns the flags that should be passed to Clang to link a binary or test target with the Swift runtime libraries.

The partial should be called with two arguments:

* is_static: A Boolean value indicating whether to link against the static or dynamic runtime libraries.

* is_test: A Boolean value indicating whether the target being linked is a test target. | +| linker_supports_filelist | Boolean. Indicates whether or not the toolchain's linker supports the input files passed to it via a file list. | +| object_format | String. The object file format of the platform that the toolchain is targeting. The currently supported values are "elf" and "macho". | +| requested_features | List of strings. Features that should be implicitly enabled by default for targets built using this toolchain, unless overridden by the user by listing their negation in the features attribute of a target/package or in the --features command line flag.

These features determine various compilation and debugging behaviors of the Swift build rules, and they are also passed to the C++ APIs used when linking (so features defined in CROSSTOOL may be used here). | +| root_dir | String. The workspace-relative root directory of the toolchain. | +| supports_objc_interop | Boolean. Indicates whether or not the toolchain supports Objective-C interop. | +| swift_worker | File. The executable representing the worker executable used to invoke the compiler and other Swift tools (for both incremental and non-incremental compiles). | +| system_name | String. The name of the operating system that the toolchain is targeting. | +| test_configuration | Struct containing two fields:

* env: A dict of environment variables to be set when running tests that were built with this toolchain.

* execution_requirements: A dict of execution requirements for tests that were built with this toolchain.

This is used, for example, with Xcode-based toolchains to ensure that the xctest helper and coverage tools are found in the correct developer directory when running tests. | +| tool_configs | This field is an internal implementation detail of the build rules. | +| unsupported_features | List of strings. Features that should be implicitly disabled by default for targets built using this toolchain, unless overridden by the user by listing them in the features attribute of a target/package or in the --features command line flag.

These features determine various compilation and debugging behaviors of the Swift build rules, and they are also passed to the C++ APIs used when linking (so features defined in CROSSTOOL may be used here). | + + + - - - - - - - - - - - - - - - -
module_mappings

Sequence of structs. Each struct contains module_name and -proto_file_paths fields that denote the transitive mappings from .proto -files to Swift modules. This allows messages that reference messages in other -libraries to import those modules in generated code.

pbswift_files

Depset of Files. The transitive Swift source files (.pb.swift) generated -from the .proto files.

- - - ## SwiftUsageInfo +
+SwiftUsageInfo(toolchain)
+
+ A provider that indicates that Swift was used by a target or any target that it depends on, and specifically which toolchain was used. - - - - - - - - - - - -
toolchain

The Swift toolchain that was used to build the targets propagating this -provider.

+ +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| toolchain | The Swift toolchain that was used to build the targets propagating this provider. | +