feat: Initial Kconfig integration

Adds a Kconfig infrastructure for managing build-time configuration options,
moving away from scattered #defines and build variables.

Includes:
- Top-level Kconfig and Makefile for invoking configuration tools.
- Kconfig files for core (py/), extmod/, drivers/, shared/, and all ports/.
- Initial population of Kconfig options based on existing defines and build vars.
- Conditional defaults in common Kconfig files based on PORT_ symbols.
- Integration hooks into Makefiles and CMake files (`autoconf.mk`, `config.cmake`).
- Initial build system integration for Kconfig variables in unix, stm32, rp2 ports.
- Basic documentation in docs/develop/kconfig.rst.

Further work needed for full dependency analysis, help text refinement,
complete build system integration, and testing.

🤖 Generated with Anon Kode & gemini-2.5-pro-exp-03-25
Co-Authored-By: Anon Kode <noreply@Anon Kode.com>

Author: pi-anl

KCONFIG_PLAN.md

@@ -0,0 +1,114 @@
+# Kconfig Integration Plan for MicroPython
+
+**Important Note:** This Kconfig system is intended as an *optional overlay* to the existing `mpconfig*.h` and build variable system. It allows users to easily customize builds locally using `make menuconfig`. The primary configuration mechanism for MicroPython remains the existing system. The goal is not (currently) to fully replace the existing system, but to provide a user-friendly alternative for common overrides.
+
+This document outlines the plan to integrate the Kconfig system into the MicroPython build process for managing compile-time configuration.
+
+## Goals
+
+1.  **User-Friendly Customization:** Provide a standard, interactive interface (menuconfig, xconfig) for users to *optionally* override default MicroPython features and port-specific settings for their local builds.
+2.  **Discoverability:** Make common configuration options easily discoverable with integrated help text.
+3.  **Structure:** Organize Kconfig options in a hierarchy mirroring the project structure.
+4.  **Integration:** Ensure Kconfig selections (`CONFIG_...`) correctly override the base configuration derived from `mpconfigport.h`, `mpconfigboard.h`, and Make/CMake variables where Kconfig options exist.
+
+## Prerequisites
+
+*   Installation of Kconfig frontends (e.g., `kconfig-frontends` package providing `menuconfig`, `kconfig-conf`, etc., or Zephyr's `kconfiglib`). This plan assumes standard Kconfig tools are available in the PATH.
+
+## Kconfig File Structure
+
+*   A top-level `Kconfig` file will be created in the repository root.
+*   This root `Kconfig` will source other `Kconfig` files located in relevant directories:
+    *   `py/Kconfig`
+    *   `extmod/Kconfig`
+    *   `drivers/Kconfig`
+    *   `shared/Kconfig`
+    *   `ports/<port>/Kconfig` (e.g., `ports/unix/Kconfig`, `ports/stm32/Kconfig`)
+    *   `ports/<port>/boards/Kconfig` (Potentially, if board-level Kconfig is desired)
+
+## Implementation Phases
+
+**Phase 1: Initial Setup and Core `py/` Defines**
+
+1.  **Create Top-Level Files:**
+    *   Create `Kconfig` (root): Defines the main menu structure and sources other Kconfig files.
+    *   Create `Makefile` (root): Contains targets for Kconfig (`menuconfig`, `xconfig`) and a default target to delegate builds to ports.
+2.  **Create Core Kconfig:**
+    *   Create `py/Kconfig`.
+3.  **Identify & Define Core `py/` Options:**
+    *   Use `grep` to find common `#define`s starting with `MICROPY_` or `MPY_` within the `py/` directory (e.g., `MICROPY_ENABLE_GC`, `MICROPY_FLOAT_IMPL`, `MICROPY_PY_BUILTINS_SET`).
+    *   Add corresponding `config` entries to `py/Kconfig` with appropriate types (`bool`, `int`, `hex`, `string`), default values (extracted from defines), and initial help text.
+    *   Define choices where mutually exclusive options exist (e.g., float implementation).
+4.  **Configure Kconfig Output (Header):**
+    *   Set up Kconfig build environment variables (e.g., `KCONFIG_CONFIG=.config`, `srctree=.`, `objtree=build`) likely via the top-level Makefile.
+    *   Configure Kconfig (e.g., using `kconfig-conf --syncconfig Kconfig`) to generate a C header file (e.g., `build/mpconfig_kconfig.h`) containing `#define`s for chosen options (prefixed with `CONFIG_`).
+5.  **Integrate Generated Header:**
+    *   Modify `py/mpconfig.h` (or a similar central header like `py/mpconfigbase.h`) to include `build/mpconfig_kconfig.h` *if it exists*.
+    *   Guard existing default `#define`s in MicroPython source files (`#ifndef CONFIG_...`) so that Kconfig values take precedence when the header is present.
+6.  **Testing:**
+    *   Run `make menuconfig` from the root.
+    *   Save a configuration (`.config`).
+    *   Run `make -C mpy-cross` or `make PORT=unix -C ports/unix` (or the equivalent using the new top-level make target).
+    *   Verify `build/mpconfig_kconfig.h` is generated correctly.
+    *   Verify the build incorporates the settings from the generated header.
+
+**Phase 2: Makefile Integration**
+
+1.  **Identify Makefile Variables:**
+    *   Use `grep` to find common variables starting with `MICROPY_` or `MPY_` in Makefiles (`Makefile`, `*.mk`) across the project, especially in `py/mkrules.mk` and port Makefiles. Examples: `FROZEN_MANIFEST`, `MICROPY_PY_FFI`.
+2.  **Add Kconfig Options:**
+    *   Add corresponding `config` entries to the relevant `Kconfig` files (e.g., `ports/unix/Kconfig` for port-specific Make variables).
+3.  **Configure Kconfig Output (Makefile Include):**
+    *   Configure Kconfig to generate a Makefile include fragment (e.g., `build/autoconf.mk`) containing Make variable assignments based on chosen options (`CONFIG_...=y` or `CONFIG_...=value`).
+4.  **Integrate Generated Makefile:**
+    *   Modify relevant Makefiles (e.g., `py/mkrules.mk`, port Makefiles) to include `build/autoconf.mk`. The inclusion point needs careful consideration - include it early to allow overrides later, or late to enforce Kconfig values. Start by including it early.
+5.  **Refactor Makefiles:**
+    *   Update Makefiles to use the Kconfig variables (e.g., `ifeq ($(CONFIG_MICROPY_PY_FFI),y)`).
+    *   Remove original variable definitions if they are now fully controlled by Kconfig.
+6.  **Testing:**
+    *   Run `make menuconfig`, change relevant options, save.
+    *   Run `make` for a Make-based port (e.g., `unix`, `stm32`).
+    *   Verify the build reflects the Kconfig settings passed via `autoconf.mk`.
+
+**Phase 3: CMake Integration**
+
+1.  **Identify CMake Variables:**
+    *   Use `grep` to find common variables set with `set(MICROPY_...` or `set(MPY_...` in CMake files (`CMakeLists.txt`, `*.cmake`), particularly in CMake-based ports like `esp32` and `rp2`.
+2.  **Add Kconfig Options:**
+    *   Add corresponding `config` entries to relevant `Kconfig` files (e.g., `ports/esp32/Kconfig`).
+3.  **Configure Kconfig Output (CMake Include):**
+    *   Configure Kconfig to generate a CMake script (e.g., `build/config.cmake`) containing CMake variable assignments (`set(CONFIG_... ON)` or `set(CONFIG_... "value")`).
+4.  **Integrate Generated CMake:**
+    *   Modify relevant `CMakeLists.txt` files to include `build/config.cmake` early in the configuration process.
+5.  **Refactor CMake:**
+    *   Update CMake files to use the Kconfig variables (e.g., `if(CONFIG_MICROPY_BLUETOOTH_NIMBLE)`).
+    *   Remove original variable definitions if controlled by Kconfig.
+6.  **Testing:**
+    *   Run `make menuconfig`, change relevant options, save.
+    *   Build a CMake-based port (e.g., `esp32`, `rp2`).
+    *   Verify the build reflects the Kconfig settings passed via `config.cmake`.
+
+**Phase 4: Expansion and Refinement**
+
+1.  **Systematic Scan:** Thoroughly scan *all* project directories (`extmod`, `drivers`, `ports`, etc.) for C `#define`s, Makefile variables, and CMake variables starting with `MICROPY_` or `MPY_`.
+2.  **Create Kconfig Entries:** Add Kconfig entries for all identified configuration points into the structured `Kconfig` files.
+3.  **Dependencies:** Analyze code logic (`#if`, conditional assignments) to define dependencies (`depends on`) and selections (`select`) between Kconfig options.
+4.  **Help Text:** Review and improve the help text for all Kconfig options, explaining their purpose and impact.
+5.  **Add Targets:** Implement the `xconfig` target in the top-level Makefile. Implement the default target to delegate `make PORT=<port> [BOARD=<board>] ...` calls correctly.
+6.  **Testing:** Test across a wider range of ports and configurations.
+
+**Phase 5: Documentation and Cleanup**
+
+1.  **Documentation:** Add documentation explaining the new Kconfig system, prerequisites, and usage.
+2.  **Cleanup:** Remove configuration settings from original source files, Makefiles, and CMake files if they have been fully superseded by the Kconfig system.
+3.  **Final Review:** Ensure consistency, test edge cases, and verify build success across major ports.
+
+## Output Files (in `build/` directory)
+
+*   `.config`: The saved Kconfig selections.
+*   `mpconfig_kconfig.h`: Generated C header with `#define CONFIG_...`.
+*   `autoconf.mk`: Generated Makefile include with `CONFIG_...=y/value`.
+*   `config.cmake`: Generated CMake include with `set(CONFIG_... ON/"value")`.
+*   Other Kconfig intermediate files (e.g., `syncconfig.log`).
+
+This phased approach allows for incremental implementation and testing, reducing the risk associated with a large-scale change to the build system.

KCONFIG_STATUS.md

@@ -0,0 +1,69 @@
+# Kconfig Integration Status Summary
+
+This document summarizes the current state of the Kconfig integration effort.
+
+## Completed Steps (Phases 1-3 & Initial Scan)
+
+*   **Initial Setup:**
+    *   Created top-level `Kconfig` and `Makefile`.
+    *   Created skeleton `Kconfig` files for core directories (`py`, `extmod`, `drivers`, `shared`) and all ports.
+*   **Core `py/` Defines:**
+    *   Identified and added initial Kconfig options for core features, types, modules, optimizations, and memory settings based on `py/mpconfig.h` and `py/mpconfigbase.h`.
+    *   Configured Kconfig output generation (`mpconfig_kconfig.h`, `autoconf.mk`, `config.cmake`) via the top-level Makefile.
+    *   Integrated the generated header include into `py/mpconfig.h`.
+*   **Makefile Integration:**
+    *   Integrated `build/autoconf.mk` include into `py/mkrules.mk`.
+*   **CMake Integration:**
+    *   Integrated `build/config.cmake` include into `py/py.cmake`.
+*   **Systematic Scan:**
+    *   Scanned `py/`, `extmod/`, `drivers/`, `shared/`, `ports/`, and `mpy-cross/` for C `#define`s and Make/CMake variables starting with `MICROPY_` or `MPY_`.
+    *   Added corresponding Kconfig entries for found configuration points into the relevant `Kconfig` files (e.g., `ports/unix/Kconfig`, `ports/stm32/Kconfig`, etc.).
+*   **Documentation:**
+    *   Created initial documentation page `docs/develop/kconfig.rst`.
+    *   Added the page to the development documentation index.
+
+## Kconfig Maintenance Check (`tools/check_kconfig_settings.sh`)
+
+To help ensure new configuration options are added to Kconfig going forward, a check script has been added:
+
+*   **Purpose:** Scans committed changes for new `#define MICROPY_...`, `#define MPY_...`, `MICROPY_... =`, `MPY_... =`, `set(MICROPY_...)`, or `set(MPY_...)` definitions/variables in relevant source files (`.c`, `.h`, `.mk`, `.cmake`, `CMakeLists.txt`), excluding common library/build directories.
+*   **Verification:** For each new setting found, it searches all `Kconfig` files to ensure a corresponding `config SETTING_NAME` entry exists.
+*   **Integration:** Designed to be run in pre-commit hooks and CI workflows.
+*   **Failure:** If settings are found without a matching Kconfig entry, the script prints an error and exits with a non-zero status.
+
+**Example Error Output:**
+
+```
+--------------------------------------------------
+Error: Found new MICROPY_/MPY_ settings without corresponding Kconfig entries:
+  - MICROPY_NEW_FEATURE_X
+  - MICROPY_HW_COOL_SENSOR
+
+Please add a 'config MICROPY_HW_COOL_SENSOR' entry to the appropriate Kconfig file.
+--------------------------------------------------
+```
+
+This provides a mechanism to catch accidental omissions and maintain consistency between the code/build system and the Kconfig definitions.
+
+## Next Steps (Phase 4 & 5 - Refinement, Testing, Cleanup)
+
+Significant manual effort is required for the following:
+
+1.  **Dependencies:** Analyze code logic (`#if`, conditional assignments in Make/CMake) across the entire codebase to define dependencies (`depends on`) and selections (`select`) between Kconfig options. This is crucial for ensuring valid configurations.
+2.  **Help Text:** Review and significantly improve the help text for *all* Kconfig options, explaining their purpose, impact on resources (flash/RAM), and any potential side effects or requirements.
+3.  **Refactoring:**
+    *   Systematically replace hardcoded `#define` values in C source files with checks for the corresponding `CONFIG_...` Kconfig definition (e.g., `#if CONFIG_MICROPY_ENABLE_GC`).
+    *   Refactor Makefiles (`*.mk`) to use variables derived from Kconfig (e.g., `ifeq ($(CONFIG_MICROPY_PY_FFI),y)`) instead of their original definitions.
+    *   Refactor CMake files (`*.cmake`, `CMakeLists.txt`) to use Kconfig variables (e.g., `if(CONFIG_MICROPY_BLUETOOTH_NIMBLE)`).
+    *   Remove original definitions from source/Make/CMake files once they are fully controlled by Kconfig.
+4.  **Testing:**
+    *   Perform thorough build testing across a wide range of ports (Make-based and CMake-based) and boards.
+    *   Test various combinations of Kconfig options (enabling/disabling features) to ensure the build system and code behave correctly.
+    *   Verify that generated firmware reflects the chosen Kconfig settings.
+5.  **Documentation:**
+    *   Expand and refine the `docs/develop/kconfig.rst` documentation with more detailed usage instructions, information about common options, and guidance for port maintainers.
+6.  **Cleanup:**
+    *   Consolidate duplicated options (e.g., `MICROPY_PY_NETWORK_WIZNET5K` defined in both `extmod/Kconfig` and `ports/stm32/Kconfig`). Decide on the canonical location for each option.
+    *   Ensure consistency in naming and style across all Kconfig files.
+
+This integration provides the basic framework, but the refinement phase is essential for making it robust and user-friendly.

Kconfig

@@ -0,0 +1,110 @@
+mainmenu "MicroPython Configuration"
+
+# Default to a common configuration file name
+config KCONFIG_CONFIG
+	string
+	option env="KCONFIG_CONFIG"
+	default ".config"
+
+# Build directory
+config KCONFIG_BUILD_DIR
+	string
+	option env="KCONFIG_BUILD_DIR"
+	default "build"
+
+# Define ARCH for Kconfig scripts (optional, but good practice)
+config ARCH
+	string
+	option env="ARCH"
+	default "arm"
+
+# Include Kconfig files from subdirectories
+source "py/Kconfig"
+source "extmod/Kconfig"
+source "drivers/Kconfig"
+source "shared/Kconfig"
+
+# Conditionally include port-specific Kconfig files based on PORT variable
+choice
+    prompt "Target Port"
+    optional
+
+config PORT_UNIX
+    bool "Unix Port"
+config PORT_STM32
+    bool "STM32 Port"
+config PORT_ESP32
+    bool "ESP32 Port"
+config PORT_ESP8266
+    bool "ESP8266 Port"
+config PORT_RP2
+    bool "RP2 Port"
+config PORT_MIMXRT
+    bool "MIMXRT Port"
+config PORT_SAMD
+    bool "SAMD Port"
+config PORT_NRF
+    bool "nRF Port"
+config PORT_CC3200
+    bool "CC3200 Port"
+config PORT_PIC16BIT
+    bool "PIC16BIT Port"
+config PORT_POWERPC
+    bool "PowerPC Port"
+config PORT_QEMU
+    bool "QEMU Port"
+config PORT_RENESAS_RA
+    bool "Renesas RA Port"
+config PORT_WEBASSEMBLY
+    bool "WebAssembly Port"
+config PORT_ZEPHYR
+    bool "Zephyr Port"
+
+endchoice
+
+# Source port Kconfig if selected
+if PORT_UNIX
+source "ports/unix/Kconfig"
+endif
+if PORT_STM32
+source "ports/stm32/Kconfig"
+endif
+if PORT_ESP32
+source "ports/esp32/Kconfig"
+endif
+if PORT_ESP8266
+source "ports/esp8266/Kconfig"
+endif
+if PORT_RP2
+source "ports/rp2/Kconfig"
+endif
+if PORT_MIMXRT
+source "ports/mimxrt/Kconfig"
+endif
+if PORT_SAMD
+source "ports/samd/Kconfig"
+endif
+if PORT_NRF
+source "ports/nrf/Kconfig"
+endif
+if PORT_CC3200
+source "ports/cc3200/Kconfig"
+endif
+if PORT_PIC16BIT
+source "ports/pic16bit/Kconfig"
+endif
+if PORT_POWERPC
+source "ports/powerpc/Kconfig"
+endif
+if PORT_QEMU
+source "ports/qemu/Kconfig"
+endif
+if PORT_RENESAS_RA
+source "ports/renesas-ra/Kconfig"
+endif
+if PORT_WEBASSEMBLY
+source "ports/webassembly/Kconfig"
+endif
+if PORT_ZEPHYR
+source "ports/zephyr/Kconfig"
+endif