README+Docs: Add virtual environments as recommended usage way

README.md

@@ -43,8 +43,7 @@ The following packages need to be installed for generating fabric HDL models and
 Install python dependencies
 
 ```
-pip3 install -r requirements.txt
-sudo apt-get install python3-tk
+$ sudo apt-get install python3-tk python3-virtualenv
 ```
 
 The following packages need to be installed for the CAD toolchain
@@ -56,12 +55,23 @@ A flow using VPR, the place and route tool from the [VTR project](https://github
 
 ## Getting started
 
-To set up FABulous:
+We recommend using Python virtual environments for the usage of FABulous.
+If you are not sure what this is and why you should use it, please read the [virtualenv documentation](https://virtualenv.pypa.io/en/latest/index.html).
 
 ```
-git clone https://github.com/FPGA-Research-Manchester/FABulous
-cd FABulous
-pip install -e .
+$ git clone https://github.com/FPGA-Research-Manchester/FABulous
+$ cd FABulous
+$ virtualenv venv
+$ source venv/bin/activate
+(venv)$ pip install -r requirements.txt
+(venv)$ pip install -e .
+```
+
+You can deactivate the virtual environment with the `deactivate` command.
+Please note, that you always have to enable the virtual environment to use FABulous:
+```
+$ cd <path to FABulous>
+$ source venv/bin/activate
 ```
 
 We have provided a Python Command Line Interface (CLI) as well as a project structure for easy access of the FABulous toolchain.
@@ -78,21 +88,22 @@ To exit the shell simply type `exit` and this will terminate the shell.
 A demo of the whole flow:
 
 ```
-FABulous -c demo # Create a demo project
-FABulous demo # Run Fabulous interactive shell for demo project
+(venv)$ FABulous -c demo # Create a demo project
+(venv)$ FABulous demo # Run Fabulous interactive shell for demo project
+
 # In the FABulous shell
-load_fabric
-run_FABulous_fabric
-run_FABulous_bitstream npnr ./user_design/sequential_16bit_en.v
-exit
+FABulous> load_fabric
+FABulous> run_FABulous_fabric
+FABulous> run_FABulous_bitstream npnr ./user_design/sequential_16bit_en.v
+FABulous> exit
 ```
 
 To run a simulation of a test bitstream on the design with Icarus Verilog:
 
 ```
-cd demo/Test
-./build_test_design.sh
-./run_simulation.sh
+(venv)$ cd demo/Test
+(venv)$ ./build_test_design.sh
+(venv)$ ./run_simulation.sh
 ```
 
 The tool also supports using TCL script to drive the build process. Assuming you have created a demo project using

docs/source/FPGA-to-bitstream/Bitstream generation.rst

@@ -35,7 +35,7 @@ With the FASM file generated by Nextpnr or VPR, you can run this command for bit
 
 .. code-block:: console
 
-        bit_gen -genBitstream <fasm_file> meta_data.txt <bitstream file>
+        (venv)$ bit_gen -genBitstream <fasm_file> meta_data.txt <bitstream file>
 
 +------------------+-----------------------------------------------------------------------+
 | <fasm_file>      | the FASM file generated by Nextpnr or VPR in previous compilation     |
@@ -50,7 +50,7 @@ The following command lowers the FASM representation of the placed and routed ``
 
 .. code-block:: console
 
-        bit_gen -genBitstream 16bit_sequential_en.fasm meta_data.txt 16bit_sequential_en_output.bin
+        (venv)$ bit_gen -genBitstream 16bit_sequential_en.fasm meta_data.txt 16bit_sequential_en_output.bin
 
 
 Changes in the primitives or adding new primitives

docs/source/Usage.rst

@@ -9,26 +9,45 @@ Prerequisites
 
 The following packages need to be installed for generating fabric HDLs
 
+:Python:
+
+Version >= 3.9
+
+:Dependencies:
+
+.. code-block:: console
+
+    $ sudo apt-get install python3-tk python3-virtualenv
+
 :FABulous repository:
 
 .. code-block:: console
 
-    git clone https://github.com/FPGA-Research-Manchester/FABulous
+    $ git clone https://github.com/FPGA-Research-Manchester/FABulous
 
-:Python:
- version >= 3.9
+:Virtual environment:
 
-:python dependencies:
+We recommend using python virtual environments for the usage of FABulous.
+If you are not sure what this is and why you should use it, please read the
+:`virtualenv documentation <https://virtualenv.pypa.io/en/latest/index.html>`_:
 
 .. code-block:: console
 
-    pip3 install -r requirements.txt
+   $ cd FABulous
+    $ virtualenv venv
+    $ source venv/bin/activate
+
+Now there is a ``(venv)`` at the beginning of your command prompt.
+You can deactivate the virtual environment with the ``deactivate`` command.
+Please note, that you always have to enable the virtual environment
+with ``source venv/bin/activate`` to use FABulous.
 
-This will also require to install `Tkinter` for the TCL facilities. To install `Tkinter` on Ubuntu, run:
+:Python dependencies:
 
 .. code-block:: console
 
-    sudo apt-get install python3-tk
+    (venv)$ pip install -r requirements.txt
+
 
 The following packages need to be installed for the CAD toolchain
 
@@ -41,22 +60,43 @@ The following packages need to be installed for the CAD toolchain
 Install FABulous with "editable" option:
 .. code-block:: console
 
-    pip3 install -e .
+    (venv)$ pip install -e .
 
 Building Fabric and Bitstream
 -----------------------------
 
 
 .. code-block:: console
 
-   FABulous -c <name_of_project>
-   FABulous <name_of_project>
+   (venv)$ FABulous -c <name_of_project>
+   (venv)$ FABulous <name_of_project>
+
    # inside the FABulous shell
-   load_fabric
-   run_FABulous_fabric
-   run_FABulous_bitstream npnr user_design/sequential_16bit_en.v
-
-
+   FABulous> load_fabric
+   FABulous> run_FABulous_fabric
+   FABulous> run_FABulous_bitstream npnr user_design/sequential_16bit_en.v
+
+.. note:
+  You will probably recieve a Warning for the FASM package like the following:
+
+  ```
+  RuntimeWarning: Unable to import fast Antlr4 parser implementation.
+  ImportError: cannot import name 'antlr_to_tuple' from partially initialized module 'fasm.parser' (most likely due to a circular import)
+
+  Falling back to the much slower pure Python textX based parser
+  implementation.
+
+  Getting the faster antlr parser can normally be done by installing the
+  required dependencies and then reinstalling the fasm package with:
+    pip uninstall
+    pip install -v fasm
+
+  ```
+
+  This usually happens when FASM can't find the Antlr4 package, but this is not mendatory for us.
+  If you still want to fix this issue, you have to install FASM in your virtual environment from source.
+  Please have a look at the :`FASM documentation <https://github.com/chipsalliance/fasm>`_ for more information.
+
 After a successful call with the command ``run_FABulous_fabric`` the RTL file of each of the tiles can be found in the ``Tile`` folder and the fabric RTL file can be found in the ``Fabric`` folder.
 
 After a successful call with the command ``run_FABulous_bitstream npnr user_design/sequential_16bit_en.v``.
@@ -78,15 +118,15 @@ To set up the Docker environment, navigate to the FABulous root directory and ru
 
 .. code-block:: console
 
-     docker build -t fabulous .
+     $ docker build -t fabulous .
 
 :Running the Docker environment:
 
 To run the Docker environment, stay in the FABulous root directory (this is vital as the command mounts the current directory as the container's filesystem) and run:
 
 .. code-block:: console
 
-     docker run -it -v $PWD:/workspace fabulous
+     $ docker run -it -v $PWD:/workspace fabulous
 
 This will bring up an interactive bash environment within the Docker container, within which you can use FABulous as if hosted natively on your machine. When you are finished using FABulous, simply type ``exit``, and all changes made will have been made to your copy of the FABulous repository.
 

docs/source/references/code_generator.rst

@@ -1,5 +1,5 @@
 code_generator.py
 =================
 
-.. automodule:: fabric_generator.code_generator
-    :members:
+.. automodule:: FABulous.fabric_generator.code_generator
+    :members:

docs/source/references/fabric.rst

@@ -1,5 +1,5 @@
 fabric.py
 =========
 
-.. automodule:: fabric_generator.fabric
-   :members:
+.. automodule:: FABulous.fabric_generator.fabric
+   :members:

docs/source/references/fabric_gen.rst

@@ -1,5 +1,5 @@
 fabric_gen.py
 =============
 
-.. automodule:: fabric_generator.fabric_gen
-   :members:
+.. automodule:: FABulous.fabric_generator.fabric_gen
+   :members:

docs/source/references/file_parser.rst

@@ -1,5 +1,5 @@
 file_parser.py
 ==============
 
-.. automodule:: fabric_generator.file_parser
-   :members:
+.. automodule:: FABulous.fabric_generator.file_parser
+   :members:

docs/source/references/model_gen_npnr.rst

@@ -1,5 +1,5 @@
 model_generation_npnr.py
 ========================
 
-.. automodule:: fabric_generator.model_generation_npnr
-    :members:
+.. automodule:: FABulous.fabric_generator.model_generation_npnr
+    :members:

docs/source/references/model_gen_vpr.rst

@@ -1,5 +1,5 @@
 model_generation_vpr.py
 =======================
 
-.. automodule:: fabric_generator.model_generation_vpr
-    :members:
+.. automodule:: FABulous.fabric_generator.model_generation_vpr
+    :members:

docs/source/simulation/simulation.rst

@@ -5,18 +5,18 @@ The following series of commands can be used to easily run a simulation with a t
 
 .. code-block:: console
 
-        cd demo/Test
-        ./build_test_design.sh
-        ./run_simulation.sh
+        (venv)$ cd demo/Test
+        (venv)$ ./build_test_design.sh
+        (venv)$ ./run_simulation.sh
 
 FABulous comes with 3 different simulation methods _`configuration module`,
 
 #. Serial (Mode 0)
 
-   Send configuration in through UART 
+   Send configuration in through UART
 
 #. Parallel (Mode 1) - default in the testbench
-   
+
    Use parallel configuration port
 
 #. Bitbang configuration port (To be supported in the testbench)
@@ -34,7 +34,7 @@ FABulous comes with 3 different simulation methods _`configuration module`,
 
    The next figure shows the enable generation (and input sampling) for generating the enable signals for 
 
-   * the control shift register and 
+   * the control shift register and
    * the data shift register.
 
    .. figure:: ../figs/bitbang2.*

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
+requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2"]
 build-backend = "setuptools.build_meta"
 
 [project]