add 'compile_builtins' deprecation warning (#757)

docs/data_types/external_api.rst

@@ -16,11 +16,10 @@ List of types that are currently in the external VHDL API:
 * **string_ptr**, and **byte_vector_ptr** as an alias (:ref:`External string API <ext_string_pkg>`)
 * **integer_vector_ptr** (:ref:`External integer vector API <ext_integer_vector_pkg>`)
 
-.. important:: By default, bodies of the external API functions/procedures include forced failure assertions. Hence, using ``mode/=internal`` without providing a *bridge* to a foreign language will make tests fail. Bridges must be provided through `vu.add_builtins(external=<Options>)`, where `<Options>` defaults to ``{"string": False, "integer_vector": False}``. Each field should contain a list of VHDL files to replace the *dummy* default. See `VUnit/cosim <https://github.com/VUnit/cosim>`_ for reference implementations of bridges and examples.
+.. important:: By default, bodies of the external API functions/procedures include forced failure assertions. Hence, using ``mode/=internal`` without providing a *bridge* to a foreign language will make tests fail. Bridges must be provided through `vu.add_vhdl_builtins(external=<Options>)`, where `<Options>` defaults to ``{"string": False, "integer_vector": False}``. Each field should contain a list of VHDL files to replace the *dummy* default. See `VUnit/cosim <https://github.com/VUnit/cosim>`_ for reference implementations of bridges and examples.
 
 .. toctree::
    :hidden:
 
    ext_string
    ext_integer_vector
-

docs/py/vunit.rst

@@ -2,8 +2,7 @@ vunit.ui
 ========
 
 .. autoclass:: vunit.ui.VUnit()
-   :exclude-members: add_preprocessor,
-      add_builtins
+   :exclude-members: add_preprocessor
 
 Library
 -------

vunit/builtins.py

@@ -224,10 +224,15 @@ def add_vhdl_builtins(self, external=None):
         Add vunit VHDL builtin libraries
 
         :param external: struct to provide bridges for the external VHDL API.
-                         {
-                             'string': ['path/to/custom/file'],
-                             'integer': ['path/to/custom/file']
-                         }.
+
+        :example:
+
+        .. code-block:: python
+
+            Builtins.add_vhdl_builtins(external={
+                'string': ['path/to/custom/file'],
+                'integer': ['path/to/custom/file']
+            })
         """
         self._add_data_types(external=external)
         self._add_files(VHDL_PATH / "*.vhd")

vunit/ui/__init__.py

@@ -19,6 +19,7 @@
 from typing import Optional, Set, Union
 from pathlib import Path
 from fnmatch import fnmatch
+
 from ..database import PickledDataBase, DataBase
 from .. import ostools
 from ..vunit_cli import VUnitCLI
@@ -157,7 +158,23 @@ def test_filter(name, attribute_names):
 
         self._builtins = Builtins(self, self._vhdl_standard, simulator_class)
         if compile_builtins:
-            self.add_builtins()
+            self.add_vhdl_builtins()
+            hline = "=" * 75
+            print(hline)
+            LOGGER.warning(
+                """Option 'compile_builtins' of methods 'from_args' and 'from_argv' is deprecated.
+In future releases, it will be removed and builtins will need to be added explicitly.
+To prepare for upcoming changes, it is recommended to apply the following modifications in the run script now:
+
+* Use `from_argv(compile_builtins=False)` or `from_args(compile_builtins=False)`.
+* Add an explicit call to 'add_vhdl_builtins'.
+
+Refs:
+  * http://vunit.github.io/py/vunit.html#vunit.ui.VUnit.from_args
+  * http://vunit.github.io/py/vunit.html#vunit.ui.VUnit.from_argv
+"""
+            )
+            print(hline)
 
     def _create_database(self):
         """
@@ -925,15 +942,26 @@ def _run_test(self, test_cases, report):
         )
         runner.run(test_cases)
 
-    def add_builtins(self, external=None):
+    def add_verilog_builtins(self):
+        """
+        Add VUnit Verilog builtin libraries
+        """
+        self._builtins.add_verilog_builtins()
+
+    def add_vhdl_builtins(self, external=None):
         """
-        Add vunit VHDL builtin libraries
+        Add VUnit VHDL builtin libraries
 
         :param external: struct to provide bridges for the external VHDL API.
-                         {
-                             'string': ['path/to/custom/file'],
-                             'integer': ['path/to/custom/file']
-                         }.
+
+        :example:
+
+        .. code-block:: python
+
+            VU.add_vhdl_builtins(external={
+                'string': ['path/to/custom/file'],
+                'integer': ['path/to/custom/file']}
+            )
         """
         self._builtins.add_vhdl_builtins(external=external)
 

vunit/verilog.py

@@ -8,6 +8,7 @@
 The main public Python interface of VUnit-Verilog.
 """
 
+from warnings import warn
 from vunit.ui import VUnit as VUnitVHDL
 
 
@@ -16,8 +17,15 @@ class VUnit(VUnitVHDL):
     VUnit Verilog interface
     """
 
-    def add_builtins(self, external=None):  # pylint: disable=arguments-differ
+    # This is a temporary workaround to avoid breaking the scripts of current verilog users
+    def add_vhdl_builtins(self):  # pylint: disable=arguments-differ
         """
         Add vunit Verilog builtin libraries
         """
         self._builtins.add_verilog_builtins()
+        builtins_deprecation_note = (
+            "class 'verilog' is deprecated and it will be removed in future releases; "
+            "preserve the functionality using the default vunit class, along with "
+            "'compile_builtins=False' and 'VU.add_verilog_builtins'"
+        )
+        warn(builtins_deprecation_note, Warning)

vunit/verilog/check/run.py

@@ -5,12 +5,14 @@
 # Copyright (c) 2014-2021, Lars Asplund lars.anders.asplund@gmail.com
 
 from pathlib import Path
-from vunit.verilog import VUnit
+from vunit import VUnit
 
 
 ROOT = Path(__file__).parent
 
 VU = VUnit.from_argv()
+VU.add_verilog_builtins()
+
 VU.add_library("lib").add_source_files(ROOT / "test" / "*.sv")
 VU.set_sim_option("modelsim.vsim_flags.gui", ["-novopt"])