Move most sources to a kaleidoscope/ subdir and namespace

UPGRADING.md

@@ -71,6 +71,17 @@ The API version will remain the same, even if we introduce breaking changes -
 until a stable release is made from the v2 branch. From that point onwards, the
 API version will change with further breaking changes.
 
+### New source code layout
+
+The sources were rearranged so that most of them live under `src/kaleidoscope`,
+with only the main header, `Kaleidoscope.h` out in `src/`. Some select headers
+that were used by plugins in the wild also remained in `src/`, but now emit a
+warning. If you were including anything other than `Kaleidoscope.h` which was
+not namespaced, please update the include, and either add the namespace prefix,
+or consider removing the include altogether. Most - if not all - parts of
+Kaleidoscope are included via `Kaleidoscope.h` by design, so there should not be
+a need for any extra includes.
+
 Deprecated APIs and their replacements
 --------------------------------------
 
@@ -83,6 +94,17 @@ If any of this does not make sense to you, or you have trouble updating your
 .ino sketch, do not hesitate to write us at help@keyboard.io, we can help you
 fix it.
 
+### To be removed by 2019-01-14
+
+Any headers provided by the firmware other than `Kaleidoscope.h` (currently
+`layers.h`, `key_defs_keymaps.h` and `macro_helpers.h`) are obsolete, and will
+be removed.
+
+One should not need to use `key_defs_keymaps.h` and `layers.h`, as
+`Kaleidoscope.h` includes them anyway, and the same goes for `macro_helpers.h`.
+If one absolutely must, use `kaleidoscope/key_defs_keymaps.h` and
+`kaleidoscope/macro_helpers.h` instead.
+
 Deprecated and removed APIs
 ---------------------------
 

src/Kaleidoscope.h

@@ -16,138 +16,4 @@
 
 #pragma once
 
-#include <Arduino.h>
-
-//end of add your includes here
-#ifdef __cplusplus
-extern "C" {
-#endif
-void loop();
-void setup();
-#ifdef __cplusplus
-} // extern "C"
-#endif
-
-//add your function definitions for the project KeyboardIO here
-
-#define TS(X) //Serial.print(micros() );Serial.print("\t");Serial.println(X);
-
-#include <stdio.h>
-#include <math.h>
-#include <stdint.h>
-
-#include KALEIDOSCOPE_HARDWARE_H
-#include "key_events.h"
-#include "kaleidoscope/hid.h"
-#include "layers.h"
-#include "macro_map.h"
-#include "kaleidoscope_internal/event_dispatch.h"
-#include "macro_helpers.h"
-#include "plugin.h"
-
-#define HOOK_MAX 64
-
-extern HARDWARE_IMPLEMENTATION KeyboardHardware;
-
-#ifndef VERSION
-#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 2
-
-/** 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)
-#define xstr(a) str(a)
-#define str(a) #a
-static_assert(KALEIDOSCOPE_REQUIRED_API_VERSION == KALEIDOSCOPE_API_VERSION,
-              "Kaleidoscope API version mismatch! We have version " xstr(KALEIDOSCOPE_API_VERSION)
-              " available, but version " xstr(KALEIDOSCOPE_REQUIRED_API_VERSION) " is required.");
-#endif
-
-namespace kaleidoscope {
-
-class Kaleidoscope_ {
- public:
-  Kaleidoscope_(void);
-
-  void setup(void);
-  void loop(void);
-
-  /** Detaching from / attaching to the host.
-   *
-   * These two functions wrap the hardware plugin's similarly named functions.
-   * We wrap them, because we'd like plugins and user-code not having to use
-   * `KeyboardHardware` directly.
-   *
-   * The methods themselves implement detaching from / attaching to the host,
-   * without rebooting the device, and remaining powered in between.
-   *
-   * Intended to be used in cases where we want to change some settings between
-   * detach and attach.
-   */
-  void detachFromHost() {
-    KeyboardHardware.detachFromHost();
-  }
-  void attachToHost() {
-    KeyboardHardware.attachToHost();
-  }
-
-  /** Returns the timer as it was at the start of the cycle.
-   * The goal of this method is two-fold:
-   *  - To reduce the amount of calls to millis(), providing something cheaper.
-   *  - To have a consistent timer value for the whole duration of a cycle.
-   *
-   * This cached value is updated at the start of each cycle as the name
-   * implies. It is recommended to use this in plugins over millis() unless
-   * there is good reason not to.
-   */
-  static uint32_t millisAtCycleStart() {
-    return millis_at_cycle_start_;
-  }
-
-  EventHandlerResult onFocusEvent(const char *command) {
-    return kaleidoscope::Hooks::onFocusEvent(command);
-  }
-
- private:
-  static uint32_t millis_at_cycle_start_;
-};
-
-extern kaleidoscope::Kaleidoscope_ Kaleidoscope;
-
-} // namespace kaleidoscope
-
-// For compatibility reasons we enable class Kaleidoscope_ also to be available
-// in global namespace.
-//
-typedef kaleidoscope::Kaleidoscope_  Kaleidoscope_;
-
-// For compatibility reasons we enable the global variable Kaleidoscope
-// in global namespace.
-//
-using kaleidoscope::Kaleidoscope;
-
-// Use this function macro to register plugins with Kaleidoscope's
-// hooking system. The macro accepts a list of plugin instances that
-// must have been instantiated at global scope.
-//
-#define KALEIDOSCOPE_INIT_PLUGINS(...) _KALEIDOSCOPE_INIT_PLUGINS(__VA_ARGS__)
+#include "kaleidoscope/Kaleidoscope.h"

src/Kaleidoscope.cpp → src/kaleidoscope/Kaleidoscope.cpp

@@ -14,7 +14,7 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "Kaleidoscope.h"
+#include "kaleidoscope/Kaleidoscope.h"
 #include <stdarg.h>
 
 namespace kaleidoscope {

src/kaleidoscope/Kaleidoscope.h

@@ -0,0 +1,153 @@
+/* Kaleidoscope - Firmware for computer input devices
+ * Copyright (C) 2013-2018  Keyboard.io, Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <Arduino.h>
+
+//end of add your includes here
+#ifdef __cplusplus
+extern "C" {
+#endif
+void loop();
+void setup();
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+//add your function definitions for the project KeyboardIO here
+
+#define TS(X) //Serial.print(micros() );Serial.print("\t");Serial.println(X);
+
+#include <stdio.h>
+#include <math.h>
+#include <stdint.h>
+
+#include KALEIDOSCOPE_HARDWARE_H
+#include "kaleidoscope/key_events.h"
+#include "kaleidoscope/hid.h"
+#include "kaleidoscope/layers.h"
+#include "kaleidoscope/macro_map.h"
+#include "kaleidoscope_internal/event_dispatch.h"
+#include "kaleidoscope/macro_helpers.h"
+#include "kaleidoscope/plugin.h"
+
+#define HOOK_MAX 64
+
+extern HARDWARE_IMPLEMENTATION KeyboardHardware;
+
+#ifndef VERSION
+#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 2
+
+/** 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)
+#define xstr(a) str(a)
+#define str(a) #a
+static_assert(KALEIDOSCOPE_REQUIRED_API_VERSION == KALEIDOSCOPE_API_VERSION,
+              "Kaleidoscope API version mismatch! We have version " xstr(KALEIDOSCOPE_API_VERSION)
+              " available, but version " xstr(KALEIDOSCOPE_REQUIRED_API_VERSION) " is required.");
+#endif
+
+namespace kaleidoscope {
+
+class Kaleidoscope_ {
+ public:
+  Kaleidoscope_(void);
+
+  void setup(void);
+  void loop(void);
+
+  /** Detaching from / attaching to the host.
+   *
+   * These two functions wrap the hardware plugin's similarly named functions.
+   * We wrap them, because we'd like plugins and user-code not having to use
+   * `KeyboardHardware` directly.
+   *
+   * The methods themselves implement detaching from / attaching to the host,
+   * without rebooting the device, and remaining powered in between.
+   *
+   * Intended to be used in cases where we want to change some settings between
+   * detach and attach.
+   */
+  void detachFromHost() {
+    KeyboardHardware.detachFromHost();
+  }
+  void attachToHost() {
+    KeyboardHardware.attachToHost();
+  }
+
+  /** Returns the timer as it was at the start of the cycle.
+   * The goal of this method is two-fold:
+   *  - To reduce the amount of calls to millis(), providing something cheaper.
+   *  - To have a consistent timer value for the whole duration of a cycle.
+   *
+   * This cached value is updated at the start of each cycle as the name
+   * implies. It is recommended to use this in plugins over millis() unless
+   * there is good reason not to.
+   */
+  static uint32_t millisAtCycleStart() {
+    return millis_at_cycle_start_;
+  }
+
+  EventHandlerResult onFocusEvent(const char *command) {
+    return kaleidoscope::Hooks::onFocusEvent(command);
+  }
+
+ private:
+  static uint32_t millis_at_cycle_start_;
+};
+
+extern kaleidoscope::Kaleidoscope_ Kaleidoscope;
+
+} // namespace kaleidoscope
+
+// For compatibility reasons we enable class Kaleidoscope_ also to be available
+// in global namespace.
+//
+typedef kaleidoscope::Kaleidoscope_  Kaleidoscope_;
+
+// For compatibility reasons we enable the global variable Kaleidoscope
+// in global namespace.
+//
+using kaleidoscope::Kaleidoscope;
+
+// Use this function macro to register plugins with Kaleidoscope's
+// hooking system. The macro accepts a list of plugin instances that
+// must have been instantiated at global scope.
+//
+#define KALEIDOSCOPE_INIT_PLUGINS(...) _KALEIDOSCOPE_INIT_PLUGINS(__VA_ARGS__)

src/kaleidoscope/hid.h

@@ -16,7 +16,7 @@
 
 #pragma once
 #include <Arduino.h>
-#include "key_defs.h"
+#include "kaleidoscope/key_defs.h"
 
 namespace kaleidoscope {
 namespace hid {

src/kaleidoscope/hooks.h

@@ -22,8 +22,8 @@ namespace kaleidoscope {
 union Key;
 }
 
-#include "plugin.h"
-#include "event_handlers.h"
+#include "kaleidoscope/plugin.h"
+#include "kaleidoscope/event_handlers.h"
 
 // Forward declaration required to enable friend declarations
 // in class Hooks.

src/key_defs.h → src/kaleidoscope/key_defs.h

@@ -17,14 +17,14 @@
 #pragma once
 
 
-#include "HIDTables.h"
+#include "kaleidoscope/HIDTables.h"
 
-#include "key_defs_keyboard.h"
-#include "key_defs_sysctl.h"
-#include "key_defs_consumerctl.h"
-#include "key_defs_keymaps.h"
+#include "kaleidoscope/key_defs_keyboard.h"
+#include "kaleidoscope/key_defs_sysctl.h"
+#include "kaleidoscope/key_defs_consumerctl.h"
+#include "kaleidoscope/key_defs_keymaps.h"
 
-#include "key_defs_aliases.h"
+#include "kaleidoscope/key_defs_aliases.h"
 
 #ifdef ARDUINO_VIRTUAL
 #include "VirtualHID/VirtualHID.h"