{"id":22830,"date":"2025-08-26T09:00:52","date_gmt":"2025-08-26T16:00:52","guid":{"rendered":"https:\/\/engineering.fb.com\/?p=22830"},"modified":"2025-08-26T11:25:05","modified_gmt":"2025-08-26T18:25:05","slug":"enabling-kotlin-incremental-compilation-on-buck2","status":"publish","type":"post","link":"https:\/\/engineering.fb.com\/2025\/08\/26\/open-source\/enabling-kotlin-incremental-compilation-on-buck2\/","title":{"rendered":"Enabling Kotlin incremental compilation on Buck2"},"content":{"rendered":"

The Kotlin incremental compiler has been a true gem for developers chasing faster compilation since its introduction in build tools. Now, we\u2019re excited to bring its benefits to <\/span>Buck2<\/span><\/a> \u2013\u00a0 Meta\u2019s build system \u2013 to unlock even more speed and efficiency for Kotlin developers.<\/span>
\n<\/span><\/p>\n

Unlike a traditional compiler that recompiles an entire module every time, an incremental compiler focuses only on what was changed. This cuts down compilation time in a big way, especially when modules contain a large number of source files.<\/span><\/p>\n

Buck2 promotes small modules as a key strategy for achieving fast build times. Our codebase followed that principle closely, and for a long time, it worked well. With only a handful of files in each module, and Buck2’s support for fast incremental builds and parallel execution, incremental compilation didn\u2019t seem like something we needed.<\/span><\/p>\n

But, let\u2019s be real: Codebases grow, teams change, and reality sometimes drifts away from the original plan. Over time, some modules started getting bigger \u2013 either from legacy or just organic growth. And while big modules were still the exception, they started having quite an impact on build times.<\/span><\/p>\n

So we gave the Kotlin incremental compiler a closer look \u2013 and we\u2019re glad we did. The results? Some <\/span>critical modules now build up to 3x faster<\/b>. That\u2019s a big win for developer productivity and overall build happiness.\u00a0<\/span><\/p>\n

Curious about how we made it all work in Buck2? Keep reading. We\u2019ll <\/span>walk you through the steps we took to bring the Kotlin incremental compiler to life<\/b> in our Android toolchain.<\/span><\/p>\n

Step 1: Integrating Kotlin\u2019s Build Tools API<\/span><\/h2>\n

As of Kotlin 2.2.0, the only guaranteed public contract to use the compiler is through the command-line interface (CLI). But since the CLI doesn\u2019t support incremental compilation (at least for now), it didn\u2019t meet our needs. Alternatively, we could integrate the Kotlin incremental compiler directly via the internal compiler\u2019s components \u2013 APIs that are technically accessible but not intended for public use. However, relying on them would\u2019ve made our toolchain fragile and likely to break with every Kotlin update since there\u2019s no guarantee of backward compatibility. That didn\u2019t seem like the right path either.<\/span><\/p>\n

Then we came across the Build Tools API (<\/span>KEEP<\/span><\/a>), introduced in Kotlin 1.9.20 as the official integration point for the compiler \u2013 including support for incremental compilation. Although the API was still marked as experimental, we decided to give it a try. We knew it would eventually stabilize, and saw it as a great opportunity to get in early, provide feedback, and help shape its direction. Compared to using internal components, it offered a far more sustainable and future-proof approach to integration.<\/span><\/p>\n

\u26a0\ufe0f Depending on kotlin-compiler? Watch out!<\/span><\/h3>\n

In the Java world, a <\/span>shaded<\/span><\/i> library is a modified version of the library where the class and package names are changed. This process \u2013 called shading \u2013 is a handy way to avoid classpath conflicts, prevent version clashes between libraries, and keeps internal details from leaking out.<\/span><\/p>\n

Here\u2019s quick example:<\/span>
\n<\/span><\/p>\n