package-catalog
0.4.0

swift package index versions swift package index platforms

catalog 是一个简单但功能强大的 Swift Package 插件，用于生成符号图 (symbolgraph)、收集代码片段 (snippets) 以及检测项目中的 DocC 文档资源。

它类似于 swift-docc-plugin，但它实际上并不构建文档，而只是生成和定位使用 Swift Package Manager 的符号图和项目扫描功能构建文档所需的资源。

catalog 以 JSON 格式输出文档元数据，格式相当简单明了。其输出旨在易于被下游工具转换，这些工具可以消费、重新定位、压缩或以其他方式后处理这些元数据。

从 v0.4.0 版本开始，swift-package-catalog 包含两个工具

  1. blame
  2. catalog

入门指南

catalog 是一个普通的 Swift Package 插件，您可以像使用任何其他插件一样使用它，只需将其添加到您的 Package.swift 依赖项列表中即可

let package:Package = .init(name: "example", products: [],
    dependencies: 
    [
        .package(url: "https://github.com/kelvin13/swift-package-catalog", from: "0.4.0"),
    ],
    targets: [])

运行 blame

blame 可用于发现依赖项的直接使用者。要使用 blame，请向其传递目标名称列表

$ swift package blame Atomics NIOCore
direct consumers of Atomics:
0. NIOEmbedded (in 'swift-nio')
1. NIOPosix (in 'swift-nio')

direct consumers of NIOCore:
0. NIO (in 'swift-nio')
1. NIOEmbedded (in 'swift-nio')
2. NIOPosix (in 'swift-nio')
3. NIOSSL (in 'swift-nio-ssl')
4. NIOTLS (in 'swift-nio')

运行 catalog

使用 swift package 运行 catalog 将以 JSON 格式输出它设法找到的所有文档资源。在幕后，它将指示 SPM 生成相关的符号图。

$ swift package catalog
Building for debugging...
Build complete! (0.08s)
Building for debugging...
Build complete! (0.07s)
[
    {
        "catalog_tools_version": 3,
        "package": "swift-grammar", 
        "modules": 
        [
            {
                "module": "Grammar",
                "dependencies": [],
                "include": 
                [
                    ".build/x86_64-unknown-linux-gnu/extracted-symbols/swift-grammar/Grammar"
                ]
            }
        ],
        "snippets": 
        [
        ]
    }, 
    {
        "catalog_tools_version": 3,
        "package": "swift-json", 
        "modules": 
        [
            {
                "module": "JSON",
                "dependencies": [{"package": "swift-grammar", "modules": ["Grammar"]}],
                "include": 
                [
                    ".build/x86_64-unknown-linux-gnu/extracted-symbols/swift-json/JSON", 
                    "Sources/JSON/JSON.docc"
                ]
            }
        ],
        "snippets": 
        [
            {
                "snippet": "LintingDictionary",
                "dependencies": 
                [
                    {
                        "package": "swift-grammar", 
                        "modules": ["Grammar"]
                    }, 
                    {
                        "package": "swift-json", 
                        "modules": ["JSON"]
                    }
                ],
                "sources": 
                [
                    "Snippets/LintingDictionary.swift"
                ]
            }, 
            {
                "snippet": "BasicDecoding",
                "dependencies": 
                [
                    {
                        "package": "swift-grammar", 
                        "modules": ["Grammar"]
                    }, 
                    {
                        "package": "swift-json", 
                        "modules": ["JSON"]
                    }
                ],
                "sources": 
                [
                    "Snippets/BasicDecoding.swift"
                ]
            }
        ]
    }
]

注意：相对路径仅为演示目的而显示。catalog 插件实际上发出的是绝对路径。

您可以通过传递模块作为位置参数来过滤 catalog 扫描的模块。顺序无关紧要。

$ swift package catalog JSON 
Building for debugging...
Build complete! (0.07s)
[
    {
        "catalog_tools_version": 3,
        "package": "swift-json", 
        "modules": 
        [
            {
                "module": "JSON",
                "dependencies": [{"package": "swift-grammar", "modules": ["Grammar"]}],
                "include": 
                [
                    ".build/x86_64-unknown-linux-gnu/extracted-symbols/swift-json/JSON", 
                    "sources/json.docc"
                ]
            }
        ],
        "snippets": 
        [
            ...
        ]
    }
]

代码片段不绑定到任何模块，因此将始终显示。

目标过滤区分大小写。

$ swift package catalog json
error: target 'json' is not a swift source module in this package

请注意，具有相同名称的多个模块可能出现在依赖树中，只要冲突的模块永远不会组合到同一个产品中。这意味着此工具编目的模块数量可能大于传递给其调用的参数数量。