floogen: Add support for installation within python virtual environment

CHANGELOG.md

@@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added support for single-AXI configuration networks.
 - Support for negative increments when specifying a `src_range` or `dst_range` in the `connections` schema.
 - Add support for multiple non-contiguous address ranges for endpoints.
+- Support for 'floogen' installation in a Python virtual environment using `poetry`.
 
 ### Changed
 

README.md

@@ -226,6 +226,10 @@ The following example shows the configuration for a simple mesh topology with 4x
 
 ### Usage
 
+`floogen` can be installed and run _globally_ with `pip`, or _locally_ within a Python virtual environment.
+
+##### Global installation
+
 To install `floogen` run the following command:
 
 ```sh
@@ -238,6 +242,30 @@ which allows you to use `floogen` with the following command:
 floogen -c <config_file> -o <output_dir>
 ```
 
+##### Local virtual environment
+
+To build a local virtual environment we exploit `poetry`, that can be installed as follows:
+
+```sh
+pip install pipx==1.7.1
+pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
+```
+
+Note that the original setup leverages `Python 3.10` and `pipx 1.7.1`.
+Moreover, we currently install the git development version of `poetry`, as [PEP 621 support has not been released yet](https://github.com/python-poetry/poetry/commit/119a3d761782e6ef1e6389a66d6d666906cd6e67) (see the [documentation](docs/floogen.md) for more details).
+
+Then, to install `floogen` run the following script:
+
+```sh
+source floogen/floo_gen_venv.sh
+```
+
+Once the virtual environment is activated, `floogen` is executed with the following command:
+
+```sh
+floogen -c <config_file> -o <output_dir>
+```
+
 ### Configuration
 
 The example configuration above shows the basic structure of a configuration file. A more detailed description of the configuration file can be found in the [documentation](docs/floogen.md).

docs/floogen.md

@@ -136,7 +136,11 @@ In case of tree routers, you can also specify the following fields:
 
 ## Running floogen
 
-`floogen` is a Python package that can be installed with `pip`:
+`floogen` is a Python package that can be installed and run _globally_ with `pip`, or _locally_ within a Python virtual environment.
+
+### Global installation
+
+To install `floogen` with `pip`:
 
 ```bash
 pip install .
@@ -150,6 +154,33 @@ floogen -c <config_file> -o <output_dir>
 
 where `<config_file>` is the configuration file and `<output_dir>` is the output directory where the generated RTL code will be placed.
 
+### Local virtual environment
+
+To build a local virtual environment we exploit `poetry`.
+However, its most recent `pip` release (1.8.3) does not support **PEP-621**, as the tool is older than that.
+Users would thus require to adhere to `poetry`-specific sections, when writing their `pyproject.toml`.
+As [support for PEP 621 was recently merged to `main`](https://github.com/python-poetry/poetry/commit/119a3d761782e6ef1e6389a66d6d666906cd6e67), it will be hopefully released soon.
+
+We hence suggest installing the git development version of `poetry`:
+
+```sh
+pip install pipx==1.7.1
+pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
+```
+
+Note that the original setup leverages `Python 3.10` and `pipx 1.7.1`.
+
+Then, to install `floogen` run the following script:
+
+```sh
+source floogen/floo_gen_venv.sh
+```
+
+Once the virtual environment is activated, `floogen` is executed with the following command:
+
+```sh
+floogen -c <config_file> -o <output_dir>
+```
 
 ## Additonal arguments
 

floogen/floo_gen_venv.sh

@@ -0,0 +1,56 @@
+# Copyright 2023 University of Modena and Reggio Emilia.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Author: Gianluca Bellocchi <gianluca.bellocchi@unimore.it>
+
+#!/bin/bash
+
+FLOOGEN_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+FLOOGEN_VENV_NAME=floogen # should match name specified in pyproject.toml
+
+POETRY='poetry@main' # temporary
+
+ENV_LIST=$($POETRY env list)
+ENV_PATH=$($POETRY env info --path)
+
+# check if previous floogen virtual environment exists
+echo "$ENV_LIST" | grep "venv" &> /dev/null
+if [ $? == 0 ]; then
+	echo "Old $FLOOGEN_VENV_NAME virtual environment exists"
+    echo "$ENV_PATH"
+	echo "Do you want to proceed and install $FLOOGEN_VENV_NAME again?"
+
+	select yn in "yes" "no"; do
+		case $yn in
+			yes ) 	break;;
+			no ) 	exit;;
+		esac
+	done
+fi
+
+# check if other floogen virtual environments exist
+echo "$ENV_LIST" | grep $FLOOGEN_VENV_NAME &> /dev/null
+if [ $? == 0 ]; then
+	echo "Old $FLOOGEN_VENV_NAME virtual environment exists"
+    echo "$ENV_PATH"
+	echo "Do you want to proceed and install $FLOOGEN_VENV_NAME again?"
+
+	select yn in "yes" "no"; do
+		case $yn in
+			yes ) 	break;;
+			no ) 	exit;;
+		esac
+	done
+fi
+
+# install environment (does not update lock if it exists)
+echo "Installing $FLOOGEN_VENV_NAME virtual environment"
+$POETRY install --sync
+
+# to activate environment
+if [[ "$VIRTUAL_ENV" == "" ]]
+then
+	echo "Activating $FLOOGEN_VENV_NAME virtual environment"
+    $POETRY shell
+fi