XCGrapher
xcgrapher is, by default, a framework-level dependency graph generator for Xcode projects. It works by reading local clones of the source, so it’s not a problem if your project relies on internal/unpublished frameworks.
However, it is so much more than just that. xcgrapher supports custom (Swift) plugins so you can easily parse your source code and quickly create graphs that are meaningful to you and your team!
Basic Usage
To produce a graph of imported Cocoapods and Swift Package Manager modules for the target SomeApp in the project SomeApp.xcodeproj:
xcgrapher --project SomeApp.xcodeproj --target SomeApp --pods --spm
This produces the following image:
You could also pass --apple to include native frameworks in the graph. See xcgrapher --help for more options.
Installation
brew tap maxchuquimia/scripts
brew install xcgrapher
gem install xcodeproj # If you use Cocoapods you probably don't need to do this
Or, just clone the project and make install.
Custom Graphs
What if (for example) your team has it’s own property wrappers for dependency injection? You can graph it’s usage that too!
Create yourself a new Swift Package and subclass XCGrapherPlugin from the package maxchuquimia/XCGrapherPluginSupport. You can override a function that will be called once with every source file in your project and it’s (SPM) dependencies. Then you can parse each file as needed and generate an array of arrows that will be drawn.
In fact, xcgrapher‘s default behaviour is implemented as a plugin too!
For full documentation take a look at the XCGrapherPluginSupport repo.
How it works
Main Project Target
xcgrapher uses xcodeproj (a Cocoapods gem) to find all the source files of the given target. It then reads them and creates a list of imports to know which --pods, --spm and/or --apple modules are part of the target.
Swift Package Manager
xcgrapher builds the --project so that all it’s SPM dependencies are cloned. It parses the build output to find the location of these clones and calls swift package describe on each. Then it iterates through all the source files of each package to find their import lines and repeats.
Cocoapods
xcgrapher uses the Podfile.lock to discover what each pod’s dependencies are. Change the location of the lockfile with the --podlock option if needed. Cocoapods source files are not currently searched so graphing links to imported Apple frameworks from a pod is unsupported, as is file-by-file processing in a custom plugin. xcgrapher is really geared towards Xcode projects and Swift Packages.
Apple
xcgrapher assumes /System/Library/Frameworks and another path (see NativeDependencyManager.swift) contains a finite list of frameworks belonging to Apple. This probably isn’t ideal for some cases, so open a PR if you know a better way!
Carthage
Carthage dependencies are currently unsupported. Need it? Add it! Conform to the DependencyManager protocol and have a look at the usage of SwiftPackageManager.
Notes on Development
Here’s a few things to bear in mind if you’re adding a feature:
- Run
make configurebefore trying to build or run tests from Xcode (this is done automatically beforemake buildormake install) - Tests pass in Xcode, however you can’t run the project from within Xcode (due to enivironment variables missing). When developing I like to just
make installafter unit tests are passing and then do my manual testing from the command line.
