Guide on how to invoke Windows Vivado toolchain from WSL environment using wrapper scripts for cross-platform FPGA development and building.
This skill provides a configuration scheme to run development frameworks (such as LiteX, Cocotb, etc.) in a Linux/WSL environment while utilizing native Windows Vivado for synthesis, implementation, and bitstream loading.
Confirm the full path of vivado.bat on the Windows side.
D:/Xilinx/Vivado/2018.3/bin/vivado.batCreate a wrapper script in the WSL terminal (recommended path: ~/.local/bin/vivado):
#!/bin/bash
# Call Windows Vivado and forward all arguments
# Note: Use absolute path for cmd.exe to avoid PATH conflicts
/mnt/c/Windows/System32/cmd.exe /c "D:/Xilinx/Vivado/2018.3/bin/vivado.bat" "$@"
[!CAUTION] Line Ending Warning: The script must use LF (Linux) line endings. If created in Windows and copied to WSL, fix it using the following command in WSL:
sed -i 's/\r$//' /path/to/wrapper
chmod +x ~/.local/bin/vivadoPATH.
export PATH="$HOME/.local/bin:$PATH"
/mnt/c/ or /mnt/d/ to ensure Windows tools can directly access the files./mnt/d/litex) instead of an internal WSL path (e.g., /home/user/litex).Vivado TCL scripts generated by frameworks like LiteX use /mnt/d/... format paths, which Windows Vivado cannot recognize. They must be converted before running:
# Convert /mnt/d/ to D:/ format
sed -i 's|/mnt/d/|D:/|g' /mnt/d/litex/build/*/gateware/*.tcl
sed -i 's|/mnt/c/|C:/|g' /mnt/c/project/build/*/gateware/*.tcl
If you don't want to reinstall Python packages, you can redirect them via environment variables:
export PYTHONPATH=/mnt/d/litex/litex:/mnt/d/litex/litex-boards:/mnt/d/litex/migen:/mnt/d/litex/pythondata-cpu-vexriscv
| Issue | Cause | Solution |
|---|---|---|
bad interpreter | Script uses CRLF line endings | Convert using sed -i 's/\r$//'. |
syntax error near (...) | Windows PATH contains special characters | Export a stripped PATH: export PATH="/usr/bin:/bin:$HOME/.local/bin". |
vivado not found | Wrapper script not in PATH | Check if echo $PATH includes the script path. |
cmd.exe: command not found | Missing Windows interoperability path | Use absolute path /mnt/c/Windows/System32/cmd.exe. |
file.v does not exist | Incompatible TCL path format | Use sed to convert /mnt/X/ to X:/. |
Invoke directly from the WSL terminal:
vivado -version
Build Pynq-Z2 with LiteX:
python3 -m litex_boards.targets.tul_pynq_z2 --build