Using Periphery

Scan Command

The scan command is Periphery's primary function. To begin an interactive guided setup, simply change to your project directory and run:

periphery scan

After answering a few questions, Periphery will print out the full scan command with appropriate arguments for your project, and execute it.

How It Works

Periphery first builds all of the schemes provided via the --schemes option using xcodebuild. It then indexes all files that are members of the targets passed to the --targets option, resulting in a graph of declarations and references. Finally, it performs numerous mutations on the graph then analyzes it to identify unused declarations.

For example, if your Xcode workspace consists of a single application and multiple frameworks all defined in separate projects, you'd choose a scheme that builds the application and framework targets. Typically any dependent frameworks would be built implicitly if they're used by the application, so you'd likely only need to specify your application's main scheme.

It's important to specify a complete set of targets for the --targets option. For the example above, we'd need to specify the application target, and each framework target. If you did not include your application target, then Periphery would correctly identify that many public interfaces of your frameworks are unused.

The scan options for this example would be as follows:

periphery scan --workspace MyApp.xcworkspace --schemes MyApp --targets MyApp,FrameworkA,FrameworkB --format xcode

If your project consists of one or more standalone frameworks that do not also contain some kind of application that consume their interfaces, then you'll need to tell Periphery to assume that all public declarations are in fact used by including the --retain-public option.

If your project is 100% Swift, then you'll likely want to include the --no-retain-objc-annotated option. For projects that are mixed Objective-C/Swift, we highly recommend you read about the implications this can have on your results in the Objective-C section.

Aggressive Mode

By default Periphery aims to only report declarations that are safe to remove. In practice however, there are some scenarios in which code has a very high likelihood of being unused, but which cannot be guaranteed by static analysis alone. Such analysis techniques that may produce false negatives are only enabled in aggressive mode.

To enable aggressive mode:

periphery scan --aggressive ...
More scrutiny is advised when reviewing results produced by aggressive mode. Some results may appear at first glance to be unused, and indeed your application may compile successfully after removal, however you should keep in mind how the removal might affect dynamic runtime behavior. With great power comes great responsibility!

The following scenarios are identified by aggressive mode:

Activating Periphery

To activate Periphery you'll need the license key emailed to you after purchase. The email contains your email address and license key, these must be entered into Periphery exactly as they are in the email.

To activate using an interactive prompt:

periphery activate

Alternatively, you can activate non-interinteractively by passing the --email and --key options to activate.

Updating Periphery

We are continually enhancing Periphery's accuracy and performance - we recommend you update often.

New versions often contain new heuristics which can identify previously unknown segments of unused code.

brew cask upgrade periphery