platformio / platformio/platformio-core

Feature: Track source file for each config option in ProjectConfig

Open
#5,384 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
9.5k
Forks
905
Avg merge
2d 13h
Merged PRs (30d)
2

Description

Feature: Track source file for each config option in ProjectConfig

Problem

When platformio.ini uses extra_configs to include additional .ini files, ProjectConfig merges all values into a flat dict via Python's configparser. After merging, there's no way to determine which file a particular config value came from.

This makes it difficult to:

  • Debug config issues: "Where is this lib_deps entry defined?" requires manually searching all included files
  • Build tooling: Tools that need to modify a config value (e.g. updating a library version) must independently re-parse every config file to find where the value is declared
  • Provide helpful diagnostics: pio project config could show the source file for each option, especially useful when values are overridden by later files
Proposed Solution

Add source file tracking to ProjectConfig so each option records which file it was loaded from.

API suggestion:

config = ProjectConfig.get_instance("platformio.ini")

# Existing — returns merged value
config.get("env:esp32", "lib_deps")
# => ["blues/Notecard @ ^1.8.3", "acme/Foo @ ^2.0"]

# New — returns the file path where the option was defined
config.get_source("env:esp32", "lib_deps")
# => "/path/to/shared/libs.ini"

For multi-value options like lib_deps where entries may come from different files (base [env] section vs env-specific), a per-entry variant would be even more useful:

config.get_sources("env:esp32", "lib_deps")
# => {
#   "blues/Notecard @ ^1.8.3": "/path/to/shared/libs.ini",
#   "acme/Foo @ ^2.0": "/path/to/platformio.ini",
# }
Implementation Notes

Python's configparser.ConfigParser doesn't track source files natively. One approach:

  • Override read() / read_file() to tag each option with its source path before merging
  • Store metadata in a parallel dict: {(section, option): filepath}
  • For list-valued options, track per-entry sources

The _parsed attribute already records which files were read (in order), so the infrastructure for tracking is partially there.

Use Cases
  1. pio project config --verbose — show where each value comes from, like git config --show-origin
  2. Dependency management tools — update version specs in the correct file when using extra_configs
  3. CI debugging — understand why a config value differs between environments when configs are split across files

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate ProjectConfig and inspect how its _parsed file list and ConfigParser read/read_file handling work. Define source metadata for merged options, including per-entry sources for list-valued options, and expose the proposed get_source or get_sources API. Done means values can be traced to their defining files, including overrides from extra_configs.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.