openXC7 toolchain installer

This is an open source FPGA toolchain using yosys and openXC7/nextpnr for Xilinx 7 series FPGAs (Spartan7, Artix7, Zynq7), with added support for Kintex7 FPGAs (70T, 160T, 325T, 420T, 480T).

Recommended Installation Methods

Nix

The nix-based toolchain is the recommended option for Linux and macOS. It supports the full feature set, including the GHDL plugin in yosys for VHDL.

See: https://github.com/openXC7/toolchain-nix/

Apio

Apio is a lightweight, pip-installable CLI that wraps yosys, nextpnr, and the openXC7 database. It provides the simplest getting-started experience: no snap, no nix, no manual builds.

pip install apio
apio install system

See: https://github.com/FPGAwars/apio

Alternative: Build from Sources

The toolchain-sources-builder.sh script provides an alternative to Nix or Apio for users who prefer to build from source. It automates downloading, building, and installing the toolchain components into /opt/openxc7.

The source builder supports macOS with Homebrew and Debian/Ubuntu Linux with APT. On macOS, install the Xcode command line tools (xcode-select --install) and Homebrew first. Run the script as your normal user; it uses sudo when system packages or the installation directory require it.

Use a dedicated build directory. The script resets and cleans its downloaded source repositories on subsequent runs, so the build directory is only needed while the builder runs: the installation itself is self-contained.

Objectives

The script handles the following tasks:

• cloning, updating and checking out yosys/nextpnr/prjxray/prjxray-db/fpga-assembler repositories
• building each specified tool
• installing the resulting binaries into /opt/openxc7

Usage

The script can be executed with or without arguments:

• with no arguments or all: downloads, builds and installs all supported tools
• with specific tool names (yosys and/or prjxray and/or nextpnr and/or fpga-as) only the specified tools will be downloaded, built, and installed

./toolchain-sources-builder.sh all

To use a different absolute installation path or limit parallel compilation:

INSTALL_PREFIX="$HOME/opt/openxc7" JOBS=4 ./toolchain-sources-builder.sh all

Python dependencies, including FASM's statically linked ANTLR parser, are installed in a virtual environment under the installation prefix. System Python packages are not modified. If the system CMake is older than the 3.28 required by Yosys, the builder installs a newer CMake in that environment as well.

The Project X-Ray database pin must match the database submodule of the pinned nextpnr revision. Updating just one can produce missing-feature errors during fasm2frames conversion.

Bitstreams are assembled by fpga-as, which replaces the fasm2frames + xc7frames2bit pair the makefiles used to call: it emits the same frames in one process and is 9x to 120x faster on the demo designs. It is built with Bazel, which the distributions do not package, so the builder downloads the pinned Bazel release binary for the host and verifies it against the checksum published next to that release before using it. Everything else the build needs -- a C++ toolchain and the JDK that FASM already requires -- comes from the dependencies above.

Environment setup

After installation, the script generates a file at /opt/openxc7/export.sh, which can be sourced in your terminal to update the environment variables accordingly:

source /opt/openxc7/export.sh

For a custom INSTALL_PREFIX, source export.sh from that directory instead.

This allows you to use the installed tools in your current shell session without manually modifying/adding:

• PATH
• NEXTPNR_XILINX_DIR
• NEXTPNR_XILINX_PYTHON_DIR
• PRJXRAY_DB_DIR

Shared installations

The Python packages are installed in a virtual environment inside INSTALL_PREFIX rather than in the system or user Python, so an installation does not depend on the HOME of the user who ran the builder and can live on a filesystem shared by several users and machines, for example over NFS. Two things have to hold for that:

• everyone who uses the installation must be able to read it, which a restrictive umask breaks:

  chmod -R a+rX /srv/openxc7

• every client must mount the prefix at the same path and provide the same python3 minor version, because venv/bin/* carry absolute shebangs and pyvenv.cfg records the interpreter used at installation time.

An environment exported by an older version of this script may leave a PYTHONPATH pointing at the prefix's lib/python; that would take precedence over the virtual environment, so source the current export.sh instead.

Installer checks

The offline regression checks require Bash, Git and Python 3:

bash -n toolchain-sources-builder.sh
python3 -m unittest discover -s tests -v
shellcheck toolchain-sources-builder.sh tests/smoke-toolchain.sh

These checks cover installer control flow; validating a toolchain build also requires running the builder and generating a bitstream with the installed tools. After sourcing export.sh, run bash tests/smoke-toolchain.sh to synthesize, place and route an Arty A7-35T blinky design and generate its bitstream. This also exercises chip database generation and FASM's fast parser; it does not program hardware.