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 Simulating nMigen code requires no additional software. However, a waveform viewer like GTKWave_ is invaluable for debugging.
  10
  11 Converting nMigen code to Verilog requires Yosys_ 0.9 (or newer).
  12
  13 Synthesizing, placing and routing an nMigen design for an FPGA requires Yosys_ 0.9 (or newer), as well as 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 .. _GTKWave: http://gtkwave.sourceforge.net/
  21
  22
  23 Installing prerequisites
  24 ========================
  25
  26 ... on Windows
  27 --------------
  28
  29 .. todo::
  30
  31    Determine what's appropriate here (do we put Python in PATH? what about Yosys? is there something better than GTKWave? do we just give up and suggest WSL?)
  32
  33
  34 ... on Debian Linux
  35 -------------------
  36
  37 nMigen works on Debian 10 or newer. The required version of Yosys is available in the main repository since Debian 11, but requires the Backports_ repository on Debian 10. Run:
  38
  39 .. note: debian 10 provides: python3 3.7.3, yosys 0.8 (yosys 0.9 in backports)
  40 .. note: debian 11 provides: python3 3.8.2, yosys 0.9
  41
  42 .. code-block:: shell
  43
  44    $ sudo apt-get install python3-pip yosys gtkwave
  45
  46 .. _Backports: https://wiki.debian.org/Backports
  47
  48
  49 ... on Ubuntu Linux
  50 -------------------
  51
  52 nMigen works on Ubuntu 20.04 LTS or newer.
  53
  54 .. note: ubuntu 20.04 provides: python3 3.8.2, yosys 0.9
  55
  56 .. code-block:: shell
  57
  58    $ sudo apt-get install python3-pip yosys gtkwave
  59
  60
  61 ... on macOS
  62 ------------
  63
  64 nMigen works best with Homebrew_. Run:
  65
  66 .. code-block:: shell
  67
  68    $ brew install python yosys gtkwave
  69
  70 .. _Homebrew: https://brew.sh
  71
  72
  73 ... on other platforms
  74 ----------------------
  75
  76 Refer to the `Yosys README`_ for detailed build instructions.
  77
  78 .. _Yosys README: https://github.com/YosysHQ/yosys/#setup
  79
  80
  81 Installing nMigen
  82 =================
  83
  84 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.
  85
  86
  87 Latest release
  88 --------------
  89
  90 To install the latest release of nMigen, run:
  91
  92 .. code-block:: shell
  93
  94    $ pip3 install --upgrade nmigen
  95
  96
  97 Development snapshot
  98 --------------------
  99
 100 To install a development snapshot of nMigen for the first time, run:
 101
 102 .. code-block:: shell
 103
 104    $ git clone https://github.com/nmigen/nmigen
 105    $ cd nmigen
 106    $ pip3 install --editable .
 107
 108 Any changes made to the ``nmigen`` directory will immediately affect any code that uses nMigen. To update the snapshot, run:
 109
 110 .. code-block:: shell
 111
 112    $ cd nmigen
 113    $ git pull --ff-only origin master
 114    $ pip3 install --editable .
 115
 116 It is important to run the ``pip3 install --editable .`` each time the development snapshot is updated in case package dependencies have been added or changed.
 117
 118
 119 Installing board definitions
 120 =============================
 121
 122 .. todo::
 123
 124          Explain how to install `<https://github.com/nmigen/nmigen-boards>`_.