diff --git a/docs/data_types/external_api.rst b/docs/data_types/external_api.rst index f3f467e3d..bcaa396cf 100644 --- a/docs/data_types/external_api.rst +++ b/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 `) * **integer_vector_ptr** (:ref:`External integer vector API `) -.. 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=)`, where `` defaults to ``{"string": False, "integer_vector": False}``. Each field should contain a list of VHDL files to replace the *dummy* default. See `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=)`, where `` defaults to ``{"string": False, "integer_vector": False}``. Each field should contain a list of VHDL files to replace the *dummy* default. See `VUnit/cosim `_ for reference implementations of bridges and examples. .. toctree:: :hidden: ext_string ext_integer_vector - diff --git a/docs/py/vunit.rst b/docs/py/vunit.rst index 96256f6e7..ef61e781e 100644 --- a/docs/py/vunit.rst +++ b/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 ------- diff --git a/vunit/builtins.py b/vunit/builtins.py index c8ffcbbe8..f6d338049 100755 --- a/vunit/builtins.py +++ b/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") diff --git a/vunit/ui/__init__.py b/vunit/ui/__init__.py index 80ed8e1be..7351bdf43 100644 --- a/vunit/ui/__init__.py +++ b/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) diff --git a/vunit/verilog.py b/vunit/verilog.py index 4a5bd88fd..3fabcb73b 100644 --- a/vunit/verilog.py +++ b/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) diff --git a/vunit/verilog/check/run.py b/vunit/verilog/check/run.py index f70f1fa11..f328b0ec4 100644 --- a/vunit/verilog/check/run.py +++ b/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"])