Build Systems

Bazel

Bazel support is provided by rules_periphery. See Installation for module setup.

To scan your project, declare a target in your root BUILD.bazel:

load("@rules_periphery//:defs.bzl", "scan_auto")

scan_auto(
    name = "scan_auto",
)

bazel run //:scan_auto

Running the target queries your project to identify all top-level targets, generates a hidden implementation of the scan rule, and then invokes bazel run. You can filter the default top-level target query with the filter attribute, whose value is passed as the first argument to Bazel’s filter operator. You can also override the generated query entirely with the query attribute, which is useful when you need to exclude targets such as ones tagged manual, or avoid building targets that use an incorrect transition when built directly. The generated query can be seen in the console with the --verbose option.

Periphery’s generated scan rule follows embedded bundle and plugin edges transitively, so you can root the scan in application targets while still analyzing code that is only reachable through extensions, app clips, watch applications, or Swift compiler plugins.

Tip

By default, Periphery passes --check_visibility=false to bazel run to simplify integration, since the generated scan target references your project’s targets which may not otherwise be visible. However, disabling visibility checking can invalidate Bazel’s analysis cache, resulting in slower subsequent builds.

You can enable visibility checking with the check_visibility attribute. You must ensure the necessary targets are visible to Periphery’s generated package, for example by adding the @rules_periphery//:generated visibility label to your targets.

Declaring scan targets

If you’d rather maintain the list of scanned targets by hand — for example to scan a specific subset of your project, or to run Periphery in CI via bazel test — you can declare scan targets directly in your BUILD.bazel files:

load("@rules_periphery//:rules.bzl", "scan", "scan_report", "scan_test")

# Prints results with `bazel run //:scan`.
scan(
    name = "scan",
    config = ".periphery.yml",
    deps = [
        "//App:MyApp",
        "//Tests:MyAppTests",
    ],
)

# Fails `bazel test //:scan_test` when unused code is found.
scan_test(
    name = "scan_test",
    config = ".periphery.yml",
    deps = [
        "//App:MyApp",
        "//Tests:MyAppTests",
    ],
)

# Writes a report file at build time that other rules can consume.
scan_report(
    name = "scan_report",
    config = ".periphery.yml",
    format = "json",
    deps = [
        "//App:MyApp",
        "//Tests:MyAppTests",
    ],
)

See the rules_periphery documentation for the full set of attributes.

Other Build Systems

Periphery can analyze projects using other build systems, though it cannot drive them automatically like SPM, Xcode, and Bazel. Instead, you need to create a configuration file that specifies the location of indexstore and other resource files:

{
    "indexstores": [
        "path/to/file.indexstore"
    ],
    "test_targets": [
        "MyTests"
    ],
    "plists": [
        "path/to/file.plist"
    ],
    "xibs": [
        "path/to/file.xib",
        "path/to/file.storyboard"
    ],
    "xcdatamodels": [
        "path/to/file.xcdatamodel"
    ],
    "xcmappingmodels": [
        "path/to/file.xcmappingmodel"
    ]
}

Tip

Relative paths are assumed to be relative to the current directory.

You can then invoke Periphery as follows:

periphery scan --generic-project-config config.json