Making changes to the SB API

Subprojects LLDB
1

What is the governing philosophy around making changes to the SB API? The “SB API Coding Rules”
page establishes the practices on how to avoid introducing accidental incompatibility, but what
about the cases where there’s a case for intentionally making changes?

For example, I’d like to make a small change to SBTarget to allow surfacing errors during LoadCore():

SBProcess SBTarget::LoadCore(const char *core_file)

And add an explicit out error parameter (in line with SBTarget::Attach(), Launch(), …):

SBProcess SBTarget::LoadCore(const char core_file*, SBError** **&**error)

If the rule is to strictly avoid any kind of changes then I’d have to resort to
a COM-like versioning and introduce a new SBTarget::LoadCore2 (or LoadCoreEx, … pick
your poison, I’m not set on any name) while also keeping the existing LoadCore().

Any guidance on this? Thanks!

2

For better or worse you need to make a separate function. An alternative idea that has been floated is to start making a version 2 SB API and then eventually deprecate the current API, but probably due to the amount of work involved and the cost/benefit ratio, nobody’s ever really taken point on it.

3

What is the governing philosophy around making changes to the SB API? The “SB API Coding Rules”
page establishes the practices on how to avoid introducing accidental incompatibility, but what
about the cases where there’s a case for intentionally making changes?

For example, I’d like to make a small change to SBTarget to allow surfacing errors during LoadCore():

SBProcess SBTarget::LoadCore(const char *core_file)

And add an explicit out error parameter (in line with SBTarget::Attach(), Launch(), …):

SBProcess SBTarget::LoadCore(const char core_file*, SBError** **&**error)

If the rule is to strictly avoid any kind of changes then I’d have to resort to
a COM-like versioning and introduce a new SBTarget::LoadCore2 (or LoadCoreEx, … pick
your poison, I’m not set on any name) while also keeping the existing LoadCore().

Any guidance on this? Thanks!

Just add an extra overloaded version of LoadCore. We don’t want people’s code to not link and since Apple uses a LLDBRPC.framework that sub-launches a lldb-rpc-server which can connect to older LLDB.framework binaries, we can’t remove functions.

Greg

4

Thanks. I wasn’t sure how well C++ overloading works with SWIG, that’s definitely a more ergonomic solution.

5

Overloading with different numbers of arguments works with no problems, and we use that in a bunch of places in the SB API. I seem to remember that SWIG doesn't always get more subtle overloading (float vrs. double) right, but I can't bring a specific example to mind. Anyway, Greg's solution should work just fine.

Jim