From e7ab78366d184a912f5f76d717f6aa387b7cd21c Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Mon, 25 May 2026 10:03:38 -0400
Subject: [PATCH] [core] Add esphome.build_flags option for IDF + PlatformIO
 (#16629)

---
 esphome/const.py                     |  1 +
 esphome/core/config.py               | 11 +++++++++++
 script/ci-custom.py                  |  2 +-
 tests/components/esphome/common.yaml |  2 ++
 4 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/esphome/const.py b/esphome/const.py
index 9dd77a7cb8..07f6bad771 100644
--- a/esphome/const.py
+++ b/esphome/const.py
@@ -199,6 +199,7 @@ CONF_BROKER = "broker"
 CONF_BSSID = "bssid"
 CONF_BUFFER_DURATION = "buffer_duration"
 CONF_BUFFER_SIZE = "buffer_size"
+CONF_BUILD_FLAGS = "build_flags"
 CONF_BUILD_PATH = "build_path"
 CONF_BUS_VOLTAGE = "bus_voltage"
 CONF_BUSY_PIN = "busy_pin"
diff --git a/esphome/core/config.py b/esphome/core/config.py
index 5a98b94781..6125c4ecc9 100644
--- a/esphome/core/config.py
+++ b/esphome/core/config.py
@@ -13,6 +13,7 @@ from esphome.const import (
     CONF_AREA,
     CONF_AREA_ID,
     CONF_AREAS,
+    CONF_BUILD_FLAGS,
     CONF_BUILD_PATH,
     CONF_COMMENT,
     CONF_COMPILE_PROCESS_LIMIT,
@@ -288,6 +289,7 @@ CONFIG_SCHEMA = cv.All(
                     cv.string_strict: cv.Any([cv.string], cv.string),
                 }
             ),
+            cv.Optional(CONF_BUILD_FLAGS, default=[]): cv.ensure_list(cv.string_strict),
             cv.Optional(CONF_ENVIRONMENT_VARIABLES, default={}): cv.Schema(
                 {
                     cv.string_strict: cv.string,
@@ -510,6 +512,12 @@ async def _add_platformio_options(pio_options):
         cg.add_platformio_option(key, val)
 
 
+@coroutine_with_priority(CoroPriority.FINAL)
+async def _add_build_flags(flags: list[str]) -> None:
+    for flag in flags:
+        cg.add_build_flag(flag)
+
+
 @coroutine_with_priority(CoroPriority.FINAL)
 async def _add_environment_variables(env_vars: dict[str, str]) -> None:
     # Set environment variables for the build process
@@ -705,6 +713,9 @@ async def to_code(config: ConfigType) -> None:
     if config[CONF_PLATFORMIO_OPTIONS]:
         CORE.add_job(_add_platformio_options, config[CONF_PLATFORMIO_OPTIONS])
 
+    if config[CONF_BUILD_FLAGS]:
+        CORE.add_job(_add_build_flags, config[CONF_BUILD_FLAGS])
+
     if config[CONF_ENVIRONMENT_VARIABLES]:
         CORE.add_job(_add_environment_variables, config[CONF_ENVIRONMENT_VARIABLES])
 
diff --git a/script/ci-custom.py b/script/ci-custom.py
index 56ca0d0355..51fea97874 100755
--- a/script/ci-custom.py
+++ b/script/ci-custom.py
@@ -562,7 +562,7 @@ def lint_constants_usage():
 # Maximum allowed CONF_ constants in esphome/const.py.
 # This file is frozen — new constants go in esphome/components/const/__init__.py.
 # Decrease this number when constants are moved out of const.py.
-CONST_PY_MAX_CONF = 1012
+CONST_PY_MAX_CONF = 1013
 
 
 @lint_content_check(include=["esphome/const.py"])
diff --git a/tests/components/esphome/common.yaml b/tests/components/esphome/common.yaml
index db75b08b38..93f82824e6 100644
--- a/tests/components/esphome/common.yaml
+++ b/tests/components/esphome/common.yaml
@@ -2,6 +2,8 @@ esphome:
   debug_scheduler: true
   platformio_options:
     board_build.flash_mode: dio
+  build_flags:
+    - "-DESPHOME_TEST_BUILD_FLAG"
   environment_variables:
     TEST_ENV_VAR: "test_value"
     BUILD_NUMBER: "12345"