openflow: add configure.py

A class, and a helper that uses it, to configure the OCI engine, containers
and tools names.

Author: rodrigomelo9

.github/workflows/test.yml

@@ -27,4 +27,6 @@ jobs:
         pylint -s n openflow
         git diff --check --cached
     - name: Test
-      run: pytest test
+      run: |
+        pytest test
+        make -C examples/configure

Makefile

@@ -1,10 +1,11 @@
 #!/usr/bin/make
 
 check: 
-	pycodestyle openflow
-	pylint -s n openflow
+	pycodestyle openflow examples
+	pylint -s n openflow examples
 	git diff --check --cached
 	pytest test
+	make -C examples/configure
 
 clean:
 	py3clean .

README.md

@@ -13,3 +13,33 @@ Currently, it is based on `GHDL`, `Yosys`, `ghdl-yosys-plugin`, `nextpnr`,
 
 > **NOTE:** it started as part of [PyFPGA](https://github.com/PyFPGA/pyfpga)
 > and will be used to solves the `openflow` **tool**.
+
+## Installation
+
+Openflow requires Python `>=3.6`. For now, it's only available as a git repository
+hosted on GitHub. It can be installed with pip:
+
+```
+pip install 'git+https://github.com/PyFPGA/pyfpga#egg=pyfpga'
+```
+
+> On GNU/Linux, installing pip packages on the system requires `sudo`.
+> Alternatively, use `--local` for installing PyFPGA in your HOME.
+
+You can get a copy of the repository either through git clone or downloading a
+tarball/zipfile:
+
+```
+git clone https://github.com/PyFPGA/openflow.git
+cd openflow
+```
+
+Then, use pip from the root of the repo:
+
+```
+pip install -e .
+```
+
+> With `-e` (`--editable`) your application is installed into site-packages via
+> a kind of symlink. That allows pulling changes through git or changing the
+> branch, without the need to reinstall the package.

examples/configure/Makefile

@@ -0,0 +1,8 @@
+EXAMPLES=$(wildcard *.py)
+
+.PHONY: $(EXAMPLES)
+
+all: $(EXAMPLES)
+
+$(EXAMPLES):
+	python3 $@

examples/configure/defaults.py

@@ -0,0 +1,8 @@
+"""Example about default values."""
+
+from openflow.configure import ConfigureTools
+
+cfg = ConfigureTools()
+
+for tool in cfg.get_tools():
+    print(cfg.get_command(tool))

examples/configure/file.py

@@ -0,0 +1,8 @@
+"""Example about to specify a file."""
+
+from openflow.configure import ConfigureTools
+
+cfg = ConfigureTools('file.yml')
+
+for tool in cfg.get_tools():
+    print(cfg.get_command(tool))

examples/configure/file.yml

@@ -0,0 +1,15 @@
+engine:
+  name: example
+  volumes:
+    - "path1:path2"
+    - "path3:path4"
+  work: .
+  options: global-option
+tools:
+  example1:
+    name: alt-example1
+    container: hdlc/example1
+  example2:
+    name: alt-example2
+    container: hdlc/example2
+    options: local-option

examples/configure/methods.py

@@ -0,0 +1,36 @@
+"""Example about to use the different methods."""
+
+from openflow.configure import ConfigureTools
+
+cfg = ConfigureTools()
+
+print('* Defaults for GHDL:')
+print(cfg.get_command('ghdl'))
+
+print('* Setting a different engine:')
+cfg.set_engine('podman')
+print(cfg.get_command('ghdl'))
+
+print('* Setting different volumes:')
+cfg.set_volumes(['v1:v1', 'v2:v2'])
+print(cfg.get_command('ghdl'))
+
+print('* Setting a different work:')
+cfg.set_work('/tmp')
+print(cfg.get_command('ghdl'))
+
+print('* Setting a global options:')
+cfg.set_global_options('--global option')
+print(cfg.get_command('ghdl'))
+
+print('* Setting a new container:')
+cfg.set_container('ghdl', 'alt-ghdl-container')
+print(cfg.get_command('ghdl'))
+
+print('* Setting a new tool name:')
+cfg.set_name('ghdl', 'alt-ghdl-name')
+print(cfg.get_command('ghdl'))
+
+print('* Setting a local options:')
+cfg.set_local_options('ghdl', '--local option')
+print(cfg.get_command('ghdl'))

openflow/__init__.py

@@ -3,3 +3,4 @@
 __version__ = '0.1.0'
 
 from openflow.openflow import Openflow
+from openflow.configure import ConfigureTools

openflow/configure.py

@@ -0,0 +1,105 @@
+#
+# Copyright (C) 2020-2021 Rodrigo A. Melo
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+"""openflow.configure
+
+A Class to configure the OCI engine, the containers and the name of the
+underlying FOSS tools.
+"""
+
+
+import os
+from yaml import safe_load, dump
+
+
+class ConfigureTools:
+    """Configure Tools."""
+
+    def __init__(self, filename='.openflow.yml'):
+        """Class constructor."""
+        userfile = os.getenv('OPENFLOW_FILE')
+        homefile = os.path.join(os.path.expanduser('~'), filename)
+        projfile = os.path.join(os.path.dirname(__file__), 'configure.yml')
+        if userfile is not None and os.path.exists(userfile):
+            filepath = userfile
+        elif os.path.exists(filename):
+            filepath = filename
+        elif os.path.exists(homefile):
+            filepath = homefile
+        else:
+            filepath = projfile
+        self.configs = {}
+        with open(filepath, 'r') as file:
+            self.configs = safe_load(file)
+
+    def get_command(self, tool):
+        """Get the command-line needed to run a tool."""
+        engine = self.configs['engine']['name']
+        name = self.configs['tools'][tool]['name']
+        if engine is not None and os.getenv('OPENFLOW_OFF') is None:
+            oci = [
+              engine,
+              'run --rm',
+              '-v ' + (' -v ').join(self.configs['engine']['volumes']),
+              '-w ' + self.configs['engine']['work'],
+              self.configs['engine'].get('options', None),
+              self.configs['tools'][tool].get('options', None),
+              self.configs['tools'][tool]['container'],
+              name
+            ]
+            return ' '.join(list(filter(None, oci)))
+        return name
+
+    def get_tools(self):
+        """Returns the list of configured tools."""
+        return sorted(list(self.configs['tools'].keys()))
+
+    def dump(self):
+        """Dumps the configuration in YAML format (debug purpouses)."""
+        return dump(self.configs)
+
+    def set_engine(self, engine):
+        """Set the OCI engine."""
+        self.configs['engine']['name'] = engine
+
+    def unset_engine(self):
+        """Unset the OCI engine. """
+        self.configs['engine']['name'] = None
+
+    def set_volumes(self, volumes):
+        """Set the volumes of the OCI engine."""
+        self.configs['engine']['volumes'] = volumes
+
+    def set_work(self, work):
+        """Set the working directory inside the container."""
+        self.configs['engine']['work'] = work
+
+    def set_global_options(self, options):
+        """Set options shared by all the containers."""
+        self.configs['engine']['options'] = options
+
+    def set_container(self, tool, container):
+        """Set the container of the specified tool."""
+        self.configs['tools'][tool]['container'] = container
+
+    def set_name(self, tool, name):
+        """Set the name of the specified tool."""
+        self.configs['tools'][tool]['name'] = name
+
+    def set_local_options(self, tool, options):
+        """Set options for a particular container."""
+        self.configs['tools'][tool]['options'] = options