New environment 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,31 +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
+```
+
+You will also need several Python packages.  It is best to do this within a Python virtual environment:
+
+```
+make env
+```
+
+Anytime you run the VTR flow or regressions tests (which use Python) you should activate the virtual environment in your terminal:
+
+```
+source .venv/bin/activate
 ```
 
 For documentation generation these additional packages are required:
 
 ```shell
 apt-get install \
 	doxygen \
-	python-sphinx \
-	python-sphinx-rtd-theme \
-	python-recommonmark
+	sphinx-common
+pip install -r doc/requirements.txt
 ```
 
 

CMakeLists.txt

@@ -446,3 +446,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,23 @@ 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
+
+This will create a Python virtual environment in ``.venv``; however, you won't need this environment until later in the tutorial when you reach the section on "Automatically Running the VTR Flow".
+
 Build VTR
 ---------
 
@@ -368,7 +385,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
 

install_apt_packages.sh

@@ -0,0 +1,13 @@
+sudo apt-get update
+
+sudo apt-get install -y \
+    make \
+    cmake \
+    build-essential \
+    pkg-config \
+    bison \
+    flex \
+    libgtk-3-dev \
+    libx11-dev \
+    python3-dev \
+    python3-venv