Update installation instructions

source/SpinalHDL/Getting Started/Install and setup.rst

@@ -3,39 +3,85 @@
 Install and setup
 =================
 
-Spinal is a Scala library so it requires setting up a Scala environment; there
-are many ways to do so. Also, it generates VHDL, Verilog or SystemVerilog, which
-can be used by many different tools. This section describes the supported way to
-install a *SpinalHDL description to Simulation* flow, but there can be many
-variations.
+Spinal is a Scala library (a programming language using the Java VM) so it
+requires setting up a Scala environment; there are many ways to do so.
+Also, it generates VHDL, Verilog or SystemVerilog, which can be used by many
+different tools. This section describes the supported way to install a
+*SpinalHDL description to Simulation* flow, but there can be many variations.
 
-
-Mandatory requirements
-----------------------
+Required/Recommended tools
+--------------------------
 
 Before you download the SpinalHDL tools, you need to install a Scala environment:
 
 * `Java JDK <https://www.oracle.com/java/technologies/downloads/>`_, a Java
   environment
+* `Scala 2 <https://www.scala-lang.org/>`_, compiler and library
 * `SBT <https://www.scala-sbt.org/download.html>`_, a Scala build tool
 
 These tools enable to use Spinal; but without any other tools, it is limited to
-code generation.
+HDL code generation.
+
+To enable more features we recommend:
+
+* An IDE (for instance the currently recommended `IntelliJ <https://www.jetbrains.com/idea/>`_
+  with its Scala plugin or `VSCodium <https://vscodium.com/>`_ with Metals extension) to
+  get features such as:
+
+    * Code suggestions / completion
+    * Automatic build with syntax errors right in the code
+    * Generate code with a single click
+    * Run simulation / tests with a single click (if a supported simulator is
+      set up)
+
+* A supported simulator like `Verilator <https://www.veripool.org/verilator/>`_
+  to test the design right from SpinalHDL.
+* `Gtkwave <https://gtkwave.sourceforge.net/>`_ to view the waves generated by
+  Verilator during simulation.
+* `Git <https://git-scm.com/>`_ for version control system
+* A C++ toolchain, needed for simulating with Verilator
+* A linux shell, needed for simulating with Verilator
 
 Linux Installation
-----------------------
+------------------
 
-For instance, to install them on the Debian distribution:
+At time of writing the recommended way of installing Scala and SBT is via `Coursier <https://get-coursier.io/docs/cli-installation>`_.
+Coursier is able to in addition to the scala tools install a Java JDK to use, in the
+example below we install Java from the package manager. We recommend to install JDK 17 (LTS)
+because of compatibility with the used Scala version.
+
+For Debian or Ubuntu we run:
 
 .. code-block:: sh
 
-   sudo apt-get install openjdk-8-jdk
-   sudo apt-get install scala
-   echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
-   echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
-   curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
    sudo apt-get update
-   sudo apt-get install sbt
+   sudo apt-get install openjdk-17-jdk-headless curl git
+   curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz" | gzip -d > cs
+   chmod +x cs
+   # should find the just installed jdk, agree to cs' questions for adding to your PATH
+   ./cs setup
+   source ~/.profile
+
+If you want to install the tools for simulation and/or formal proofs, we recommend `oss-cad-suite <https://github.com/YosysHQ/oss-cad-suite-build>`_.
+It contains a waveform viewer (gtkWave), verilog simulators (verilator and iverilog), VHDL simulator (GHDL) and other tools.
+In case you want to build the tools yourself have a look at the legacy simulation tool :ref:`installation instructions <sim backend install>`.
+
+We first install the needed C++ toolchain and download oss-cad-suite. To use it we must load the oss-cad-suite
+environment for each shell we want to use it in. Note that oss-cad-suite contains a Python 3 interpreter that
+may interfere with the system Python installation if loaded permanently.
+
+Go to the oss-cad-suite `release page <https://github.com/YosysHQ/oss-cad-suite-build/releases/latest>`_ to get the
+download link for the latest version. You can download/extract oss-cad-suite to a folder of
+your choice.
+
+.. code-block:: sh
+
+   sudo apt-get install make gcc g++ zlib1g-dev
+   curl -fLO <download link>
+   tar xzf <file that you downloaded>
+
+To use oss-cad-suite in a shell you need to load it's environment, e.g. via ``souce <path to oss-cad-suite>/environment``.
+
 
 Mac OS X Installation
 ----------------------
@@ -67,64 +113,75 @@ Jenv added these lines to my .bash_profile
 
 If this works for you, please let us know.  If this does not work for you, you can read the github issue about Mac o SX installation here. 
 https://github.com/SpinalHDL/SpinalHDL/issues/1216
-
-Installing SBT in an internet-free environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to install the tools for simulation and/or formal proofs, we recommend `oss-cad-suite <https://github.com/YosysHQ/oss-cad-suite-build>`_.
+
+Windows installation
+--------------------
 
 .. note::
-   If you do not need this, you can skip to the next section:
-   :ref:`recommended`.
+   A simpler option on Windows is to use WSL. If you want to use WSL, install `it <https://learn.microsoft.com/en-us/windows/wsl/install>`_, a distribution of your choice and
+   follow the Linux installation instructions. Data in your WSL instance can be accessed from windows under ``\\wsl$``
 
-Normally, SBT uses online repositories to download and cache your projects
-dependencies. This cache is located in several folders:
+At time of writing the recommended way of installing Scala and SBT is via `Coursier <https://get-coursier.io/docs/cli-installation>`_.
+Coursier is able to in addition to the scala tools install a Java JDK to use, in the
+example below we install Java manually. We recommend to install JDK 17 (LTS) because of
+compatibility with the used Scala version.
 
-* ``~/.sbt``
-* ``~/.cache/JNA``
-* ``~/.cache/coursier``
+First download and install `Adoptium JDK 17 <https://adoptium.net/temurin/releases/?os=windows&version=17>`_.
+Download, unzip and run the `Coursier installer <https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip>`_,
+when asked agree to an update of your ``PATH`` variable. Reboot to force an update of ``PATH``.
 
-To set up an internet-free environment, you can:
+If you want to install the tools for simulation and/or formal proofs, we recommend `oss-cad-suite <https://github.com/YosysHQ/oss-cad-suite-build>`_.
+It contains a waveform viewer (gtkWave), verilog simulators (verilator and iverilog), VHDL simulator (GHDL) and other tools.
+Download the oss-cad-suite installer from the `release page <https://github.com/YosysHQ/oss-cad-suite-build/releases>`
+In case you want to build the tools yourself have a look at the legacy simulation tool :ref:`installation instructions <sim backend install>`.
 
-#. Set up an environment with internet
-#. Launch a Spinal command (see :ref:`Using SBT`) to fetch dependencies (for
-   instance using the `getting started
-   <https://github.com/SpinalHDL/SpinalTemplateSbt>`_ repository)
-#. Copy the caches to the internet-free environment.
+To get the necessary compiler/shell for verilator simulation we recommend `MSYS2 <https://www.msys2.org>`_.
+If you already have a working gcc/make/shell available from another tool (e.g. chocolatey, scoop, etc.) this should not be needed.
+Download the latest installer and install MSYS2 with default settings. You should get a MSYS2 terminal at the end of the installation, there run:
 
-.. note::
-   You can get a portable SBT setup here: https://www.scala-sbt.org/download.html
+.. code-block:: sh
 
-.. note::
-   You might be interested in `SpinalNomad <https://github.com/SpinalHDL/SpinalNomad/tree/main/sbt>`_.
+   pacman -Syuu
+   # repoen 'MSYS2 UCRT64' from start menu if requested
+   pacman -Syuu
+   pacman -S --needed base-devel mingw-w64-x86_64-toolchain git
+   # agree to install all packages
 
+We need to make the MSYS2 applications accessible from 'normal' Windows, so add ``bin`` and ``usr\bin`` of MSYS2
+into your windows ``PATH`` (ie : ``C:\msys64\usr\bin;C:\msys64\mingw64\bin``). Restart to ensure the new ``PATH`` is set.
 
-.. _recommended:
+To use oss-cad-suite it's tools need to be in the ``PATH``, one way to do that is to open a shell using ``start.bat``
+in the oss-cad-suite installation.
 
-Recommended requirements
-------------------------
+Installing SBT in an internet-free Linux environment
+----------------------------------------------------
 
-To enable more features:
+.. note::
+   If you are not using an air-gapped environment we recommend to
+   go with the normal linux installation. (which is a subset of the
+   installation for an air-gapped environment)
 
-* An IDE (for instance `IntelliJ <https://www.jetbrains.com/idea/>`_ with its
-  Scala plugin or `VSCodium <https://vscodium.com/>`_ with Metals extension) to
-  get features such as:
+Normally, SBT uses online repositories to download and cache your projects
+dependencies. This cache is located in several folders:
 
-    * Code suggestions / completion
-    * Automatic build with syntax errors right in the code
-    * Generate code with a single click
-    * Run simulation / tests with a single click (if a supported simulator is
-      set up)
+* ``~/.sbt``
+* ``~/.cache/JNA``
+* ``~/.cache/coursier``
 
-* A supported simulator like `Verilator <https://www.veripool.org/verilator/>`_
-  to test the design right from SpinalHDL.
-* `Gtkwave <https://gtkwave.sourceforge.net/>`_ to view the waves generated by
-  Verilator during simulation.
-* `Git <https://git-scm.com/>`_ for version control system
+To set up an internet-free environment, you can:
 
+#. Set up an environment with internet (see above)
+#. Launch a Spinal command (see :ref:`Using SBT`) to fetch dependencies (for
+   instance using the `getting started
+   <https://github.com/SpinalHDL/SpinalTemplateSbt>`_ repository)
+#. Copy the caches to the internet-free environment.
 
 .. _template:
 
-Create a SpinalHDL project
---------------------------
+Create a first SpinalHDL project
+================================
 
 We have prepared a ready-to-go project for you the: `getting started <https://github.com/SpinalHDL/SpinalTemplateSbt>`_ repository.
 

source/SpinalHDL/Simulation/index.rst

@@ -2,7 +2,11 @@
 Simulation
 ==========
 
-As always, you can use your standard simulation tools to simulate the VHDL/Verilog generated by SpinalHDL. However, since SpinalHDL 1.0.0, the language integrates an API to write testbenches and test your hardware directly in Scala. This API provides the capabilities to read and write the DUT signals, fork and join simulation processes, sleep and wait until a given condition is reached. Therefore, using SpinalHDL's simulation API, it is easy to integrate testbenches with the most common Scala unit-test frameworks.
+As always, you can use your standard simulation tools to simulate the VHDL/Verilog generated by SpinalHDL.
+However, since SpinalHDL 1.0.0, the language integrates an API to write testbenches and test your hardware
+directly in Scala. This API provides the capabilities to read and write the DUT signals, fork and join
+simulation processes, sleep and wait until a given condition is reached. Therefore, using SpinalHDL's
+simulation API, it is easy to integrate testbenches with the most common Scala unit-test frameworks.
 
 To be able to simulate user-defined components, SpinalHDL uses external HDL simulators as backend. Currently, four simulators are supported:
 
@@ -12,7 +16,7 @@ To be able to simulate user-defined components, SpinalHDL uses external HDL simu
 - `VCS <https://www.synopsys.com/verification/simulation/vcs.html>`_ **(experimental, since SpinalHDL 1.7.0)**
 - `XSim <https://www.google.com/search?q=site%3Axilinx.com+xsim>`_ **(experimental, since SpinalHDL 1.7.0)**
 
-With external HDL simulators it is possible to directly test the generated HDL sources without increasing the SpinalHDL codebase complexity. 
+With external HDL simulators it is possible to directly test the generated HDL sources without increasing the SpinalHDL codebase complexity.
 
 .. toctree::
    :hidden:

source/SpinalHDL/Simulation/install/GHDL.rst

@@ -2,6 +2,10 @@
 Setup and installation of GHDL
 ==============================
 
+.. note::
+   If you installed the recommended oss-cad-suite during SpinalHDL :ref:`setup <Install>` you
+   can skip the instructions below - but you need to activate the oss-cad-suite environment.
+
 Even though GHDL is generally available in linux distributions package system, SpinalHDL depends on bugfixes of GHDL codebase that were added after the release of GHDL v0.37. Therefore it is reccomended to install GHDL from source.
 The C++ library boost-interprocess, which is contained in the libboost-dev package in debian-like distributions, has to be installed too. boost-interprocess is required to generate the shared memory communication interface. 
 

source/SpinalHDL/Simulation/install/Icarus Verilog.rst

@@ -2,6 +2,10 @@
 Setup and installation of Icarus Verilog
 ========================================
 
+.. note::
+   If you installed the recommended oss-cad-suite during SpinalHDL :ref:`setup <Install>` you
+   can skip the instructions below - but you need to activate the oss-cad-suite environment.
+
 In most recent linux distributions, a recent version of Icarus Verilog is generally available through the package system.
 The C++ library boost-interprocess, which is contained in the libboost-dev package in debian-like distributions, has to be installed too. boost-interprocess is required to generate the shared memory communication interface. 
 

source/SpinalHDL/Simulation/install/Verilator.rst

@@ -2,6 +2,9 @@
 Setup and installation of Verilator
 ===================================
 
+.. note::
+   If you installed the recommended oss-cad-suite during SpinalHDL :ref:`setup <Install>` you
+   can skip the instructions below - but you need to activate the oss-cad-suite environment.
 
 SpinalSim + Verilator is supported on both Linux and Windows platforms.
 
@@ -57,7 +60,7 @@ In order to get SpinalSim + Verilator working on Windows, you have to do the fol
 * Install `MSYS2 <https://www.msys2.org/>`_
 * Via MSYS2 get gcc/g++/verilator (for Verilator you can compile it from the sources)
 * Add ``bin`` and ``usr\bin`` of MSYS2 into your windows ``PATH`` (ie : ``C:\msys64\usr\bin;C:\msys64\mingw64\bin``)
-* Check that the JAVA_HOME environnement variable point to the JDK installation folder (ie : ``C:\Program Files\Java\jdk-13.0.2``)
+* Check that the JAVA_HOME environment variable points to the JDK installation folder (i.e.: ``C:\Program Files\Java\jdk-13.0.2``)
 
 Then you should be able to run SpinalSim + Verilator from your Scala project without having to use MSYS2 anymore.
 

source/SpinalHDL/Simulation/install/index.rst

@@ -1,8 +1,5 @@
-Installation instructions
-=========================
-
-Scala
-^^^^^
+SBT setup for simulation
+========================
 
 To enable SpinalSim, the following lines have to be added in your build.sbt file :
 
@@ -17,6 +14,8 @@ Also the following imports have to be added in testbenches sources :
    import spinal.core._
    import spinal.core.sim._
 
+.. _sim backend install:
+
 Backend-dependent installation instructions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^