tayloraswift/swift-package-catalog

getting started

catalog is a normal Swift Package Plugin, and you can use it (like any other plugin) by adding it to your Package.swift dependency list:

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

running `blame`

blame can be used to discover the direct consumers of a dependency. To use blame, pass it a list of target names:

$ 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')

running `catalog`

Running catalog with swift package will output all the documentation resources it managed to find, in JSON format. Behind the scenes, it will direct the SPM to generate the relevant symbolgraphs.

$ 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"
                ]
            }
        ]
    }
]

Note: Relative paths are shown for demonstration purposes. The catalog plugin actually emits absolute paths.

You can filter the modules catalog scans by passing them as positional arguments. The order does not matter.

$ 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": 
        [
            ...
        ]
    }
]

Snippets are not bound to any module, and will therefore always appear.

Target filtering is case-sensitive.

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

Note that multiple modules with the same name can occur in a dependency tree, as long as colliding modules are never combined into the same product. This means that the number of modules cataloged by this tool may be greater than the number of arguments passed to its invocation.

Package Metadata

Repository: tayloraswift/swift-package-catalog

Default branch: master

README: README.md