Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Why use the .api extension and not .abi? #198

Open
joffrey-bion opened this issue Mar 20, 2024 · 6 comments
Open

Why use the .api extension and not .abi? #198

joffrey-bion opened this issue Mar 20, 2024 · 6 comments
Labels

Comments

@joffrey-bion
Copy link
Contributor

joffrey-bion commented Mar 20, 2024

Given that these files are meant to represent a serialized ABI to check binary compatibility, and that the tool is called binary-compatibility-validator it would make sense to call this the ABI, right?

@qwwdfsad
Copy link
Collaborator

It indeed makes sense. This is rather a historical oddity where we first started with "what is public API" and then every other name just followed.
If we ever consider pushing BCV to 1.0 or merging it into Kotlin upstream, we definitely should consider the renaming

@joffrey-bion
Copy link
Contributor Author

I see, thanks. I was thinking that maybe because of the change in structure with the klib / KMP support, it might be a good time to change the extension too

@fzhinkin
Copy link
Collaborator

We thought about that too, but changing the name of JVM dump files would be painful for existing users, and having two files (for KLib and class files) with the (conceptually) same stuff inside but different names looked weird.

@joffrey-bion
Copy link
Contributor Author

changing the name of JVM dump files would be painful for existing users

In which way?

These files are updated each time an ABI change happens, so it's already part of the process to update them/commit them in some way. Making a source code change + apiDump + commit is as complicated as making a plugin version update + apiDump + commit. Git is quite good at recognizing the file even with a different name if the contents don't change. Is there something I am missing?

@fzhinkin
Copy link
Collaborator

In which way?

  • If we change the file extension name, plugin's update in a project will make the dump invalid (well, the dump will not exists from plugin's POV) even if nothing had changed in the ABI;
  • git --follow helps with renaming, but it's not something working out of the box.

Given that the new release introduces experimental feature useful for some developers (those who owns KMP projects), it's hard to justify why everyone else should be disturbed.

As Vsevolod said, it's something that could be done with a major release, but for now we decided to stick to existing naming convention.

@joffrey-bion
Copy link
Contributor Author

joffrey-bion commented Mar 20, 2024

plugin's update in a project will make the dump invalid

Yes, and the good thing about it is that it's a conscious decision, so nothing surprising to the users here. It has happened several times in the past that updating the Kotlin plugin breaks the dumps (which is arguably more surprising), and at least for me personally it has never been more painful than forgetting to apiDump after a code change.

Also, enabling the klib support flag (which I guess one day will be the default) already moves the dumps, so we may as well capitalize on this :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants