Skip to content

Commit 3a44dbd

Browse files
GaneshPatil7517GaneshPatil7517
committed
Docs: Add CONFIG.md documenting config files, env vars, and precedence (#503)
1 parent 032faa9 commit 3a44dbd

1 file changed

Lines changed: 226 additions & 0 deletions

File tree

‎docs/CONFIG.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# concore Configuration Reference
2+
3+
This document describes the configuration files used by `mkconcore.py` to locate compilers, runtimes, and Docker settings. All config files are read from `CONCOREPATH` — the directory containing `concore.py`.
4+
5+
## How CONCOREPATH Is Resolved
6+
7+
`mkconcore.py` resolves `CONCOREPATH` in the following order:
8+
9+
1. The directory containing `mkconcore.py` itself (if `concore.py` exists there)
10+
2. The current working directory (if `concore.py` exists there)
11+
3. Falls back to the `mkconcore.py` directory
12+
13+
---
14+
15+
## Configuration Files
16+
17+
### `concore.tools`
18+
19+
**Purpose:** Override compiler and runtime paths for all supported languages.
20+
21+
**Format:** Key-value pairs, one per line. Lines starting with `#` and blank lines are ignored.
22+
23+
```
24+
KEY=value
25+
```
26+
27+
**Supported Keys:**
28+
29+
| Key | Platform | Default | Description |
30+
|-----|----------|---------|-------------|
31+
| `CPPWIN` | Windows | `g++` | C++ compiler |
32+
| `CPPEXE` | POSIX | `g++` | C++ compiler |
33+
| `VWIN` | Windows | `iverilog` | Verilog compiler |
34+
| `VEXE` | POSIX | `iverilog` | Verilog compiler |
35+
| `PYTHONWIN` | Windows | `python` | Python interpreter |
36+
| `PYTHONEXE` | POSIX | `python3` | Python interpreter |
37+
| `MATLABWIN` | Windows | `matlab` | MATLAB executable |
38+
| `MATLABEXE` | POSIX | `matlab` | MATLAB executable |
39+
| `OCTAVEWIN` | Windows | `octave` | GNU Octave executable |
40+
| `OCTAVEEXE` | POSIX | `octave` | GNU Octave executable |
41+
| `JAVACWIN` | Windows | `javac` | Java compiler |
42+
| `JAVACEXE` | POSIX | `javac` | Java compiler |
43+
| `JAVAWIN` | Windows | `java` | Java runtime |
44+
| `JAVAEXE` | POSIX | `java` | Java runtime |
45+
46+
**Example (`concore.tools`):**
47+
48+
```
49+
CPPEXE=/usr/bin/g++
50+
PYTHONEXE=/opt/python3.11/bin/python3
51+
VEXE=/usr/local/bin/iverilog
52+
OCTAVEEXE=/usr/bin/octave
53+
JAVACEXE=/usr/lib/jvm/java-17/bin/javac
54+
JAVAEXE=/usr/lib/jvm/java-17/bin/java
55+
```
56+
57+
**Windows Example:**
58+
59+
```
60+
CPPWIN=C:\MinGW\bin\g++.exe
61+
PYTHONWIN=C:\Python313\python.exe
62+
JAVACWIN=C:\Program Files\Java\jdk-17\bin\javac.exe
63+
JAVAWIN=C:\Program Files\Java\jdk-17\bin\java.exe
64+
```
65+
66+
---
67+
68+
### `concore.octave`
69+
70+
**Purpose:** When this file is present, `.m` files are treated as GNU Octave instead of MATLAB. The file content is ignored — only its existence matters.
71+
72+
**Format:** Empty file (presence-based flag).
73+
74+
**How to enable:**
75+
76+
```bash
77+
touch $CONCOREPATH/concore.octave
78+
```
79+
80+
**How to disable:** Delete the file.
81+
82+
---
83+
84+
### `concore.mcr`
85+
86+
**Purpose:** Path to the local MATLAB Compiler Runtime (MCR) installation. Used when running compiled MATLAB executables instead of MATLAB directly.
87+
88+
**Format:** Single line containing the absolute path to the MCR installation.
89+
90+
**Default:** `~/MATLAB/R2021a`
91+
92+
**Example (`concore.mcr`):**
93+
94+
```
95+
/opt/matlab/mcr/v913
96+
```
97+
98+
**Windows Example:**
99+
100+
```
101+
C:\Program Files\MATLAB\R2021a\runtime\win64
102+
```
103+
104+
---
105+
106+
### `concore.sudo`
107+
108+
**Purpose:** Override the Docker executable command. Originally intended to control whether Docker runs with `sudo`, but can specify any container runtime (Docker, Podman, etc.).
109+
110+
**Format:** Single line containing the Docker executable command.
111+
112+
**Default:** `docker` (from `DOCKEREXE` environment variable, or the literal string `docker`)
113+
114+
**Example (`concore.sudo`):**
115+
116+
```
117+
sudo docker
118+
```
119+
120+
**To use Podman instead of Docker:**
121+
122+
```
123+
podman
124+
```
125+
126+
---
127+
128+
### `concore.repo`
129+
130+
**Purpose:** Override the Docker Hub repository prefix used when pulling pre-built images.
131+
132+
**Format:** Single line containing the Docker Hub username or organization.
133+
134+
**Default:** `markgarnold`
135+
136+
**Example (`concore.repo`):**
137+
138+
```
139+
myorganization
140+
```
141+
142+
This means Docker images will be pulled from `myorganization/<image-name>` instead of `markgarnold/<image-name>`.
143+
144+
---
145+
146+
## Environment Variables
147+
148+
Environment variables are read **before** config files and provide initial defaults. Config files override environment variables.
149+
150+
| Variable | Default | Description |
151+
|----------|---------|-------------|
152+
| `CONCORE_CPPWIN` | `g++` | Windows C++ compiler |
153+
| `CONCORE_CPPEXE` | `g++` | POSIX C++ compiler |
154+
| `CONCORE_VWIN` | `iverilog` | Windows Verilog compiler |
155+
| `CONCORE_VEXE` | `iverilog` | POSIX Verilog compiler |
156+
| `CONCORE_PYTHONEXE` | `python3` | POSIX Python interpreter |
157+
| `CONCORE_PYTHONWIN` | `python` | Windows Python interpreter |
158+
| `CONCORE_MATLABEXE` | `matlab` | POSIX MATLAB executable |
159+
| `CONCORE_MATLABWIN` | `matlab` | Windows MATLAB executable |
160+
| `CONCORE_OCTAVEEXE` | `octave` | POSIX GNU Octave executable |
161+
| `CONCORE_OCTAVEWIN` | `octave` | Windows GNU Octave executable |
162+
| `CONCORE_JAVACEXE` | `javac` | POSIX Java compiler |
163+
| `CONCORE_JAVACWIN` | `javac` | Windows Java compiler |
164+
| `CONCORE_JAVAEXE` | `java` | POSIX Java runtime |
165+
| `CONCORE_JAVAWIN` | `java` | Windows Java runtime |
166+
| `DOCKEREXE` | `docker` | Docker executable |
167+
168+
---
169+
170+
## Precedence (Priority Order)
171+
172+
When `mkconcore.py` resolves a tool path, the following precedence applies (highest priority first):
173+
174+
1. **`concore.tools` file** — overrides everything for compiler/runtime paths
175+
2. **`concore.sudo` file** — overrides `DOCKEREXE` for Docker executable
176+
3. **`concore.repo` file** — overrides `DOCKEREPO` for Docker repository
177+
4. **Environment variables** (`CONCORE_*`, `DOCKEREXE`) — initial defaults
178+
5. **Hardcoded defaults** — `g++`, `python3`, `iverilog`, `octave`, `docker`, etc.
179+
180+
For `concore.octave` and `concore.mcr`, there is no environment variable equivalent — they are controlled only by file presence/content.
181+
182+
---
183+
184+
## Quick Start
185+
186+
**Minimal setup (Python-only study on Linux):**
187+
188+
No config files needed — defaults work out of the box.
189+
190+
**Typical setup (Python + C++ on Linux):**
191+
192+
```bash
193+
# Only needed if g++ is not on PATH
194+
echo "CPPEXE=/usr/local/bin/g++-13" > $CONCOREPATH/concore.tools
195+
```
196+
197+
**Windows setup (Python + C++):**
198+
199+
```
200+
CPPWIN=C:\MinGW\bin\g++.exe
201+
PYTHONWIN=C:\Python313\python.exe
202+
```
203+
204+
**Docker without sudo:**
205+
206+
```bash
207+
echo "docker" > $CONCOREPATH/concore.sudo
208+
```
209+
210+
**Using Octave instead of MATLAB:**
211+
212+
```bash
213+
touch $CONCOREPATH/concore.octave
214+
```
215+
216+
---
217+
218+
## Diagnostic
219+
220+
Run `concore doctor` to see all detected tools, config file status, and environment variables in a single readiness report:
221+
222+
```
223+
$ concore doctor
224+
```
225+
226+
See the [CLI README](../concore_cli/README.md) for details.

0 commit comments

Comments
 (0)