forked from OSchip/llvm-project
2e35cb7508
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 llvm-svn: 183244 |
||
|---|---|---|
| .. | ||
| project.xcworkspace | ||
| xcshareddata/xcschemes | ||
| project.pbxproj | ||