Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for symbol graph extraction #772

Merged
merged 5 commits into from
Jun 19, 2024
Merged

Add support for symbol graph extraction #772

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c3998db
Add support for symbol graph extraction.
allevato Feb 23, 2022
1e11915
Add a test discovery tool that uses SymbolKit to detect `XCTestCase` …
allevato Feb 23, 2022
8079ec2
Update the `swift_test` rule to perform test discovery if a target is…
allevato Feb 23, 2022
5005c20
Affix the class name to distinguish the `__allTests` arrays generated…
allevato Mar 9, 2022
4f132c9
Add symbol graph extraction support to swift_toolchain for Linux
luispadron Jun 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions MODULE.bazel
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
28 changes: 28 additions & 0 deletions doc/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -538,6 +538,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
Expand Down
2 changes: 2 additions & 0 deletions swift/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
],
)
Expand Down
41 changes: 41 additions & 0 deletions swift/internal/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
],
)

Expand Down Expand Up @@ -336,6 +375,7 @@ bzl_library(
":feature_names",
":features",
":providers",
":symbol_graph_extracting",
":toolchain_config",
":utils",
"@bazel_skylib//lib:collections",
Expand Down Expand Up @@ -391,6 +431,7 @@ bzl_library(
":output_groups",
":providers",
":swift_common",
":swift_symbol_graph_aspect",
":utils",
"@bazel_skylib//lib:dicts",
],
Expand Down
5 changes: 5 additions & 0 deletions swift/internal/actions.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
37 changes: 23 additions & 14 deletions swift/internal/compiling.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [
swift_toolchain_config.add_arg("-disallow-use-new-driver"),
Expand All @@ -193,8 +193,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [
swift_toolchain_config.add_arg(
Expand All @@ -212,8 +212,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [
swift_toolchain_config.add_arg(
Expand All @@ -232,8 +232,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [
swift_toolchain_config.add_arg(
Expand Down Expand Up @@ -607,6 +607,7 @@ def compile_action_configs(
swift_toolchain_config.action_config(
actions = [
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [_pcm_developer_framework_paths_configurator],
),
Expand Down Expand Up @@ -777,8 +778,9 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [
swift_toolchain_config.add_arg("-Xcc", "-Xclang"),
Expand Down Expand Up @@ -876,8 +878,9 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [
swift_toolchain_config.add_arg(
Expand All @@ -893,7 +896,7 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.PRECOMPILE_C_MODULE,
# swift_action_names.SYMBOL_GRAPH_EXTRACT, # TODO: Enable once supported
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [
swift_toolchain_config.add_arg(
Expand Down Expand Up @@ -963,6 +966,7 @@ def compile_action_configs(
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.DUMP_AST,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [_dependencies_swiftmodules_configurator],
not_features = [
Expand Down Expand Up @@ -1043,6 +1047,7 @@ def compile_action_configs(
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.DUMP_AST,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [
lambda prereqs, args: _framework_search_paths_configurator(
Expand Down Expand Up @@ -1072,8 +1077,9 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [
_clang_search_paths_configurator,
Expand All @@ -1088,8 +1094,9 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [_dependencies_clang_modules_configurator],
features = [SWIFT_FEATURE_USE_C_MODULES],
Expand All @@ -1099,8 +1106,9 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [_dependencies_clang_modulemaps_configurator],
not_features = [SWIFT_FEATURE_USE_C_MODULES],
Expand Down Expand Up @@ -1198,8 +1206,9 @@ def compile_action_configs(
actions = [
swift_action_names.COMPILE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.SYMBOL_GRAPH_EXTRACT,
],
configurators = [_module_name_configurator],
),
Expand All @@ -1208,8 +1217,8 @@ def compile_action_configs(
actions = [
swift_action_names.COMPILE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [_package_name_configurator],
),
Expand Down Expand Up @@ -1294,8 +1303,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [
lambda _, args: args.add_all(
Expand Down Expand Up @@ -1329,8 +1338,8 @@ def compile_action_configs(
swift_action_names.COMPILE,
swift_action_names.COMPILE_MODULE_INTERFACE,
swift_action_names.DERIVE_FILES,
swift_action_names.PRECOMPILE_C_MODULE,
swift_action_names.DUMP_AST,
swift_action_names.PRECOMPILE_C_MODULE,
],
configurators = [_source_files_configurator],
),
Expand Down
24 changes: 12 additions & 12 deletions swift/internal/derived_files.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,18 +68,6 @@ def _indexstore_directory(actions, target_name):
"""
return actions.declare_directory("{}.indexstore".format(target_name))

def _symbol_graph_directory(actions, target_name):
"""Declares a directory in which the compiler's symbol graph will be written.

Args:
actions: The context's actions object.
target_name: The name of the target being built.

Returns:
The declared `File`.
"""
return actions.declare_directory("{}.symbolgraph".format(target_name))

def _intermediate_bc_file(actions, target_name, src):
"""Declares a file for an intermediate llvm bc file during compilation.

Expand Down Expand Up @@ -373,6 +361,18 @@ def _swiftsourceinfo(actions, add_target_name_to_output_path, target_name, modul
"{}.swiftsourceinfo".format(module_name),
)

def _symbol_graph_directory(actions, target_name):
"""Declares a directory for symbol graphs extracted from a Swift module.

Args:
actions: The context's actions object.
target_name: The name of the target being built.

Returns:
The declared `File`.
"""
return actions.declare_directory("{}.symbolgraphs".format(target_name))

def _vfsoverlay(actions, target_name):
"""Declares a file for the VFS overlay for a compilation action.

Expand Down
7 changes: 6 additions & 1 deletion swift/internal/linking.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,14 @@ _OBJC_PROVIDER_LINKING = hasattr(apple_common.new_objc_provider(), "linkopt")

def binary_rule_attrs(
*,
additional_deps_aspects = [],
additional_deps_providers = [],
stamp_default):
"""Returns attributes common to both `swift_binary` and `swift_test`.

Args:
additional_deps_aspects: A list of additional aspects that should be
applied to the `deps` attribute of the rule.
additional_deps_providers: A list of lists representing additional
providers that should be allowed by the `deps` attribute of the
rule.
Expand All @@ -65,7 +68,9 @@ def binary_rule_attrs(
"""
return dicts.add(
swift_compilation_attrs(
additional_deps_aspects = [swift_clang_module_aspect],
additional_deps_aspects = [
swift_clang_module_aspect,
] + additional_deps_aspects,
additional_deps_providers = additional_deps_providers,
requires_srcs = False,
),
Expand Down
Loading