Installation — Ubuntu (native)¶
Setting up the full toolchain on native Ubuntu (bare-metal or VM). Tested on Ubuntu 22.04 LTS (x86_64).
On Windows? Use the WSL2 guide instead
Use the WSL2 guide instead. A helper script sets up the WSL distro (kernel modules included) and then runs this same installer inside it, plus the Windows-side USB forwarding needed to program a board.
There are two ways to install:
- Automatic — one command, recommended for most people.
- Manual — step by step, if you want to understand or customise each part.
Both install the same tools at the fixed locations Anvil expects (~/opt/anvil,
~/opt/sv2v/sv2v, ~/miniconda3 with the xc7 env, ~/opt/f4pga).
Automatic installation¶
The toolchain-setup script
installs everything and runs an end-to-end build to verify it works.
Prefer to read it before running (good practice for any curl | bash):
git clone https://github.com/LogiSmith/toolchain-setup.git
cd toolchain-setup
less install.sh # review
./install.sh
The script is idempotent — re-running it skips anything already installed.
Options¶
| Flag | Effect |
|---|---|
--minimal |
Skip optional tools (RISC-V toolchain + openFPGALoader/board) |
--no-board |
Skip only openFPGALoader + udev (no board programming) |
--no-test |
Skip the end-to-end build self-test |
--skip-apt |
Skip the apt steps (deps already present) |
-h, --help |
Show help |
Example — minimal install without board tooling (e.g. a headless test box):
How to know it worked¶
The installer is fail-fast: it stops at the first step that fails. So the sign of success is the green banner at the very end:
If you see that, everything installed and the end-to-end test passed. If instead
you see a red ✗ Install failed during step: …, it tells you which step failed
and how to fix it — fix that and re-run (the installer is idempotent).
After it finishes¶
Open a new shell (or source ~/.bashrc) so the anvil alias and Conda are
active, then confirm:
That's it — skip the manual section below. It remains as a reference for what the script does and for troubleshooting.
Manual installation¶
Follow these if you prefer to install step by step, or to understand what the
automatic script does. Keep the paths as-is unless you also change them in
anvil.py.
1. Build dependencies¶
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y build-essential flex bison libssl-dev \
libelf-dev bc python3 pahole cmake pkg-config \
libusb-1.0-0-dev libudev-dev git g++ gcc \
libftdi1-dev libhidapi-dev zlib1g-dev unzip wget
Simulator + waveform viewer (needed for anvil test):
2. Anvil CLI¶
git clone https://github.com/LogiSmith/Anvil.git ~/opt/anvil
chmod +x ~/opt/anvil/anvil.py
echo 'alias anvil="python3 ~/opt/anvil/anvil.py"' >> ~/.bashrc
source ~/.bashrc
anvil --help
3. sv2v (SystemVerilog → Verilog)¶
Anvil converts every .sv source with sv2v. Install the release binary to
~/opt/sv2v/sv2v:
wget https://github.com/zachjs/sv2v/releases/download/v0.0.13/sv2v-Linux.zip -O /tmp/sv2v.zip
unzip -o /tmp/sv2v.zip -d /tmp
mkdir -p ~/opt/sv2v
cp /tmp/sv2v-Linux/sv2v ~/opt/sv2v/sv2v
chmod +x ~/opt/sv2v/sv2v
~/opt/sv2v/sv2v --version
4. F4PGA (synthesis & place/route)¶
4.1 Miniconda¶
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/miniconda.sh
bash /tmp/miniconda.sh -b -p ~/miniconda3
source ~/miniconda3/etc/profile.d/conda.sh
echo "source ~/miniconda3/etc/profile.d/conda.sh" >> ~/.bashrc
4.2 Conda environment¶
git clone https://github.com/chipsalliance/f4pga-examples ~/f4pga-examples
cd ~/f4pga-examples
conda env create -f environment.yml
conda activate xc7
If
environment.ymlis not found, tryconda env create -f xc7/environment.yml.
4.3 Architecture definitions (Artix-7)¶
export F4PGA_INSTALL_DIR=~/opt/f4pga
export FPGA_FAM=xc7
mkdir -p $F4PGA_INSTALL_DIR/$FPGA_FAM
F4PGA_TIMESTAMP='20220907-210059'
F4PGA_HASH='66a976d'
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-install-xc7-${F4PGA_HASH}.tar.xz | tar -xJC $F4PGA_INSTALL_DIR/${FPGA_FAM}
wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/${F4PGA_TIMESTAMP}/symbiflow-arch-defs-xc7a100t_test-${F4PGA_HASH}.tar.xz | tar -xJC $F4PGA_INSTALL_DIR/${FPGA_FAM}
4.4 Carry-chain patch¶
Complex designs (e.g. a PicoRV32 SoC) hit a known assertion bug in F4PGA's carry-chain fixer. Apply this one-time patch:
sed -i 's/assert list_of_cells\[0\] is None, (bit, list_of_cells\[0\], cellname)/if list_of_cells[0] is not None: continue/' \
~/miniconda3/envs/xc7/lib/python3.7/site-packages/f4pga/utils/xc7/fix_xc7_carry.py
It relaxes an overly strict assertion that fails on multi-driver nets; the tool continues correctly afterwards.
5. RISC-V toolchain (optional — SoC firmware)¶
Needed only for anvil compile (SoC projects with C/C++ firmware):
6. openFPGALoader (optional — programming a board)¶
The apt/conda version is too old — build from source.
git clone https://github.com/trabucayre/openFPGALoader /tmp/ofl
cd /tmp/ofl && mkdir build && cd build
cmake .. && make -j$(nproc) && sudo make install
/usr/local/bin/openFPGALoader --Version
USB permissions for the board (Nexys A7 = FTDI 0403:6010):
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="0666", GROUP="plugdev"' \
| sudo tee /etc/udev/rules.d/99-openfpgaloader.rules
sudo usermod -aG plugdev $USER
sudo udevadm control --reload-rules && sudo udevadm trigger
Verify¶
All required tools (Python, sv2v, F4PGA / Conda) should report OK.
Optional rows may be WARN if you skipped sections 5–6.
Then build a real example end to end:
mkdir -p ~/projects/uart-hello && cd ~/projects/uart-hello
anvil init --board Nexys-A7-100T --example uart-hello
anvil build
A bitstream under build/<target>/top.bit means the toolchain works.
Troubleshooting¶
Click an entry to expand it. Anything not here is in the general Troubleshooting & FAQ.
[ERROR] Run as a normal user (not root); sudo is used where needed
The installer refuses to run as root on purpose: everything it puts in your home directory — Miniconda, the F4PGA environment, the Anvil clone — would end up owned by root and unusable from your own account.
Run it as yourself, without sudo. It asks for the password when it needs it.
[ERROR] Miniconda at ~/miniconda3 looks incomplete (interrupted install)
A previous run was stopped part-way. The installer will not write into a half-finished install, because the result is worse than either state.
The same applies to the Conda environment:
[ERROR] download failed (network?) or checksum mismatch
The F4PGA architecture definitions and the toolchains are a few hundred MB, and a dropped connection leaves a truncated file. A checksum mismatch is the installer catching exactly that — it is not a sign that anything was tampered with.
Re-running is safe and resumes: finished steps are skipped.
If it keeps failing on the same URL, you are probably behind a proxy or a captive portal that answers with an HTML page instead of the file.
Out of disk space part-way through
The toolchain needs roughly 25 GB. Most of it is the Conda environment and the F4PGA architecture definitions, and Verilator is built from source.
Free some space and re-run — nothing is deleted on a retry, so it picks up where it stopped.
anvil: command not found after installing
The anvil alias is added to ~/.bashrc, which only takes effect in a new
shell.
If that does not help, the clone is at ~/.anvil and can be called directly:
python3 ~/.anvil/anvil.py doctor.
anvil doctor reports FAIL for F4PGA / Conda
Conda is installed but the xc7 environment is missing or incomplete —
usually an interrupted step 4.2.