New environment setup instructions

Signed-off-by: Jeff Goeders <[email protected]>

Author: jgoeders

.gitignore

@@ -104,6 +104,7 @@ ODIN_II/usefull_tools/**/track_completed
 #Python
 #
 *.pyc
+/.venv
 
 #
 #Vim

BUILDING.md

@@ -56,33 +56,28 @@ For Docs generation you will need:
 The following should be enough to get the tools, VPR GUI and tests going on a modern Debian or Ubuntu system:
 
 ```shell
-apt-get install \
-	build-essential \
-	flex \
-	bison \
-	cmake \
-	fontconfig \
-	libcairo2-dev \
-	libfontconfig1-dev \
-	libx11-dev \
-	libxft-dev \
-	libgtk-3-dev \
-	perl \
-	liblist-moreutils-perl \
-	python \
-	time
+./install_apt_packages.sh
 ```
 
-For documentation generation these additional packages are required:
+You will also need several Python packages.  You can optionally install and activate a Python virtual environment so that you do not need to modify your system Python installation:
+```shell
+make env
+source .venv/bin/activate
+```
+
+Then to install the Python packages:
 
 ```shell
-apt-get install \
-	doxygen \
-	python-sphinx \
-	python-sphinx-rtd-theme \
-	python-recommonmark
+pip install -r requirements.txt
 ```
 
+*NOTE: Anytime you run the VTR flow or regressions tests (which use Python) you should activate the virtual environment in your terminal.*
+
+For documentation generation these additional Python packages are required:
+
+```shell
+pip install -r doc/requirements.txt
+```
 
 For development the following additional packages are useful:
 

CMakeLists.txt

@@ -451,3 +451,9 @@ list(APPEND DIRS_TO_FORMAT_PY "${CMAKE_CURRENT_SOURCE_DIR}/vpr")
 list(APPEND DIRS_TO_FORMAT_PY "${CMAKE_CURRENT_SOURCE_DIR}/vtr_flow")
 
 include(AutoPyFormat)
+
+
+#
+# Python Environment setup
+#
+include(PyEnv)

cmake/modules/PyEnv.cmake

@@ -0,0 +1,7 @@
+# Create a python virtual environment using venv and install all necessary packages
+# wheel should be installed before the requirements.txt list to prevent errors.
+add_custom_target(env
+    COMMAND python3 -m venv ../.venv
+    COMMAND . ../.venv/bin/activate && pip3 install wheel
+    COMMAND . ../.venv/bin/activate && pip3 install -r ../requirements.txt
+)

doc/src/quickstart/index.rst

@@ -14,6 +14,24 @@ The first step is to `download VTR <https://verilogtorouting.org/download/>`_ an
 
 .. note:: Developers planning to modify VTR should clone the `VTR git repository <https://github.com/verilog-to-routing/vtr-verilog-to-routing/>`_.
 
+
+Environment Setup
+-----------------
+VTR requires several system packages and Python packages to build and run the flow.  You can install the required system packages using the following command (this works on Ubuntu 18.04 and 20.04, but you may require different packages on other Linux distributions):
+
+.. code-block:: bash
+
+    > ./install_apt_packages.sh
+
+Then, to install the required Python packages within a new virtual environment:
+
+.. code-block:: bash
+
+    > make env
+    > source .venv/bin/activate
+    > pip install -r requirements.txt
+
+
 Build VTR
 ---------
 
@@ -368,7 +386,13 @@ Automatically Running the VTR Flow
 Running each stage of the flow manually is time consuming (and potentially error prone).
 For convenience, VTR provides a script (:ref:`run_vtr_flow`) which automates this process.
 
-Lets make a new directory to work in named ``blink_run_flow``:
+First, make sure you sure you have activated the Python virtual environment created at the beginning of this tutorial:
+
+.. code-block:: bash
+
+    > source $VTR_ROOT/.venv/bin/activate
+
+Next, make a new directory to work in named ``blink_run_flow``:
 
 .. code-block:: bash
 

doc/src/vtr/install_vtr.rst

@@ -14,7 +14,7 @@ Install VTR
 The complete VTR flow has been tested on 64-bit Linux systems.
 The flow should work in other platforms (32-bit Linux, Windows with cygwin) but this is untested.
 
-.. seealso:: More information about building VTR can be found in the :ref:`developer_guide`
+.. seealso:: Full information about building VTR, including setting up required system packages and Python packages, can be found in the :ref:`Building VTR guide <building_vtr>`.
 
 Please :ref:`let us know <contact>` your experience with building VTR so that we can improve the experience for others.
 

install_apt_packages.sh

@@ -0,0 +1,27 @@
+sudo apt-get update
+
+# Base packages to compile and run basic regression tests
+sudo apt-get install -y \
+    make \
+    cmake \
+    build-essential \
+    pkg-config \
+    bison \
+    flex \
+    python3-dev \
+    python3-venv
+    
+# Required for graphics
+sudo apt-get install -y \
+    libgtk-3-dev \
+    libx11-dev
+
+# Required for yosys front-end
+sudo apt-get install -y \
+    clang \
+    tcl-dev \
+    libreadline-dev
+
+# Required to build the documentation
+sudo apt-get install -y \
+    sphinx-common