tree abee41ec82d36442c6fe502e213ad5fdd300734c
parent 764cbd97f96a9b44054b5398d1105026e91839fc
author Enrico Granata <egranata@apple.com> 1370372229 +0000
committer Enrico Granata <egranata@apple.com> 1370372229 +0000

<rdar://problem/13988982>

LLDB API versioning
This checkin makes the LLDB API versioned
We are starting at version 1.0 and will then revise and update the API from there
Further details:
 API versioning
---------------------------------

The LLDB API is versioned independently of the LLDB source base
Our API version numbers are composed of a major and a minor number

The major number means a complete and stable revision of the API. Major numbers are compatibility breakers
(i.e. when we change the API major number, there is no promise of compatibility with the previous major version
 and we are free to remove and/or change any APIs)
Minor numbers are a work-in-progress evolution of the API. APIs will not be removed or changed across minor versions
(minors do not break compatibility). However, we can deprecate APIs in minor versions or add new APIs in minor versions
A deprecated API is supposedly going to be removed in the next major version and will generate a warning if used
APIs we add in minor versions will not be removed (at least until the following major) but they might theoretically be deprecated
in a following minor version
Users are discouraged from using the LLDB version number to test for API features and should instead use the API version checking
as discussed below

 API version checking
---------------------------------

You can (optionally) sign into an API version checking feature
To do so you need to define three macros:
LLDB_API_CHECK_VERSIONING - define to any value (or no value)
LLDB_API_MAJOR_VERSION_WANTED - which major version of the LLDB API you are targeting
LLDB_API_MINOR_VERSION_WANTED - which minor version of the LLDB API you are targeting

If these macros exist - LLDB will enable version checking of the public API

If LLDB_API_MAJOR_VERSION is not equal to LLDB_API_MAJOR_VERSION_WANTED we will immediately halt your compilation with an error
This is by design, since we do not make any promise of compatibility across major versions - if you really want to test your luck, disable the versioning altogether

If the major version test passes, you have signed up for a specific minor version of the API
Whenever we add or deprecate an API in a minor version, we will mark it with either
LLDB_API_NEW_IN_DOT_x - this API is new in LLDB .x
LLDB_API_DEPRECATED_IN_DOT_x - this API is deprecated as of .x

If you are using an API new in DOT_x
 if LLDB_API_MINOR_VERSION_WANTED >= x then all is well, else you will get a compilation error
  This is meant to prevent you from using APIs that are newer than whatever LLDB you want to target

If you are using an API deprecated in DOT_x
 if LLDB_API_MINOR_VERSION_WANTED >= x then you will get a compilation warning, else all is well
 This is meant to let you know that you are using an API that is deprecated and might go away

 Caveats
---------------------------------

Version checking only works on clang on OSX - you will get an error if you try to enable it on any other OS/compiler
If you want to enable version checking on other platforms, you will need to define appropriate implementations for
LLDB_API_IMPL_DEPRECATED and LLDB_API_IMPL_TOONEW and any other infrastructure your compiler needs for this purpose

We have no deprecation-as-error mode

There is no support for API versioning in Python

We reserve to use macros whose names begin with LLDB_API_ and you should not use them in your source code as they might conflict
with present or future macro names we are using to implement versioning


For API implementors:
If you need to add a new public API call, please remember to add the LLDB_API_NEW_IN_DOT_x marker in the header file
and when you are done with adding stuff, to also update LLDB_API_MINOR_VERSION
If you want to remove a function, deprecate it first, by using LLDB_API_DEPRECATED_IN_DOT_x
and when you are done with deprecating stuff, to also update LLDB_API_MINOR_VERSION
A new major version (LLDB_API_MAJOR_VERSION++) is your only chance to remove and/or change API calls
but is probably quite a big deal and you might want to consider deprecating the existing calls for a while
before doing your changes

A couple more caveats:
Currently, the lldb-tool does NOT use the version checking feature. It would be a nice future improvement to make it do that, once we have proper version checking on other OSs
APIs marked as deprecated by a comment in the source are still deprecated just that way. A good purpose for API 1.1 might be to deprecate them with appropriate markers


git-svn-id: https://llvm.org/svn/llvm-project/lldb/trunk@183244 91177308-0d34-0410-b5e6-96231b3b80d8