Print version info in all generated files

abs-tudelft · Aug 30, 2019 · 0720f40 · 0720f40
1 parent f9fdffa
commit 0720f40
Show file tree

Hide file tree

Showing 9 changed files with 82 additions and 14 deletions.
diff --git a/tests/testbench/test.py b/tests/testbench/test.py
@@ -13,7 +13,8 @@ class TestTestbench(TestCase):
     def test_basic(self):
         """testbench self-test: basic functionality"""
         testbench = Testbench()
-        testbench.add_include(os.path.dirname(__file__) + '/../../vhdmmio/vhdl/vhdmmio_pkg.vhd')
+        testbench.add_include(os.path.dirname(__file__)
+                              + '/../../vhdmmio/vhdl/vhdmmio_pkg.template.vhd')
         test_in = testbench.add_input('test_in', 8)
         test_out = testbench.add_output('test_out', 8)
         testbench.add_body('test_out <= std_logic_vector(unsigned(test_in) + 1);')
@@ -33,7 +34,8 @@ def test_basic(self):
     def test_streams(self):
         """testbench self-test: streams"""
         testbench = Testbench()
-        testbench.add_include(os.path.dirname(__file__) + '/../../vhdmmio/vhdl/vhdmmio_pkg.vhd')
+        testbench.add_include(os.path.dirname(__file__)
+                              + '/../../vhdmmio/vhdl/vhdmmio_pkg.template.vhd')
         test_source = StreamSourceMock(
             testbench.add_input('source_valid'),
             testbench.add_output('source_ready'),
@@ -59,7 +61,8 @@ def handler(data):
     def test_axi(self):
         """testbench self-test: AXI4-lite"""
         testbench = Testbench()
-        testbench.add_include(os.path.dirname(__file__) + '/../../vhdmmio/vhdl/vhdmmio_pkg.vhd')
+        testbench.add_include(os.path.dirname(__file__)
+                              + '/../../vhdmmio/vhdl/vhdmmio_pkg.template.vhd')
         master = AXI4LMasterMock(testbench, 'master')
         slave = AXI4LSlaveMock(testbench, 'slave')
         testbench.add_body('slave_req <= master_req;')

diff --git a/vhdmmio/html/__init__.py b/vhdmmio/html/__init__.py
@@ -4,6 +4,7 @@
 from os.path import join as pjoin
 import shutil
 from markdown2 import Markdown
+import vhdmmio
 from ..core.address import AddressSignalMap
 from ..template import TemplateEngine, annotate_block
 
@@ -521,10 +522,11 @@ def generate(self, output_dir):
         tple = TemplateEngine()
         for regfile in self._regfiles:
             tple.append_block('BODY', self._regfile_to_html(regfile))
-        tple['title'] = 'TODO'
+        tple['title'] = 'Register file documentation'
+        tple['version'] = vhdmmio.__version__
         tple.apply_file_to_file(
             pjoin(_MODULE_DIR, 'base.template.html'),
             pjoin(output_dir, 'index.html'))
-        shutil.copyfile(
-            pjoin(_MODULE_DIR, 'style.css'),
+        tple.apply_file_to_file(
+            pjoin(_MODULE_DIR, 'style.template.css'),
             pjoin(output_dir, 'style.css'))
diff --git a/vhdmmio/html/base.template.html b/vhdmmio/html/base.template.html
@@ -4,12 +4,18 @@
     <meta charset="UTF-8" />
     <title>$title$</title>
     <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
+    <meta name="generator" content="vhdmmio $version$" />
     <meta name="description" content="" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="theme-color" content="#ffffff" />
     <link rel="stylesheet" href="style.css" />
   </head>
   <body>
 $   BODY
+    <div class="version">
+      Generated using
+      <a href="https://github.com/abs-tudelft/vhdmmio" target="_blank">vhdMMIO</a>
+      $version$
+    </div>
   </body>
 </html>
diff --git a/vhdmmio/html/style.css → vhdmmio/html/style.template.css b/vhdmmio/html/style.css → vhdmmio/html/style.template.css
@@ -1,3 +1,4 @@
+/* Generated using vhdMMIO $version$ (https://github.com/abs-tudelft/vhdmmio) */
 
 body {
     font-family: sans-serif;
@@ -38,6 +39,18 @@ emph {
     color: rgba(0, 0, 0, 0.5);
 }
 
+div.version {
+    padding: 5px 10px;
+    font-style: italic;
+    font-size: 0.9em;
+    color: #999;
+    text-align: right;
+}
+
+div.version a {
+    color: #999;
+}
+
 /*****************************************************************************/
 /* Markdown-generated/default tables                                         */
 /*****************************************************************************/

diff --git a/vhdmmio/version.py b/vhdmmio/version.py
@@ -1,4 +1,40 @@
 """Version metadata file. This file is overridden by setuptools with the
 actual version when the module is "built"."""
 
-__version__ = 'not-installed'
+import os
+from subprocess import Popen, PIPE
+
+
+def _run_cmd(*args):
+    """Runs a command using subprocess, returning a two-tuple consisting of
+    the return code and a binary string containing the data written to
+    stdout."""
+    proc = Popen(
+        args, stdin=PIPE, stdout=PIPE, stderr=PIPE,
+        cwd=os.path.dirname(__file__))
+    output, _ = proc.communicate()
+    code = proc.returncode
+    return code, output
+
+
+def _get_version():
+    """Attempts to get vhdmmio's version at runtime using `git`."""
+    try:
+        code, output = _run_cmd('git', 'describe', '--tags')
+        if code:
+            return 'unknown'
+        output = output.decode('utf8').strip().split('-')
+        if len(output) != 3:
+            return 'unknown'
+        version = '%s+%s' % (output[0], output[2])
+
+        code, _ = _run_cmd('git', 'diff', '--quiet')
+        if code:
+            version += '+dirty'
+
+        return version
+    except OSError:
+        return 'unknown'
+
+
+__version__ = _get_version()
diff --git a/vhdmmio/vhdl/__init__.py b/vhdmmio/vhdl/__init__.py
@@ -3,6 +3,7 @@
 import os
 from os.path import join as pjoin
 import shutil
+import vhdmmio
 from ..core.address import AddressSignalMap
 from ..core.subaddress import SubAddress
 from ..template import TemplateEngine, annotate_block
@@ -131,6 +132,7 @@ def __init__(self, regfile):
 
         # Add some basic variables and shorthands to the template engine for
         # the template to use.
+        self._tple['version'] = vhdmmio.__version__
         self._tple['r'] = regfile
         self._tple['e'] = regfile.cfg.entity
         self._tple['bw'] = regfile.cfg.features.bus_width
@@ -536,10 +538,14 @@ class VhdlPackageGenerator:
 
     @staticmethod
     def generate(output_dir):
-        """Generates the HTML documentation files for the register files in the
-        given directory."""
+        """Generates the common `vhdmmio_pkg.gen.vhd` file in the given
+        directory."""
         if not os.path.exists(output_dir):
             os.makedirs(output_dir)
-        shutil.copyfile(
-            pjoin(_MODULE_DIR, 'vhdmmio_pkg.vhd'),
-            pjoin(output_dir, 'vhdmmio_pkg.gen.vhd'))
+        tple = TemplateEngine()
+        tple['version'] = vhdmmio.__version__
+        tple.apply_file_to_file(
+            pjoin(_MODULE_DIR, 'vhdmmio_pkg.template.vhd'),
+            pjoin(output_dir, 'vhdmmio_pkg.gen.vhd'),
+            comment='-- ')
+        print('Wrote %s' % pjoin(output_dir, 'vhdmmio_pkg.gen.vhd'))
diff --git a/vhdmmio/vhdl/entity.template.vhd b/vhdmmio/vhdl/entity.template.vhd
@@ -1,4 +1,4 @@
--- Generated using vhdMMIO (https://github.com/abs-tudelft/vhdmmio)
+-- Generated using vhdMMIO $version$ (https://github.com/abs-tudelft/vhdmmio)
 
 library ieee;
 use ieee.std_logic_1164.all;

diff --git a/vhdmmio/vhdl/package.template.vhd b/vhdmmio/vhdl/package.template.vhd
@@ -1,4 +1,4 @@
--- Generated using vhdMMIO (https://github.com/abs-tudelft/vhdmmio)
+-- Generated using vhdMMIO $version$ (https://github.com/abs-tudelft/vhdmmio)
 
 library ieee;
 use ieee.std_logic_1164.all;

diff --git a/vhdmmio/vhdl/vhdmmio_pkg.vhd → vhdmmio/vhdl/vhdmmio_pkg.template.vhd b/vhdmmio/vhdl/vhdmmio_pkg.vhd → vhdmmio/vhdl/vhdmmio_pkg.template.vhd
@@ -1,3 +1,5 @@
+-- Generated using vhdMMIO $version$ (https://github.com/abs-tudelft/vhdmmio)
+
 library ieee;
 use ieee.std_logic_1164.all;