Acyclic is a Scala compiler plugin that allows you to mark files within a build as acyclic, turning circular dependencies between files into compilation errors.

Acyclic is a Scala compiler plugin that allows you to mark files within a build as acyclic, turning circular dependencies between files into compilation errors.

For example, the following two files have a circular dependency between them:

In this case it is very obvious that there is a circular dependency, but in larger projects the fact that a circular dependency exists can be difficult to spot. With Acyclic, you can annotate either source file with an acyclic import:

And attempting to compile these files together will then result in a compilation error:

This applies to term-dependencies, type-dependencies, as well as cycles that span more than two files. Circular dependencies between files is something that people often don’t want, but are difficult to avoid as introducing cycles is hard to detect while working or during code review. Acyclic is designed to help you guard against unwanted cycles at compile-time, and tells you exactly where the cycles are when they appear so you can deal with them.

A more realistic example of a cycle that Acyclic may find is this one taken from a cycle in uTest:

As you can see, there is a dependency cycle between Formatter.scala, Model.scala, package.scala and TestSuite.scala. package.scala has been explicitly marked acyclic, and so compilation fails with an error. Apart from the line shown, Acyclic also gives other lines in the same file which contain dependencies contributing to this cycle.

Spotting this dependency cycle spanning 4 different files, and knowing exactly which pieces of code are causing it, is something that is virtually impossible to do manually via inspection or code-review. Using Acyclic, there is no chance of accidentally introducing a dependency cycle you don’t want, and even when you do, it shows you exactly what’s causing the cycle that you need to fix to make it go away.

Acyclic also allows you to annotate entire packages as acyclic by placing a import acyclic.pkg inside the package object. Consider the following set of files:

These 5 files do not have any file-level cycles, and form a nice linear dependency chain:

However, we may want to preserve the invariant that the package c does not have any cyclic dependencies with other packages or files.. By annotating the package with import acyclic.pkg in its package objects as shown above, we can make this circular package dependency error out:

Since, c as a whole must be acyclic, the dependency cycle between c, B.scala and A.scala is prohibited, and Acyclic errors out. As you can see, it tells you exactly where the dependencies are in the source files, giving you an opportunity to find and remove them. Here’s a realistic example from Scala.Rx:

As you can see, Dynamic.scala in rx.core was accidentally depending on Spinlock in rx.ops. That cross-module dependency from rx.core to rx.ops should not exist, and the proper solution was to move Spinlock over to rx.core. Without Acyclic, this circular dependency would likely have gone un-noticed.

Acyclic is currently being used in uTest, Scalatags and Scala.Rx, and helped remove many cycle between files which had no good reason for being cyclic. It is also being used to verify the acyclicity of its own code. It works with Scala 2.11, 2.12 and 2.13.

If you’re using incremental compilation, you may need to do a clean compile for Acyclic to find all unwanted cycles in the compilation run.

Acyclic has problems in a number of cases:

• If you use curly-braced package XXX {} acyclic inside your source files, it does the wrong thing. Acyclic assumes all packages are listed in a sequence of statements at the top of each file

• Under incremental compilation, Acyclic does not always find all possible cycles, since one cycles within the files currently getting compiled will get caught. A solution is to do a clean build every once in a while.

Acyclic is published under the MIT License:

The MIT License (MIT)

Copyright (c) 2014 Li Haoyi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.