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 import
s 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 configure
before trying to build or run tests from Xcode (this is done automatically beforemake build
ormake 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 install
after unit tests are passing and then do my manual testing from the command line.