Skip to content

feat(config): add source file tracking for config options#5387

Open
m-mcgowan wants to merge 2 commits intoplatformio:developfrom
m-mcgowan:feature/config-source-tracking
Open

feat(config): add source file tracking for config options#5387
m-mcgowan wants to merge 2 commits intoplatformio:developfrom
m-mcgowan:feature/config-source-tracking

Conversation

@m-mcgowan
Copy link

Summary

  • Add get_source(section, option) method to ProjectConfigBase that returns the file path where a given config option was last defined
  • Enables tools to determine which config file (main platformio.ini or extra_configs) contributes each option
  • Useful for lockfile generation, config debugging, and IDE tooling

How it works

During read(), each file is independently parsed to discover what sections/options it defines. A _source_map dict tracks (section, option) -> filepath, with later files overriding earlier ones -- matching the existing configparser merge semantics.

config = ProjectConfig("platformio.ini")
# Returns the file where lib_deps was last defined
source = config.get_source("env:myenv", "lib_deps")
# e.g. "/path/to/extra_envs.ini"

Test plan

  • Single file: all options trace back to the main ini
  • Extra configs: options defined in extra files trace to those files
  • Override semantics: when extra_debug.ini overrides a value from platformio.ini, get_source() returns extra_debug.ini
  • Unknown options: returns None for nonexistent section/option pairs
  • parse_extra=False: source tracking works without loading extra configs
  • All 25 existing tests continue to pass (1 skipped -- Windows-only)
  • pylint 10/10, black + isort clean

Add get_source(section, option) method to ProjectConfigBase that returns
the file path where a given option was last defined. This enables tools
to determine which config file (main platformio.ini or extra_configs)
contributes each option -- useful for lockfile generation, debugging
config resolution, and IDE tooling.

Implementation: independently parses each file during read() to build a
source map, matching configparser last-file-wins merge semantics.
@m-mcgowan m-mcgowan force-pushed the feature/config-source-tracking branch from 2d2d28e to 720b8f5 Compare February 20, 2026 10:45
@m-mcgowan m-mcgowan marked this pull request as draft February 20, 2026 10:52
@m-mcgowan
Copy link
Author

Follow-up commit adds a --show-source flag to pio project config that uses get_source() to annotate each option with the config file where it was defined.

Example output

Project with extra_configs pointing to shared config files:

$ pio project config --show-source

Computed project configuration for /path/to/project
platformio
----------
src_dir        =  /path/to/project/src  ; from platformio.ini
default_envs   =  esp32s3-idf           ; from platformio.ini
extra_configs  =  ../shared/platformio/platform_base.ini     ; from platformio.ini
                  ../shared/platformio/exceptions_base.ini
                  ../shared/platformio/idf_base.ini

env
---
custom_doctest_deps  =  https://github.com/eranpeer/FakeIt  ; from platformio.ini
                        doctest/doctest@^2.4.11

base:esp32s3
------------
platform                  =  https://...platform-espressif32.zip  ; from platform_base.ini
board                     =  esp32-s3-devkitm-1                   ; from platform_base.ini
framework                 =  arduino                              ; from platform_base.ini
board_build.psram         =  disabled                             ; from platform_base.ini
board_upload.flash_size   =  16MB                                 ; from platform_base.ini
lib_ldf_mode              =  chain                                ; from platform_base.ini
lib_compat_mode           =  strict                               ; from platform_base.ini

base:exceptions
---------------
build_flags    =  -fexceptions     ; from exceptions_base.ini
build_unflags  =  -fno-exceptions  ; from exceptions_base.ini

base:esp32s3-idf
----------------
extends    =  base:esp32s3    ; from idf_base.ini
framework  =  arduino, espidf ; from idf_base.ini

env:esp32s3-idf
---------------
extends      =  base:esp32s3-idf  ; from platformio.ini
                base:littlefs
                base:doctest
build_flags  =  -std=gnu++23      ; from platformio.ini
                -Wno-deprecated-declarations
                ...

Options inherited via extends show no source annotation (they're resolved from another section at query time, not defined in the consuming section).

Add get_source(section, option) method to ProjectConfigBase that returns
the file path where a given option was last defined. This enables tools
to determine which config file (main platformio.ini or extra_configs)
contributes each option -- useful for lockfile generation, debugging
config resolution, and IDE tooling.

Implementation: independently parses each file during read() to build a
source map, matching configparser last-file-wins merge semantics.
@m-mcgowan m-mcgowan marked this pull request as ready for review February 20, 2026 11:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant