[LLVMdev] [RFC] Developer Policy for LLVM C API

[David Chisnall]

On 27 Jul 2015, at 11:27, Antoine Pitrou <antoine at python.org> wrote:
> 
> Hal Finkel <hfinkel <at> anl.gov> writes:
>> 
>> Do you require long-term cross-release ABI and/or API stability
>> from the C API that you're using? Do these
>> other projects?
> 
> For the record, in llvmlite and Numba we don't require C API stability
> for two reasons:
> 
> 1) the C API is not enough for us and we rely on bits of the C++ API
> 2) we also rely on other details such as textual IR format, which change
>   from release to release anyway.

For the out-of-tree projects that I maintain, the answer is quite similar:

- The C API has never been expressive enough for everything that we need
- ABI stability is not a significant issue (we’re happy to recompile, as long as the .so versions are bumped)
- Lack of API stability causes lost developer time.

Some changes are unavoidable, but having a one-release deprecation cycle for more gratuitous refactorings (e.g. get->Get changes that seem to happen periodically) would make life easier.

It would also be helpful to have a single document describing the API changes between releases.  For example, the way that you get the size of a symbol in an ELF object changed recently, but the only way to find out what that I could find out how to change my code to the new mechanism was by finding the commit with the change, finding a consumer that looked like mine, and studying the diff.  This kind of thing significantly increases the cost for external developers to maintain projects that depend on LLVM - each API change can lead to an hour of developer time for a downstream project if it’s not obvious what the fix is.  Multiply that by the number of downstream projects and it’s a big cost.  

The changes to function attributes were the worst in recent memory - they were committed and then a few months later some vague documentation appeared.  Eventually, this was improved and is now moderately useful documentation.  I would like to see:

- Small changes to APIs (e.g. renaming methods) have compat code that’s left in for one major release and a deprecated attribute telling consumers what to use instead (ideally with a mode to not enable them, for space-conscious downstreams that are statically linking and don’t want to provide them).

- Large changes to APIs not be committed until they come with documentation describing how to migrate from the old to the new.  

ABI stability between major releases is largely irrelevant to most downstream projects: the proprietary ones compile and bundle a statically linked LLVM, the open source ones are happy to recompile.

I generally believe that the C API (as anything other than a machine-generated thin wrapper around the C++ for FFI) is misguided.  If we’re able to design good, clean, stable APIs for third-party consumers, then we should be using them internally as well.  If we aren’t (and, given how quickly requirements change, we probably aren’t), then we shouldn’t pretend to.

In many cases, the existence of the C API is used as an excuse for gratuitous API churn in the C++ APIs: if you care about stable APIs then you should use the C ones (in spite of the fact that they don’t expose the functionality that you require).

I don’t think it’s feasible for a project that evolves as rapidly as LLVM to have a completely stable API, but we could do a lot more to reduce pain for downstream consumers.

David