Clarification around ABI version

From: Petr Hosek <>
Date: Mon, 1 Oct 2018 20:00:09 -0700
Subject: Clarification around ABI version

This was raised in D52660. Today, libc++ recognizes at least 3 different ABI versions: v1, v2 (and above) and unstable, see

There are several questions that were raised in that review that I’d like to get clarity on:

  1. Is there a plan to eventually stabilize v2 and introduce v3 (and above) as the unstable version or is v2 going to be unstable forever?

Yes, the plan is to eventually stabilize v2 and introduce v3 (while hopefully phasing out v1). The “unstable” configuration is really
just a way to say "give me the vX that is currently being staged).

  1. What are the guarantees for v2? I understand that this ABI can still change, but I’m interested in testing and stability, shall we expect that v2 receives the same amount of coverage and that bugs specific to v2 will get resolved with the same priority as bugs specific to v1?

Once v2 is stable, it will have the same ABI guarentees as v1 (That is, it won’t change). When v2 is made stable, it will ideally become the default and primary configuration for the library. At which point v1 will be “deprecated-ish”, but will continue to be maintained until all stakeholders have migrated off it.
I imagine a timeline for migrating off v1 to take roughly 3-5 years.

My rough idea was to have at most three ABI versions in flight at any given time. The default configuration (currently v1), the unstable configuration where upcoming changes are staged, and a “deprecated” version that we’re working to remove (currently we don’t have one).