CMakeLists: add support for external overlays

Allow users who pull ArduinoCore as a module (via west) to provide
their own Zephyr overlay files in the application repository instead
of modifying ArduinoCore/variants.
This enables board-specific overlays (for example when using an
AtomS3 board) to live in the consuming project. If an overlay is not
provided the build will fail due to the missing zephyr,user section,
which is the expected behavior.

Signed-off-by: Michal Gagos <lizard123137@gmail.com>

Author: lizard123137

CMakeLists.txt

@@ -8,7 +8,11 @@ if (CONFIG_ARDUINO_API)
   elseif (IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/variants/${NORMALIZED_BOARD_TARGET})
     set(variant_dir variants/${NORMALIZED_BOARD_TARGET})
   else()
-    message(FATAL_ERROR "Variant dir not found: variants/${BOARD}, variants/${NORMALIZED_BOARD_TARGET}")
+    message(WARNING
+      "Variant dir not found: variants/${BOARD}, variants/${NORMALIZED_BOARD_TARGET}\n"
+      "Your board is currently not supported. To use it you must create a DTS overlay."
+    )
+    set(variant_dir variants/default)
   endif()
 
   add_subdirectory(cores)

documentation/variants.md

@@ -45,6 +45,7 @@ variants/
 		- The `Cmakelists` help the compiler locate the proper directory to help find the proper header files that are board specific. You need to add the name using `zephyr_include_directories(BOARD_NAME)` to this file. Do note that this `BOARD_NAME` is the same as the name of your board's directory.
 		- `variant.h` contains the necessary `#includes` inorder to tell the source code about your board's pinmap.
 - The `<BOARD_NAME>` folder is where the overlay and pinmap file resides. Inorder to understand how to write DT overlays, lookup `Documentation/overlays.md`. To understand the `<boardname_pinmap.h>` file, go through the existing `variants/ARDUINO_NANO33BLE/arduino_nano_ble_sense_pinmap.h` which shows how to use the overlay nodes inside our C programs using zephyr macros like `GPIO_DT_SPEC_GET`. The zephyr-project documentation on this is pretty extensive as well and worth reading.
+- It is also possible to apply the overlay outside of the `variants` folder. In that case `cmake` will show a warning and a default empty `variant.h` file will be used. The `zephyr,user` section will still need to be defined somewhere in your project, as described in the [Guide to Writing Overlays section](#guide-to-writing-overlays).
 
 ## Guide to Writing Overlays
 

variants/default/variant.h

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Michal Gagos
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once