Buck website makes unnecessary apologies about ABI fingerprinting.

[facebook]

Buck website makes unnecessary apologies about ABI fingerprinting.

[dreiss]

I'm considering changing the last part to the following. Thoughts?

In Buck, the ABI defines an equivalence relationship, whereas in the JLS, it does not. This is done because
Buck must be absolutely sure that a skipped recompilation would have produced the exact same output.
Some changes that technically preserve JLI ABI compatibility can break compilation,
so Buck recompiles any time there is a visibile ABI change.

[cakoose]

I think the term ABI should be avoided entirely. Saying "ABI" sort of implies that the important thing here is binary compatibility instead of source compatibility, which is the exact opposite of what's really going on. Overall,
I think referencing the JLS's binary compatibility section is more of a distraction than a help.

The best term I can come up with right now is "externally visible API". There may be subtle differences between a reader's idea of what "externally visible API" means and what Buck actually computes (for example, the "public static final" field inlining garbage that javac does) but I think it gets you most of the way there.

My attempt at a rewrite kills the footnote and replaces the term ABI with either "externally visible API" or "API":

Title: If a Java library's API doesn't change, code that uses the library doesn't need to be rebuilt.

Oftentimes, a developer will modify Java code in a way that does not affect its interface. For example, adding or removing private methods, as well as modifying the implementation of existing methods (regardless of their visibility), does not change the externally visible API of the code.

When Buck builds a java_library rule, it also computes its externally visible API. Normally, modifying a private method in a java_library would cause it and all rules that depend on it to be rebuilt because the change in cache keys would propagate up the DAG. However, Buck has special logic for a java_library where, if the .java input files have not changed since the previous build, and the API for each of its Java dependencies has not changed since the previous build, then the java_library will not be recompiled. This is valid because we know that neither the input .java files nor the API against which they would be compiled has changed, so the result would be the same if the rule were rebuilt. This localizes how much Java code needs to be recompiled in response to a change, again reducing build times.

[sdwilsh]

@cakoose - want to cook up a pull request for that?

[sdwilsh]

Closed by #115