docs/install.rst

   1 Installation
   2 ############
   3
   4 System requirements
   5 ===================
   6
   7 nMigen requires Python 3.6; it works on CPython_ 3.6 (or newer), and works faster on PyPy3.6_ 7.2 (or newer).
   8
   9 For most workflows, nMigen requires Yosys_ 0.9 (or newer). A compatible version of Yosys is distributed via PyPI_ for most popular platforms.
  10
  11 Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.
  12
  13 Synthesizing, placing and routing an nMigen design for an FPGA requires the FPGA family specific toolchain.
  14
  15 .. TODO: Link to FPGA family docs here
  16
  17 .. _CPython: https://www.python.org/
  18 .. _PyPy3.6: https://www.pypy.org/
  19 .. _Yosys: http://www.clifford.at/yosys/
  20 .. _PyPI: https://pypi.org/
  21 .. _GTKWave: http://gtkwave.sourceforge.net/
  22
  23
  24 .. _install-deps:
  25
  26 Installing prerequisites
  27 ========================
  28
  29 .. content-tabs::
  30
  31    .. tab-container:: windows
  32       :title: Windows
  33
  34       `Install Python <python:using-on-windows>`_, either from Windows Store or using the full installer. If using the full installer, make sure to install a 64-bit version of Python.
  35
  36       `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.
  37
  38       .. _Download GTKWave: https://sourceforge.net/projects/gtkwave/files/
  39
  40    .. tab-container:: macos
  41       :title: macOS
  42
  43       Install Homebrew_. Then, install Python and GTKWave by running:
  44
  45       .. code-block:: console
  46
  47          $ brew install python gtkwave
  48
  49       .. _Homebrew: https://brew.sh
  50
  51    .. tab-container:: linux
  52       :title: Linux
  53
  54       .. rubric:: Debian-based distributions
  55
  56       Install Python and GTKWave by running:
  57
  58       .. code-block:: console
  59
  60          $ sudo apt-get install python3-pip gtkwave
  61
  62       On architectures other than x86_64 and AArch64, install Yosys by running:
  63
  64       .. code-block:: console
  65
  66          $ sudo apt-get install yosys
  67
  68       If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
  69
  70       .. rubric:: Other distributions
  71
  72       Install Python and GTKWave from the package repository of your distribution.
  73
  74       On architectures other than x86_64 and AArch64, install Yosys from the package repository of your distribution.
  75
  76       If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
  77
  78       .. _build Yosys from source: https://github.com/YosysHQ/yosys/#setup
  79
  80
  81 .. _install:
  82
  83 Installing nMigen
  84 =================
  85
  86 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.
  87
  88
  89 .. _install-release:
  90
  91 Latest release
  92 --------------
  93
  94 .. |release:install| replace:: To install the latest release of nMigen, run:
  95
  96 .. content-tabs::
  97
  98    .. tab-container:: windows
  99       :title: Windows
 100
 101       |release:install|
 102
 103       .. code-block:: doscon
 104
 105          > pip install --upgrade nmigen[builtin-yosys]
 106
 107    .. tab-container:: macos
 108       :title: macOS
 109
 110       |release:install|
 111
 112       .. code-block:: console
 113
 114          $ pip install --upgrade nmigen[builtin-yosys]
 115
 116    .. tab-container:: linux
 117       :title: Linux
 118
 119       If you **did not** install Yosys manually in the :ref:`previous step <install-deps>`, to install the latest release of nMigen, run:
 120
 121       .. code-block:: console
 122
 123          $ pip3 install --upgrade nmigen[builtin-yosys]
 124
 125       If you **did** install Yosys manually in the previous step, run:
 126
 127       .. code-block:: console
 128
 129          $ pip3 install --upgrade nmigen
 130
 131
 132 .. _install-develop:
 133
 134 Development snapshot
 135 --------------------
 136
 137 .. |snapshot:first-time| replace:: To install a development snapshot of nMigen for the first time, run:
 138 .. |snapshot:update| replace:: Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
 139 .. |snapshot:reinstall| replace:: It is important to run the ``pip3 install --editable .[builtin-yosys]`` each time the development snapshot is updated in case package dependencies have been added or changed. Otherwise, code using nMigen may misbehave or crash with an ``ImportError``.
 140
 141 .. content-tabs::
 142
 143    .. tab-container:: windows
 144       :title: Windows
 145
 146       |snapshot:first-time|
 147
 148       .. code-block:: doscon
 149
 150          > git clone https://github.com/nmigen/nmigen
 151          > cd nmigen
 152          > pip install --editable .[builtin-yosys]
 153
 154       |snapshot:update|
 155
 156       .. code-block:: doscon
 157
 158          > cd nmigen
 159          > git pull --ff-only origin master
 160          > pip install --editable .[builtin-yosys]
 161
 162       |snapshot:reinstall|
 163
 164    .. tab-container:: macos
 165       :title: macOS
 166
 167       |snapshot:first-time|
 168
 169       .. code-block:: console
 170
 171          $ git clone https://github.com/nmigen/nmigen
 172          $ cd nmigen
 173          $ pip install --editable .[builtin-yosys]
 174
 175       |snapshot:update|
 176
 177       .. code-block:: console
 178
 179          $ cd nmigen
 180          $ git pull --ff-only origin master
 181          $ pip install --editable .[builtin-yosys]
 182
 183       |snapshot:reinstall|
 184
 185    .. tab-container:: linux
 186       :title: Linux
 187
 188       If you have :ref:`previously <install-deps>` installed Yosys manually, omit ``[builtin-yosys]`` from the following commands.
 189
 190       |snapshot:first-time|
 191
 192       .. code-block:: console
 193
 194          $ git clone https://github.com/nmigen/nmigen
 195          $ cd nmigen
 196          $ pip3 install --editable .[builtin-yosys]
 197
 198       |snapshot:update|
 199
 200       .. code-block:: console
 201
 202          $ cd nmigen
 203          $ git pull --ff-only origin master
 204          $ pip3 install --editable .[builtin-yosys]
 205
 206       |snapshot:reinstall|
 207
 208
 209 Installing board definitions
 210 =============================
 211
 212 .. todo::
 213
 214          Explain how to install `<https://github.com/nmigen/nmigen-boards>`_.