Documentation: Standardized Configuration Schema for concore.toml and Legacy Config Files

[GaneshPatil7517]

New users don't know how to configure concore. Currently, tool paths are scattered across four separate files:

• concore.tools - compiler/runtime paths
• concore.octave - enables Octave for .m files
• concore.mcr - path to MATLAB Compiler Runtime
• concore.sudo - Docker executable (e.g., sudo docker vs docker)

There is no single document showing:

• What fields exist in each file?
• What are valid values?
• Which files override which?
• How do they interact?
• What happens if a file is missing?

This creates friction for onboarding and contradicts concore's goal of improving UX.

Current State
From mkconcore.py , I can see the loader reads these files and environment variables, but the logic is implicit in code, not in documentation.

Proposed Solution
Create CONFIG.md documenting the unified and legacy config format.

Legacy Format (still supported)
concore.tools
Purpose: Override compiler and runtime paths
Example:
g++ = /usr/bin/g++
python3 = /opt/python3.11/bin/python3
iverilog = /usr/local/bin/iverilog

concore.octave
Purpose: Treat .m files as Octave (present = enabled, absent = disabled)

concore.mcr
Purpose: Path to MATLAB Compiler Runtime
Example:
/opt/matlab/mcr/v913

concore.sudo
Purpose: Docker executable (default: docker; can be: sudo docker, podman, etc.)
Example:
sudo docker

New Unified Format (concore.toml)
[tools]
g++ = "/usr/bin/g++"
python3 = "/opt/python3.11/bin/python3"
iverilog = "/usr/local/bin/iverilog"

[features]
octave_enabled = true

[matlab]
mcr_path = "/opt/matlab/mcr/v913"

[docker]
executable = "sudo docker"

Precedence (Priority Order)

1. Environment variables (highest)
2. concore.toml [tools] section
3. Legacy concore.tools file
4. Auto-detected via shutil.which()
5. Defaults (lowest)

Benefits

• Single source of truth for configuration
• Reduces onboarding friction - new users know what to configure
• Unblocks the concore setup wizard (knows what to write)
• Supports backward compatibility - old files still work

Implementation Tasks

• Create docs/CONFIG.md with full schema and precedence rules
• Add example files to example/concore.toml
• Update CLI README with config precedence table
• Add inline comments to mkconcore.py explaining loader logic

[GaneshPatil7517]

Hi @pradeeban and @Rahuljagwani, I’d like to work on this issue (#503).
Can you please assign it to me? I’ll start with the documentation for the unified config schema and precedence rules.
Thank you!

[pradeeban]

Hold on. This is a more time-consuming endeavor than you would imagine. There are concore-editor scripts accessing these, if I remember correctly. So, a cross-repository analysis is necessary to not break anything. Best to leave it as-is. If your goal is to simply document these four files somewhere handy, go for it.

[GaneshPatil7517]

Thank you @pradeeban understood. I'll keep it purely documentation: a docs/CONFIG.md that documents the four existing config files (format, valid values, precedence) without changing any code or config format. No modifications to mkconcore.py or the config loader.