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 .. |builtin-yosys-architectures| replace:: x86_64 and AArch64
  30
  31 .. platform-picker::
  32
  33    .. platform-choice:: windows
  34       :title: Windows
  35
  36       :ref:`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.
  37
  38       `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.
  39
  40       .. _Download GTKWave: https://sourceforge.net/projects/gtkwave/files/
  41
  42    .. platform-choice:: macos
  43       :title: macOS
  44
  45       Install Homebrew_. Then, install Python and GTKWave by running:
  46
  47       .. code-block:: console
  48
  49          $ brew install python gtkwave
  50
  51       .. _Homebrew: https://brew.sh
  52
  53    .. platform-choice:: debian
  54       :altname: linux
  55       :title: Debian
  56
  57       Install Python and GTKWave by running:
  58
  59       .. code-block:: console
  60
  61          $ sudo apt-get install python3-pip gtkwave
  62
  63       On architectures other than |builtin-yosys-architectures|, install Yosys by running:
  64
  65       .. code-block:: console
  66
  67          $ sudo apt-get install yosys
  68
  69       If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
  70
  71    .. platform-choice:: arch
  72       :altname: linux
  73       :title: Arch Linux
  74
  75       Install Python, pip, GTKWave and Yosys by running:
  76
  77       .. code-block:: console
  78
  79          $ sudo pacman -S python python-pip gtkwave yosys
  80
  81    .. platform-choice:: linux
  82       :title: Other Linux
  83
  84       Install Python and GTKWave from the package repository of your distribution.
  85
  86       On architectures other than |builtin-yosys-architectures|, install Yosys from the package repository of your distribution.
  87
  88       If Yosys 0.9 (or newer) is not available, `build Yosys from source`_.
  89
  90       .. _build Yosys from source: https://github.com/YosysHQ/yosys/#setup
  91
  92
  93 .. _install:
  94
  95 Installing nMigen
  96 =================
  97
  98 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.
  99
 100
 101 .. _install-release:
 102
 103 Latest release
 104 --------------
 105
 106 .. |release:install| replace:: To install the latest release of nMigen, run:
 107
 108 .. platform-picker::
 109
 110    .. platform-choice:: windows
 111       :title: Windows
 112
 113       |release:install|
 114
 115       .. code-block:: doscon
 116
 117          > pip install --upgrade nmigen[builtin-yosys]
 118
 119    .. platform-choice:: macos
 120       :title: macOS
 121
 122       |release:install|
 123
 124       .. code-block:: console
 125
 126          $ pip install --user --upgrade 'nmigen[builtin-yosys]'
 127
 128    .. platform-choice:: linux
 129       :title: Linux
 130
 131       If you **did not** install Yosys manually in the :ref:`previous step <install-deps>`, to install the latest release of nMigen, run:
 132
 133       .. code-block:: console
 134
 135          $ pip3 install --user --upgrade 'nmigen[builtin-yosys]'
 136
 137       If you **did** install Yosys manually in the previous step, run:
 138
 139       .. code-block:: console
 140
 141          $ pip3 install --user --upgrade nmigen
 142
 143    .. platform-choice:: arch
 144       :altname: linux
 145       :title: Arch Linux
 146
 147       |release:install|
 148
 149       .. code-block:: console
 150
 151          $ sudo pacman -S python-nmigen
 152
 153
 154 .. _install-snapshot:
 155
 156 Development snapshot
 157 --------------------
 158
 159 .. |snapshot:install| replace:: To install the latest development snapshot of nMigen, run:
 160
 161 .. platform-picker::
 162
 163    .. platform-choice:: windows
 164       :title: Windows
 165
 166       |snapshot:install|
 167
 168       .. code-block:: doscon
 169
 170          > pip install git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]
 171
 172    .. platform-choice:: macos
 173       :title: macOS
 174
 175       |snapshot:install|
 176
 177       .. code-block:: console
 178
 179          $ pip install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]'
 180
 181    .. platform-choice:: linux
 182       :title: Linux
 183
 184       If you **did not** install Yosys manually in the :ref:`previous step <install-deps>`, to install the latest release of nMigen, run:
 185
 186       .. code-block:: console
 187
 188          $ pip3 install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen[builtin-yosys]'
 189
 190       If you **did** install Yosys manually in the previous step, run:
 191
 192       .. code-block:: console
 193
 194          $ pip3 install --user 'git+https://github.com/nmigen/nmigen.git#egg=nmigen'
 195
 196
 197 .. _install-develop:
 198
 199 Editable development snapshot
 200 -----------------------------
 201
 202 .. |develop:first-time| replace:: To install an editable development snapshot of nMigen for the first time, run:
 203 .. |develop:update| replace:: Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
 204 .. |develop:reinstall| replace:: 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``.
 205
 206 .. platform-picker::
 207
 208    .. platform-choice:: windows
 209       :title: Windows
 210
 211       |develop:first-time|
 212
 213       .. code-block:: doscon
 214
 215          > git clone https://github.com/nmigen/nmigen
 216          > cd nmigen
 217          > pip install --editable .[builtin-yosys]
 218
 219       |develop:update|
 220
 221       .. code-block:: doscon
 222
 223          > cd nmigen
 224          > git pull --ff-only origin master
 225          > pip install --editable .[builtin-yosys]
 226
 227       Run the ``pip install --editable .[builtin-yosys]`` command |develop:reinstall|
 228
 229    .. platform-choice:: macos
 230       :title: macOS
 231
 232       |develop:first-time|
 233
 234       .. code-block:: console
 235
 236          $ git clone https://github.com/nmigen/nmigen
 237          $ cd nmigen
 238          $ pip install --user --editable '.[builtin-yosys]'
 239
 240       |develop:update|
 241
 242       .. code-block:: console
 243
 244          $ cd nmigen
 245          $ git pull --ff-only origin master
 246          $ pip install --user --editable '.[builtin-yosys]'
 247
 248       Run the ``pip install --editable .[builtin-yosys]`` command |develop:reinstall|
 249
 250    .. platform-choice:: linux
 251       :title: Linux
 252
 253       If you **did** install Yosys manually in the :ref:`previous step <install-deps>`, omit ``[builtin-yosys]`` from the following commands.
 254
 255       |develop:first-time|
 256
 257       .. code-block:: console
 258
 259          $ git clone https://github.com/nmigen/nmigen
 260          $ cd nmigen
 261          $ pip3 install --user --editable '.[builtin-yosys]'
 262
 263       |develop:update|
 264
 265       .. code-block:: console
 266
 267          $ cd nmigen
 268          $ git pull --ff-only origin master
 269          $ pip3 install --user --editable '.[builtin-yosys]'
 270
 271       Run the ``pip3 install --editable .[builtin-yosys]`` command |develop:reinstall|
 272
 273
 274 Installing board definitions
 275 =============================
 276
 277 .. todo::
 278
 279          Explain how to install `<https://github.com/nmigen/nmigen-boards>`_.