Subject: symbols.map stanza names

From: Alan Griffiths <[email-masked]>
Date: Fri, 28 Aug 2015 16:46:24 +0100

The current approach to naming stanzas in the symbol maps leads to a
potential for mistakes. For example, src/platform/symbols.map has the
following stanzas:

MIRPLATFORM_9 {
...
}

MIRPLATFORM_9.1 {
...
} MIRPLATFORM_9;

It is far from obvious when adding a symbol whether it should be added
to MIRPLATFORM_9.1 or to a new MIRPLATFORM_9.2. As it happens
MIRPLATFORM_9.1 was created after 0.15 was branched so that is the
"right one". But it isn't obvious: If MIRPLATFORM_9.1 had shipped in
0.15 then MIRPLATFORM_9.2 would be right.

I don't know of any reason why we name stanzas this way except "tradition".

What does the team think of using this instead?

MIRPLATFORM_9_new_symbols_from_0.16 {
...
} MIRPLATFORM_9;

And after we branch release 0.16 it is clearer we should add:

MIRPLATFORM_9_new_symbols_from_0.17 {
...
} MIRPLATFORM_9_new_symbols_from_0.16;

When the ABI breaks we consolidate as before.

---

From: Alexandros Frantzis <[email-masked]>
Date: Fri, 28 Aug 2015 19:27:08 +0300

> When the ABI breaks we consolidate as before.

+1 to including the release version in the stanza name.

As for the naming scheme I would propose the following variation:

MIRPLATFORM_9_symbols_from_0.15
MIRPLATFORM_9_symbols_from_0.16
...

and when we bump ABI and consolidate, let's say in 0.17:

MIRPLATFORM_10_symbols_from_0.17

Thanks,
Alexandros

---

From: Christopher James Halse Rogers <[email-masked]>
Date: Mon, 31 Aug 2015 10:28:39 +1000

> MIRPLATFORM_10_symbols_from_0.17

This seems sensible; I'd probably paint the bikeshed MIRPLATFORM_9+0.16.

We're not constrained by matching SOVER here, so we could even go crazy 
and call them MIRPLATFORM_0.16 etc. I don't know if encoding the SOVER 
there is valuable.

If we do this it'd be nice if the current version to target was in at 
least one of the IRC topics :)

---

From: Daniel van Vugt <[email-masked]>
Date: Mon, 31 Aug 2015 09:57:22 +0800

I've considered using your suggested approach but also been using an 
arguably cleaner solution for around the past year[*]. If you look in 
src/client/symbols.map you will find:

   MIR_CLIENT_9.1 {  # New functions in Mir 0.15

It's no less foolproof than what you suggest, but has the added benefit 
of not over-growing symbol names embedded in the binaries.

Given that symbol name length is a major cause of binary bloat in C++ 
already, that's something to consider...

[*] Past year but you won't find many traces of it because we keep 
deleting the entries with comments when they get subsumed by major ABI 
bumps.

---

From: Daniel van Vugt <[email-masked]>
Date: Mon, 31 Aug 2015 10:34:57 +0800

Although you can easily avoid being wordy and have the best of both worlds:

   MIRPLATFORM_9.0.16
   MIRPLATFORM_9.0.17

---

From: Daniel van Vugt <[email-masked]>
Date: Mon, 31 Aug 2015 11:25:49 +0800

I think there's another reason to not use the plural "symbols" in the 
stanza name as has been suggested. Because we're actually talking about 
the end result of how individual symbols are named:

   some_new_function@@MIR_PLATFORM_9.2
   [email-masked]   # Slightly less new

So ideally each one should not be named "*symbols*". Even using the word 
"symbol" is redundant. We're just adding version suffixes really, so 
keep that in mind.

---

From: Alan Griffiths <[email-masked]>
Date: Tue, 01 Sep 2015 17:39:52 +0100

On 31/08/15 04:25, Daniel van Vugt wrote:
> stanza name as has been suggested. Because we're actually talking
> about the end result of how individual symbols are named:
>
> So ideally each one should not be named "*symbols*". Even using the
> word "symbol" is redundant. We're just adding version suffixes really,
> so keep that in mind.

OK, how about:

MIR_PLATFORM_9v0.16.0

---

From: Daniel van Vugt <[email-masked]>
Date: Wed, 2 Sep 2015 10:45:11 +0800

Yes MIR_PLATFORM_9v0.16.0 would work. Although I had hoped that we don't 
get into the habit of adding to the ABI in point releases, so it could 
be just: MIR_PLATFORM_9v0.16

I'm also open to replacing 'v' with something non-alphanumeric.

The same scheme could be applied to the library file names too:
    https://bugs.launchpad.net/mir/+bug/1490428

Although the 'v' doesn't feel like the cleanest syntax. In an ideal 
world your ABI number _is_ you major version number, so it just works 
out as a version string.

---

From: Daniel van Vugt <[email-masked]>
Date: Wed, 2 Sep 2015 11:26:59 +0800

Hypothetically the "9" could now go away. Internally that's fine:
    MIR_PLATFORM_0.16

But externally if we started naming the files as such then it might get 
confusing:
    libmirplatform.so.0.17.0
    libmirplatform.so.0.16 -> libmirplatform.so.0.17.0
    libmirplatform.so -> libmirplatform.so.0.16
Means the Mir release is 0.17.0 but the ABI level (soname) is still 
0.16. Actually that's not too confusing. It might be preferable even.

---

From: Christopher James Halse Rogers <[email-masked]>
Date: Wed, 02 Sep 2015 16:54:56 +1000

> Hypothetically the "9" could now go away. Internally that's fine:

Right. I even suggested this upthread.

> 
> But externally if we started naming the files as such then it might 
> get confusing:
>    libmirplatform.so.0.17.0

I'd prefer the integer SOVER we have now to this. We could certainly do 
a
libmirplatform.so.9 → libmirplatform.so.9.0.17.0 thing if we wanted 
to, though.

> --
> Mir-devel mailing list
> [email-masked]
> Modify settings or unsubscribe at: 
> https://lists.ubuntu.com/mailman/listinfo/mir-devel

---

From: Alan Griffiths <[email-masked]>
Date: Wed, 09 Sep 2015 16:28:24 +0100

After today's standup Stephen said that Chris will update the
doc/dso_versioning_guide.md to incorporate the ideas from this thread.

---

From: Christopher James Halse Rogers <[email-masked]>
Date: Mon, 05 Oct 2015 11:01:59 +1100

> doc/dso_versioning_guide.md to incorporate the ideas from this thread.

There's a proposal up at 
https://code.launchpad.net/~raof/mir/new-dso-versioning-policy/+merge/273186 
now.