How to display your Android project dependency graph in your README file

Make your CI work for you and watch your dependency graph take shape

Fred Porciúncula
Oct 14 · 4 min read

You can also read this in Portuguese here 🇧🇷

Image for post
Image for post
Photo by Alla Hetman on Unsplash

As I’ve been writing my first highly modularized Android app for the last 6 months, I had to constantly look at how the dependency graph (composed by the Gradle modules) was evolving. You usually may have an initial idea on how your graph should look like, but new ideas and unexpected issues arise, so it’s hard to always stick to the plan and it’s normal to move things around once in a while, especially in the beginning of the project. Being able to look at the current graph structure really helps making decisions and move forward.

In the very beginning I had drawings and pictures of drawings from previous discussions with colleagues to guide my design. As the graph was taking its own shape, I started using Jake Wharton's Gradle task to generate a visual representation of the graph so I could look at it from time to time. At some point I realized how valuable the information I was getting out of it was: it guided my decisions on how a new module could fit there, it helped me prevent circular dependencies, and it made me happy to see how the project was growing.

For the size of my project, I realized the graph would also be extremely helpful for someone getting onboarded in the codebase. So as I was randomly working in the README file one day, I thought to myself: "it would be cool to have the graph here, but it's a shame how it would get out of date super quickly". Until I gave it a bit more thought and the idea behind this blogpost was born.

Show me the code

This gist has everything you need, but you can also look at it in action in this repo. There's really not a lot to it:

  1. We need the projectDependencyGraph Gradle task, so the first step is to add it in our project and reference it in our root build file.
  2. There's a small change we need to make there, though: it originally creates the dot file within rootProject.buildDir, which is usually ignored by our version control system. Instead, we can use rootProject.rootDir and place the graph somewhere within our project.
  3. Then we need to define the GitHub action that will automatically generate, commit and push the graph. This is what the job looks like:
We’re using GitHub Actions here, but it’s most likely possible to write those same steps with your favorite tool.

Thankfully there's a great GitHub action that sets up Graphviz for us, which is the tool used by the Gradle task to generate the graph. That's our second step there: ts-graphviz/setup-graphviz@v1. Third step is then running the task to generate the graph.

Once we have the graph, we need to commit it. We simply run a few Git commands to setup the user that'll own the commit and for the commit itself. We want to make sure the command doesn't fail if there are no changes (maybe the graph hasn't changed since the last time it was updated), that's why the command looks odd. Don't ask me about it, I just copied from here 💁‍♂️

Lastly we have to push, and again there's an action for that. Even though our action is pushing to master, it won't trigger a new run even if the workflow is configured to be triggered by pushes to master, so there's no concern around being stuck in recursive runs.

Show me the graph

With the Gradle task and the GitHub action in place, we can now simply reference the graph PNG file like this in the README:

It'll depend on what output directory we chose, but that's pretty much it! ✨

It's great to see the magic happening:

Image for post
Image for post
I wish all documentation could update itself like that.

If you see a way to improve this setup or have any idea on how to apply the general concept in another scenario, hit my up on Twitter!

Google Developers Experts

Experts on various Google products talking tech.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store