From 5a1b453b367310437f6937a2913a965fe53a9f43 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sun, 17 Dec 2017 08:16:32 +0100 Subject: [PATCH] Introduce KALEIDOSCOPE_API_VERSION As we guarantee backwards compatibility throughout a major version, it helps if we have that version available, so plugins / sketches can check if they are compatible, and issue a helpful error if they are not. As further convenience, defining `KALEIDOSCOPE_REQUIRED_API_VERSION` before including `Kaleidoscope.h` will result in a check being done by Kaleidoscope, and an error printed if it does not match the API shipped. Signed-off-by: Gergely Nagy --- src/Kaleidoscope.h | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/Kaleidoscope.h b/src/Kaleidoscope.h index 96e237ad..27038d00 100644 --- a/src/Kaleidoscope.h +++ b/src/Kaleidoscope.h @@ -33,6 +33,32 @@ extern HARDWARE_IMPLEMENTATION KeyboardHardware; #define VERSION "locally-built" #endif +/** Kaleidoscope API (major) version. + * + * The API is guaranteed to be backwards compatible for the entire duration of a + * major version. However, breaking changes may come, and result in a major + * version bump. To help migration, the `KALEIDOSCOPE_API_VERSION` macro can be + * used to check the major version provided by the Kaleidoscope we are compiling + * against. This can be used to error out with a helpful message, or change how + * the API is used - it is entirely up to the plugin or sketch author. The point + * of this macro is to let them easily check the version. + */ +#define KALEIDOSCOPE_API_VERSION 1 + +/** Required Kaleidoscope major version. + * + * For the sake of convenience, defining `KALEIDOSCOPE_REQUIRED_API_VERSION` + * before including `Kaleidoscope.h` itself will result in comparing its value + * to `KALEIDOSCOPE_API_VERSION`. If they differ, a helpful error message is + * printed. + * + * Done so that a new API version would result in a helpful error message, + * instead of cryptic compile errors. + */ +#if defined(KALEIDOSCOPE_REQUIRED_API_VERSION) && (KALEIDOSCOPE_REQUIRED_API_VERSION != KALEIDOSCOPE_API_VERSION) +#error Kaleidoscope API version mismatch! The plugin or sketch requires a different API version than what is available. +#endif + const uint8_t KEYMAP_SIZE __attribute__((deprecated("Kaleidoscope.setup() does not require KEYMAP_SIZE anymore."))) = 0;