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

[GaneshPatil7517]

Problem

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]

hello @pradeeban should i raise pr on this.....?