Remove emit symbol graph API

Removes the now old `emit_symbol_grah` feature in favor of the new `swift_symbol_graph_extract` rule which can be used to collec the symbol graph of Swift targets. Depends on: #772 Rebase
bazelbuild · Jun 19, 2024 · ad7216b · ad7216b
1 parent 5056592
commit ad7216b
Show file tree

Hide file tree

Showing 35 changed files with 1,670 additions and 162 deletions.
diff --git a/MODULE.bazel b/MODULE.bazel
@@ -14,12 +14,18 @@ bazel_dep(name = "platforms", version = "0.0.9")
 bazel_dep(name = "protobuf", version = "21.7", repo_name = "com_google_protobuf")
 bazel_dep(name = "rules_proto", version = "5.3.0-21.7")
 bazel_dep(name = "nlohmann_json", version = "3.6.1", repo_name = "com_github_nlohmann_json")
+bazel_dep(
+    name = "swift_argument_parser",
+    version = "1.3.0",
+    repo_name = "com_github_apple_swift_argument_parser",
+)
 
 non_module_deps = use_extension("//swift:extensions.bzl", "non_module_deps")
 use_repo(
     non_module_deps,
     "build_bazel_rules_swift_index_import",
     "build_bazel_rules_swift_local_config",
+    "com_github_apple_swift_docc_symbolkit",
     "com_github_apple_swift_log",
     "com_github_apple_swift_nio",
     "com_github_apple_swift_nio_extras",

diff --git a/doc/api.md b/doc/api.md
@@ -140,10 +140,6 @@ A tuple containing three elements:
           the index store data generated by the compiler if the
           `"swift.index_while_building"` feature is enabled, otherwise
           this will be `None`.
-      *   `symbol_graph`: A `File` representing the directory that
-          contains the symbol graph data generated by the compiler if the
-          `"swift.emit_symbol_graph"` feature is enabled, otherwise this
-          will be `None`.
       *   `const_values_files`: A list of `File`s that contains JSON
           representations of constant values extracted from the source
           files, if requested via a direct dependency.
@@ -471,7 +467,7 @@ A provider whose type/layout is an implementation detail and should not
 <pre>
 swift_common.create_swift_module(<a href="#swift_common.create_swift_module-swiftdoc">swiftdoc</a>, <a href="#swift_common.create_swift_module-swiftmodule">swiftmodule</a>, <a href="#swift_common.create_swift_module-ast_files">ast_files</a>, <a href="#swift_common.create_swift_module-defines">defines</a>, <a href="#swift_common.create_swift_module-indexstore">indexstore</a>, <a href="#swift_common.create_swift_module-plugins">plugins</a>,
                                  <a href="#swift_common.create_swift_module-swiftsourceinfo">swiftsourceinfo</a>, <a href="#swift_common.create_swift_module-swiftinterface">swiftinterface</a>, <a href="#swift_common.create_swift_module-private_swiftinterface">private_swiftinterface</a>,
-                                 <a href="#swift_common.create_swift_module-const_protocols_to_gather">const_protocols_to_gather</a>, <a href="#swift_common.create_swift_module-symbol_graph">symbol_graph</a>)
+                                 <a href="#swift_common.create_swift_module-const_protocols_to_gather">const_protocols_to_gather</a>)
 </pre>
 
 Creates a value representing a Swift module use as a Swift dependency.
@@ -491,12 +487,11 @@ Creates a value representing a Swift module use as a Swift dependency.
 | <a id="swift_common.create_swift_module-swiftinterface"></a>swiftinterface |  The `.swiftinterface` file emitted by the compiler for this module. May be `None` if no module interface file was emitted.   |  `None` |
 | <a id="swift_common.create_swift_module-private_swiftinterface"></a>private_swiftinterface |  The `.private.swiftinterface` file emitted by the compiler for this module. May be `None` if no private module interface file was emitted.   |  `None` |
 | <a id="swift_common.create_swift_module-const_protocols_to_gather"></a>const_protocols_to_gather |  A list of protocol names from which constant values should be extracted from source code that takes this module as a *direct* dependency.   |  `[]` |
-| <a id="swift_common.create_swift_module-symbol_graph"></a>symbol_graph |  A `File` representing the directory that contains the symbol graph data generated by the compiler if the `"swift.emit_symbol_graph"` feature is enabled, otherwise this will be `None`.   |  `None` |
 
 **RETURNS**
 
 A `struct` containing the `ast_files`, `defines`, `indexstore,
-  `swiftdoc`, `swiftmodule`, `swiftinterface`, and `symbol_graph` fields
+  `swiftdoc`, `swiftmodule`, and `swiftinterface` fields
   provided as arguments.
 
 
@@ -538,6 +533,34 @@ This mapping is intended to be fairly predictable, but not reversible.
 The module name derived from the label.
 
 
+<a id="swift_common.extract_symbol_graph"></a>
+
+## swift_common.extract_symbol_graph
+
+<pre>
+swift_common.extract_symbol_graph(<a href="#swift_common.extract_symbol_graph-actions">actions</a>, <a href="#swift_common.extract_symbol_graph-compilation_contexts">compilation_contexts</a>, <a href="#swift_common.extract_symbol_graph-feature_configuration">feature_configuration</a>,
+                                  <a href="#swift_common.extract_symbol_graph-include_dev_srch_paths">include_dev_srch_paths</a>, <a href="#swift_common.extract_symbol_graph-minimum_access_level">minimum_access_level</a>, <a href="#swift_common.extract_symbol_graph-module_name">module_name</a>,
+                                  <a href="#swift_common.extract_symbol_graph-output_dir">output_dir</a>, <a href="#swift_common.extract_symbol_graph-swift_infos">swift_infos</a>, <a href="#swift_common.extract_symbol_graph-swift_toolchain">swift_toolchain</a>)
+</pre>
+
+Extracts the symbol graph from a Swift module.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="swift_common.extract_symbol_graph-actions"></a>actions |  The object used to register actions.   |  none |
+| <a id="swift_common.extract_symbol_graph-compilation_contexts"></a>compilation_contexts |  A list of `CcCompilationContext`s that represent C/Objective-C requirements of the target being compiled, such as Swift-compatible preprocessor defines, header search paths, and so forth. These are typically retrieved from the `CcInfo` providers of a target's dependencies.   |  none |
+| <a id="swift_common.extract_symbol_graph-feature_configuration"></a>feature_configuration |  The Swift feature configuration.   |  none |
+| <a id="swift_common.extract_symbol_graph-include_dev_srch_paths"></a>include_dev_srch_paths |  A `bool` that indicates whether the developer framework search paths will be added to the compilation command.   |  none |
+| <a id="swift_common.extract_symbol_graph-minimum_access_level"></a>minimum_access_level |  The minimum access level of the declarations that should be extracted into the symbol graphs. The default value is `None`, which means the Swift compiler's default behavior should be used (at the time of this writing, the default behavior is "public").   |  `None` |
+| <a id="swift_common.extract_symbol_graph-module_name"></a>module_name |  The name of the module whose symbol graph should be extracted.   |  none |
+| <a id="swift_common.extract_symbol_graph-output_dir"></a>output_dir |  A directory-type `File` into which `.symbols.json` files representing the module's symbol graph will be extracted. If extraction is successful, this directory will contain a file named `${MODULE_NAME}.symbols.json`. Optionally, if the module contains extensions to types in other modules, then there will also be files named `${MODULE_NAME}@${EXTENDED_MODULE}.symbols.json`.   |  none |
+| <a id="swift_common.extract_symbol_graph-swift_infos"></a>swift_infos |  A list of `SwiftInfo` providers from dependencies of the target being compiled. This should include both propagated and non-propagated (implementation-only) dependencies.   |  none |
+| <a id="swift_common.extract_symbol_graph-swift_toolchain"></a>swift_toolchain |  The `SwiftToolchainInfo` provider of the toolchain.   |  none |
+
+
 <a id="swift_common.is_enabled"></a>
 
 ## swift_common.is_enabled

diff --git a/swift/BUILD b/swift/BUILD
@@ -54,13 +54,15 @@ bzl_library(
         "//swift/internal:providers",
         "//swift/internal:swift_binary_test_rules",
         "//swift/internal:swift_common",
+        "//swift/internal:swift_extract_symbol_graph",
         "//swift/internal:swift_feature_allowlist",
         "//swift/internal:swift_import",
         "//swift/internal:swift_interop_hint",
         "//swift/internal:swift_library",
         "//swift/internal:swift_library_group",
         "//swift/internal:swift_module_alias",
         "//swift/internal:swift_package_configuration",
+        "//swift/internal:swift_symbol_graph_aspect",
         "//swift/internal:swift_usage_aspect",
     ],
 )

diff --git a/swift/internal/BUILD b/swift/internal/BUILD
@@ -192,6 +192,45 @@ bzl_library(
         ":linking",
         ":providers",
         ":swift_clang_module_aspect",
+        ":symbol_graph_extracting",
+    ],
+)
+
+bzl_library(
+    name = "swift_symbol_graph_aspect",
+    srcs = ["swift_symbol_graph_aspect.bzl"],
+    visibility = ["//swift:__subpackages__"],
+    deps = [
+        ":attrs",
+        ":derived_files",
+        ":features",
+        ":providers",
+        ":symbol_graph_extracting",
+        ":utils",
+        "@bazel_skylib//lib:dicts",
+    ],
+)
+
+bzl_library(
+    name = "swift_extract_symbol_graph",
+    srcs = ["swift_extract_symbol_graph.bzl"],
+    visibility = ["//swift:__subpackages__"],
+    deps = [
+        ":derived_files",
+        ":providers",
+        ":swift_symbol_graph_aspect",
+    ],
+)
+
+bzl_library(
+    name = "symbol_graph_extracting",
+    srcs = ["symbol_graph_extracting.bzl"],
+    visibility = ["//swift:__subpackages__"],
+    deps = [
+        ":actions",
+        ":providers",
+        ":toolchain_config",
+        ":utils",
     ],
 )
 
@@ -336,6 +375,7 @@ bzl_library(
         ":feature_names",
         ":features",
         ":providers",
+        ":symbol_graph_extracting",
         ":toolchain_config",
         ":utils",
         "@bazel_skylib//lib:collections",
@@ -391,6 +431,7 @@ bzl_library(
         ":output_groups",
         ":providers",
         ":swift_common",
+        ":swift_symbol_graph_aspect",
         ":utils",
         "@bazel_skylib//lib:dicts",
     ],

diff --git a/swift/internal/actions.bzl b/swift/internal/actions.bzl
@@ -45,6 +45,11 @@ swift_action_names = struct(
     # headers, emitting a `.pcm` file.
     PRECOMPILE_C_MODULE = "SwiftPrecompileCModule",
 
+    # Extracts a JSON-formatted symbol graph from a module, which can be used as
+    # an input to documentation generating tools like `docc` or analyzed with
+    # other tooling.
+    SYMBOL_GRAPH_EXTRACT = "SwiftSymbolGraphExtract",
+
     # Produces files that are usually fallout of the compilation such as
     # .swiftmodule, -Swift.h and more.
     DERIVE_FILES = "SwiftDeriveFiles",