Installation

Warning

The following instructions are a work-in-progress and may not be entirely up to date.

SOL requires Python >= 3.10, and Yosys >= 0.30 except for 0.37 due to a Verilog backend bug. SOL has been tested with CPython, but might possibly run under PyPy.

SOL is built off of the Torii Hardware Definition Language, as such that is also required.

Installing Prerequisites

Prior to installing SOL, you must install all of its prerequisites and requirements.

Installing Python

First off, install python and pip onto your system if the’re not there already.

Arch Linux

$ sudo pacman -S python python-pip

Other Linux

Warning

These instructions may be incorrect or incomplete!

For Debian based systems, use apt to install python3 and python3-pip

$ sudo apt install python3 python3-pip

For Fedora and other dnf based systems,

$ sudo dnf install python3 python3-pip

macOS

Install Homebrew if not done already, then install the requirements.

$ brew install python

Windows

Warning

These instructions may be incorrect or incomplete!

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%

Installing Yosys

Arch Linux

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.

Via an AUR helper like yay

$ yay -S yosys-nightly

Via makepkg directly

$ git clone https://aur.archlinux.org/yosys-nightly.git
$ (cd yosys-nightly && makepkg -sic)

Other Linux

Warning

These instructions may be incorrect or incomplete!

With other Linux distributions, it is recommended to use the OSS Cad Suite nightly build. It provides a full environment of all the tools needed built on a nightly basis. This includes Yosys and GTKWave

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/2022-04-26/oss-cad-suite-linux-x64-20240710.tgz
$ tar xfv oss-cad-suite-linux-x64-20240710.tgz
$ export PATH="`pwd`/oss-cad-suite/bin:$PATH"

macOS

For macOS systems, it is recommended to use the YoWASP distribution of the toolchain. However if you want to use the native tools, and you are using an Intel based Mac, then the OSS Cad Suite has nightly builds for x86_64 versions of Darwin. This includes Yosys and GTKWave

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/2022-04-26/oss-cad-suite-darwin-x64-20240710.tgz
$ tar xfv oss-cad-suite-darwin-x64-220240710.tgz
$ export PATH="`pwd`/oss-cad-suite/bin:$PATH"

Windows

Warning

These instructions may be incorrect or incomplete!

The OSS Cad Suite has nightly builds for x86_64 versions of Windows. This includes Yosys and GTKWave

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

Installing Torii

Next, install the latest stable version of Torii from PyPi.

Linux

$ pip3 install --user --upgrade torii

macOS

$ pip install --user --upgrade torii

Windows

> pip install --upgrade torii

Installing SOL

The latest release of SOL is recommended for any new projects planning to use SOL. 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 the API may be unstable.

Latest release

Linux

$ pip3 install --user --upgrade sol-usb

macOS

$ pip install --user --upgrade sol-usb

Windows

> pip install --upgrade sol-usb

Development snapshot

Linux

$ pip3 install --user 'sol-usb @ git+https://github.com/shrine-maiden-heavy-industries/sol.git'

macOS

$ pip install --user 'sol-usb @ git+https://github.com/shrine-maiden-heavy-industries/sol.git'

Windows

> pip install "sol-usb @ git+https://github.com/shrine-maiden-heavy-industries/sol.git"

Editable development snapshot

Linux

To install an editable development snapshot of SOL for the first time, run:

$ git clone https://github.com/shrine-maiden-heavy-industries/sol
$ cd sol
$ pip3 install --user --editable '.'

Any changes made to the sol directory will immediately affect any code that uses SOL. To update the snapshot, run:

$ cd sol
$ 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 SOL may misbehave or crash with an ImportError.

macOS

To install an editable development snapshot of SOL for the first time, run:

$ git clone https://github.com/shrine-maiden-heavy-industries/sol
$ cd sol
$ pip install --user --editable '.'

Any changes made to the sol directory will immediately affect any code that uses SOL. To update the snapshot, run:

$ cd sol
$ git pull --ff-only origin main
$ pip install --user --editable '.'

Run the pip install --editable . command each time the editable development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using SOL may misbehave or crash with an ImportError.

Windows

To install an editable development snapshot of SOL for the first time, run:

> git clone https://github.com/shrine-maiden-heavy-industries/sol
> cd sol
> pip install --editable .

Any changes made to the sol directory will immediately affect any code that uses SOL. To update the snapshot, run:

> cd sol
> git pull --ff-only origin main
> pip install --editable .

Run the pip install --editable . command each time the editable development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using SOL may misbehave or crash with an ImportError.