About binary compatibility and the following documentation: <https://kotlinlang.org/docs/jvm-api-gui...

# getting-started

[Johann Pardanaud]

About binary compatibility and the following documentation: https://kotlinlang.org/docs/jvm-api-guidelines-backward-compatibility.html#don-t-add-arguments-to-existing-api-functions

How recompiling only the lib.kt file can happen? Maybe due to incremental builds? Shouldn't the compiler see the lib.kt changed and then recompile the client.kt too?

If I publish my library on maven central, and users use gradle to add them to their project and build everything, is this going to be an issue?

[Robert Williams]

One common place where binary compatibility is a big problem is with transitive dependencies
eg I use lib 1.0 which was compiled against baseLib 1.0 in my app
I then either directly or via another dependency update baseLib to 2.0 which is binary incompatible
My code will get recompiled if it had a dependency on baseLib but not if it had a dependency only on lib; lib will never get recompiled (and I may not even have the source for it)
This will appear to work fine until lib calls the incompatible method and will give a strange crash. The only fix is to ask the maintainer of lib to make a new version based on baseLib 2.0 (which may then be incompatible with other existing consumers)

[Johann Pardanaud]

That's crystal clear, thank you!

[Johann Pardanaud]

Now, I understand adding arguments to a function will break backward compatibility, but how can we fix this? By creating an overload of the same function with the new argument?

[Robert Williams]

Yep, that's the suggested fix on that page:

For the JVM, it's possible to work around this: You need to add a @JvmOverloads annotation. For multiplatform projects, there is no workaround.

[Johann Pardanaud]

Oh right, I did not see this!

When they say:

For multiplatform projects, there is no workaround.

They mean there is no workaround for new arguments only? But writing a new overload is OK for multiplatform?

[Robert Williams]

Yeah, the wording's a bit confusing and kind of hidden but I guess they mean the workaround is to the specific advice "Don't add arguments to existing API functions"

[Robert Williams]

If you make a new overload that's adding new API functions so it's not really a workaround

[Johann Pardanaud]

yeah, that was what I thought, perfect then!

[Johann Pardanaud]

thank you for your help 🙂