47 Zeilen
2.5 KiB
Markdown
47 Zeilen
2.5 KiB
Markdown
# Troubleshooting
|
|
|
|
## CLI Build Error (ModuleNotFoundError)
|
|
|
|
### Issue Description
|
|
When compiling the project via an external system terminal (Command Line Interface) using `pio run`, the build might crash during the final linking stage with the following error:
|
|
```text
|
|
*** [.pio/build/ttgo-lora32-v21/firmware.elf] ModuleNotFoundError: No module named 'SCons.Tool.FortranCommon'
|
|
```
|
|
Interestingly, this error **does not occur** when triggering the build inside the integrated VS Code PlatformIO IDE.
|
|
|
|
### Root Cause
|
|
This behavior is caused by a **Python environment collision** on your local Linux system.
|
|
|
|
* **Inside the IDE (Success):** VS Code automatically sandboxes the execution path. It activates PlatformIO's isolated virtual environment (located at `~/.platformio/penv/`), ensuring that only the internally shipped, compatible dependencies are used.
|
|
* **Inside the System Terminal (Failure):** When calling `pio` globally, your shell utilizes the system's global Python environment. If global Python packages or system-wide SCons modules are present (e.g., installed via `apt`, `dnf`, or `pacman`), they collide with the PlatformIO Core engine. This breaks internal lookup paths, causing the compilation to miss the required `FortranCommon` module during the binary linking process.
|
|
|
|
### Solution
|
|
|
|
To resolve this issue permanently and ensure the CLI operates with the exact same isolation as the IDE, you must force your terminal to use PlatformIO's dedicated virtual environment binary.
|
|
|
|
#### Option 1: Configure Shell Aliases (Recommended)
|
|
Add an explicit alias to your shell configuration file to redirect global calls to the virtual environment binary.
|
|
|
|
1. Open your shell configuration file (e.g., `~/.bashrc` or `~/.zshrc`):
|
|
```bash
|
|
nano ~/.bashrc
|
|
```
|
|
2. Append the following lines at the very bottom of the file:
|
|
```bash
|
|
# Force the pio command to use PlatformIO's isolated virtual environment
|
|
alias pio="~/.platformio/penv/bin/pio"
|
|
alias platformio="~/.platformio/penv/bin/platformio"
|
|
```
|
|
3. Save the file and reload your current terminal session to apply the changes:
|
|
```bash
|
|
source ~/.bashrc
|
|
```
|
|
|
|
#### Option 2: Manually Activate the Virtual Environment
|
|
Alternatively, you can manually bootstrap the PlatformIO virtual environment inside your active terminal instance before running build tasks:
|
|
|
|
```bash
|
|
source ~/.platformio/penv/bin/activate
|
|
```
|
|
*(Once activated, your terminal prompt will typically show a `(penv)` prefix, indicating that the isolated environment is active).*
|