Installation

System requirements

nMigen requires Python 3.6; it works on CPython 3.6 (or newer), and works faster on PyPy3.6 7.2 (or newer).

For most workflows, nMigen requires Yosys 0.9 (or newer). A compatible version of Yosys is distributed via PyPI for most popular platforms.

Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave is invaluable for debugging.

Synthesizing, placing and routing an nMigen design for an FPGA requires the FPGA family specific toolchain.

Installing prerequisites

Windows

Install Python, either from Windows Store or using the full installer. If using the full installer, make sure to install a 64-bit version of Python.

Download GTKWave, either win32 or win64 binaries. GTKWave does not need to be installed; it can be unpacked to any convenient location and run from there.

macOS

Install Homebrew. Then, install Python and GTKWave by running:

$ brew install python gtkwave

Debian

Install Python and GTKWave by running:

$ sudo apt-get install python3-pip gtkwave

On architectures other than x86_64 and AArch64, install Yosys by running:

$ sudo apt-get install yosys

If Yosys 0.9 (or newer) is not available, build Yosys from source.

Arch Linux

Install Python, pip, GTKWave and Yosys by running:

$ sudo pacman -S python python-pip gtkwave yosys

Other Linux

Install Python and GTKWave from the package repository of your distribution.

On architectures other than x86_64 and AArch64, install Yosys from the package repository of your distribution.

If Yosys 0.9 (or newer) is not available, build Yosys from source.

Installing nMigen

The latest release of nMigen should work well for most applications. A development snapshot—any commit from the master branch of nMigen—should be similarly reliable, but is likely to include experimental API changes that will be in flux until the next release. With that in mind, development snapshots can be used to try out new functionality or to avoid bugs fixed since the last release.

Latest release

Windows

To install the latest release of nMigen, run:

> pip install --upgrade nmigen[builtin-yosys]

macOS

To install the latest release of nMigen, run:

$ pip install --user --upgrade 'nmigen[builtin-yosys]'

Linux

If you did not install Yosys manually in the previous step, to install the latest release of nMigen, run:

$ pip3 install --user --upgrade 'nmigen[builtin-yosys]'

If you did install Yosys manually in the previous step, run:

$ pip3 install --user --upgrade nmigen

Arch Linux

To install the latest release of nMigen, run:

$ sudo pacman -S python-nmigen

Development snapshot

Windows

To install the latest development snapshot of nMigen, run:

> pip install git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]

macOS

To install the latest development snapshot of nMigen, run:

$ pip install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]'

Linux

If you did not install Yosys manually in the previous step, to install the latest release of nMigen, run:

$ pip3 install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]'

If you did install Yosys manually in the previous step, run:

$ pip3 install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen'

Editable development snapshot

Windows

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

> git clone https://github.com/nmigen/nmigen
> cd nmigen
> pip install --editable .[builtin-yosys]

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

> cd nmigen
> git pull --ff-only origin master
> pip install --editable .[builtin-yosys]

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

macOS

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

$ git clone https://github.com/nmigen/nmigen
$ cd nmigen
$ pip install --user --editable '.[builtin-yosys]'

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

$ cd nmigen
$ git pull --ff-only origin master
$ pip install --user --editable '.[builtin-yosys]'

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

Linux

If you did install Yosys manually in the previous step, omit [builtin-yosys] from the following commands.

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

$ git clone https://github.com/nmigen/nmigen
$ cd nmigen
$ pip3 install --user --editable '.[builtin-yosys]'

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

$ cd nmigen
$ git pull --ff-only origin master
$ pip3 install --user --editable '.[builtin-yosys]'

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

Installing board definitions

Todo

Explain how to install https://github.com/nmigen/nmigen-boards.