Installation¶
Warning
The following instructions are a work-in-progress and may not be entirely up to date, or work for the target system, if you run into anything, please report an issue!
System requirements¶
Torii requires Python 3.10 or newer, and has been tested with CPython and PyPy, but only CPython is officially supported.
In addition, Torii also requires a copy of Yosys version 0.30 or newer, excluding version 0.37 due to a bug in the Verilog backend.
These are the only two “hard” requirements for Torii, you can do things like simulation without any additional software, however to view simulation results, a waveform viewer such as surfer or GTKWave is invaluable for debugging. Formal verification support, additionally needs sby and an SMT solver such as Yices or Bitwuzla.
To synthesize, place-and-route, and pack a Torii design for an FPGA, you need the toolchain specific to the family of FPGA you are targeting, see the platform specific documentation for more information regarding vendor toolchains.
Installing Prerequisites¶
Prior to installing Torii, install the required system prerequisites, and optionally the prerequisites for simulation and formal support.
Python and pip¶
First off, install python and pip as appropriate on your system if it’s not done so already.
$ sudo pacman -S python python-pip
$ sudo dnf install python3 python3-pip
$ sudo apt install python3 python3-pip
$ sudo zypper install python3 python3-pip
Install Homebrew if not done already, then install the requirements.
$ brew install python
Download the latest Python installer from the python downloads page.
Follow the instructions and ensure that the installer installs pip and puts the python executable in your %PATH%
Yosys¶
There are two primary ways to get a copy of Yosys for your system, the first is with the systems package manager, a.k.a “Native”, or via pre-build binary distributions provided by YosysHQ known as the OSS CAD Suite.
The OSS CAD Suite is very large and has lots of extra things, such as it’s own version of python, and a suite of other tools, it’s very convenient, but can cause some problems if you’re using it for your primary environment for Torii.
There is also a distribution of the Yosys toolchain built to target WASM and installable from pypi called YoWASP, currently Torii is not able to find a Yosys install from these so it is not a viable way to install Yosys for Torii to use at the moment.
On Arch Linux and Arch-likes, you can install nightly Yosys packages which are located in the AUR with an AUR helper or using makepkg directly.
$ yay -S yosys-nightly
$ git clone https://aur.archlinux.org/yosys-nightly.git
$ (cd yosys-nightly && makepkg -sic)
$ sudo dnf install yosys
Todo
Find a source for deb packages
Todo
Find a source for suse packages
Simply download the latest release for your architecture, extract it to a good home, and then add it to your $PATH
$ curl -LOJ https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2025-03-17/oss-cad-suite-linux-x64-20250317.tgz
$ tar xf oss-cad-suite-linux-x64-20250317.tgz
$ export PATH="$PATH:`pwd`/oss-cad-suite/bin"
For macOS systems it is recommended to use the OSS CAD Suite <https://github.com/YosysHQ/oss-cad-suite-build/tree/main>_ provided by YosysHQ.
There is also a distribution of the Yosys toolchain built to target WASM and installable from pypi called YoWASP, currently Torii is not able to find a Yosys install from these so it is not a viable way to install Yosys for Torii to use at the moment.
Simply download the latest release for your architecture, extract it to a good home, and then add it to your $PATH
$ curl -LOJ https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2025-03-17/oss-cad-suite-darwin-x64-20250317.tgz
$ tar xf oss-cad-suite-darwin-x64-20250317.tgz
$ export PATH="$PATH:`pwd`/oss-cad-suite/bin"
For Windows systems it is recommended to use the OSS CAD Suite <https://github.com/YosysHQ/oss-cad-suite-build/tree/main>_ provided by YosysHQ.
There is also a distribution of the Yosys toolchain built to target WASM and installable from pypi called YoWASP, currently Torii is not able to find a Yosys install from these so it is not a viable way to install Yosys for Torii to use at the moment.
Simply download the latest release for your architecture, extract it to a good home, and then add it to your $PATH
$ call %cd%\oss-cad-suite\environment.bat
Waveform Viewer (Optional)¶
An EDA Waveform Viewer is optional, but highly recommended. GTKWave is the standard of the Open Source EDA world, and has been around for a long time, and is what you will find most tutorials using. On the other hand, surfer is an up-and-coming waveform viewer that’s written in Rust and is able to run in your web browser via WASM.
There are two primary ways to get a waveform viewer for your system, the first is with the systems package manager, a.k.a “Native”, or via pre-build binary distributions provided by YosysHQ known as the OSS CAD Suite.
The OSS CAD Suite only provides GTKWave, so if you wish to use surfer instead see the Native install options.
$ sudo pacman -S gtkwave
$ sudo dnf install gtkwave
$ sudo apt install gtkwave
$ sudo zypper install gtkwave
There are two ways to install Surfer, the first is from source, and the other is using a pre-built binary.
Please see the surfer install instructions for up-to-date installation instructions for your platform.
The OSS-CAD-Suite builds come bundled with a copy of GTKWave. If you wish to use surfer, see the Native install instructions.
The OSS-CAD-Suite builds come bundled with a copy of GTKWave. If you wish to use surfer, see the Native install instructions.
There are two ways to install Surfer, the first is from source, and the other is using a pre-built binary.
Please see the surfer install instructions for up-to-date installation instructions for your platform.
The OSS-CAD-Suite builds come bundled with a copy of GTKWave. If you wish to use surfer, see the Native install instructions.
There are two ways to install Surfer, the first is from source, and the other is using a pre-built binary.
Please see the surfer install instructions for up-to-date installation instructions for your platform.
Formal Tools (Optional)¶
On Arch Linux and Arch-likes, you can install nightly sby packages which are located in the AUR with an AUR helper or using makepkg directly.
$ yay -S sby-nightly
$ git clone https://aur.archlinux.org/sby-nightly.git
$ (cd yosys-nightly && makepkg -sic)
The OSS-CAD-Suite builds already include sby as well as a suite of SMT solvers.
The OSS-CAD-Suite builds already include sby as well as a suite of SMT solvers.
The OSS-CAD-Suite builds already include sby as well as a suite of SMT solvers.
Installing Torii¶
The latest stable release of Torii is recommended for any new projects planning to use Torii. It provides the most up-to-date stable version of the API. However, if needed, you can also install a development snapshot to get access to the bleeding-edge, however things might break.
The stable release of Torii can be installed directly from PyPI.
$ pip3 install --user --upgrade torii
There are two possible ways to install a development snapshot for Torii, the first is using pip and to get it directly from GitHub.
The other way is to have a local git clone of the repository and install it in an editable manner, this is recommended if you plan to do any development work on Torii itself.
$ pip3 install --user 'torii @ git+https://github.com/shrine-maiden-heavy-industries/torii-hdl.git'
$ git clone https://github.com/shrine-maiden-heavy-industries/torii-hdl
$ cd torii-hdl
$ pip3 install --user --editable '.'
Any changes made to the torii-hdl directory will immediately affect any code that uses Torii. To update the snapshot, run:
$ cd torii-hdl
$ git pull --ff-only origin main
$ pip3 install --user --editable '.'
Run the pip3 install --editable . command each time the editable development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using Torii may misbehave or crash with an ImportError.
Installing Board Definitions¶
The torii-boards package includes a collection of pre-made board files for various FPGA development boards, it is generally useful to have.
Just like with Torii proper, there are two versions you can install, the latest stable, or the development version.
The stable release of Torii-boards can be installed directly from PyPI.
$ pip3 install --user --upgrade torii-boards
There are two possible ways to install a development snapshot for the board support package, the first is using pip and to get it directly from GitHub.
The other way is to have a local git clone of the repository and install it in an editable manner, this is recommended if you plan to do any development work on the board files themselves.s
$ pip3 install --user 'torii-boards @ git+https://github.com/shrine-maiden-heavy-industries/torii-boards.git'
$ git clone https://github.com/shrine-maiden-heavy-industries/torii-boards
$ cd torii-boards
$ pip3 install --user --editable '.'
Any changes made to the torii-boards directory will immediately affect any code that uses the board definitions.
To update the snapshot, run:
$ cd torii-boards
$ git pull --ff-only origin main
$ pip3 install --user --editable '.'
Run the pip3 install --editable . command each time the editable development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using Torii may misbehave or crash with an ImportError.
Next Steps¶
Now that you’ve installed Torii, see the getting started guide for a quick introduction, and the language guide for more in-depth documentation on the language.