ui: remove 'compile_builtins'; preserve previous behaviour using 'add…

…_vhdl_builtins' (VUnit#559)

docs/check/user_guide.rst

@@ -703,6 +703,7 @@ preprocessor in your VUnit run script.
 .. code-block:: python
 
     ui = VUnit.from_argv()
+    ui.add_vhdl_builtins()
     ui.enable_check_preprocessing()
 
 The check preprocessor scans your code for calls to ``check_relation``

docs/com/user_guide.rst

@@ -35,6 +35,7 @@ is provided as an optional add-on to VUnit. It is compiled to the
 .. code-block:: python
 
     prj = VUnit.from_argv()
+    prj.add_vhdl_builtins()
     prj.add_com()
 
 The VHDL functionality is provided to your testbench with the

docs/logging/user_guide.rst

@@ -301,6 +301,7 @@ the ``run.py`` file like this:
 .. code-block:: python
 
     ui = VUnit.from_argv()
+    ui.add_vhdl_builtins()
     ui.enable_location_preprocessing()
 
 Regardless of method the location information is appended to the end of the log entry:

docs/user_guide.rst

@@ -43,6 +43,12 @@ bench or test for many different combinations of generic values.
    # Create VUnit instance by parsing command line arguments
    vu = VUnit.from_argv()
 
+   # Optionally add VUnit's builtin HDL utilities for checking, logging, communication...
+   # See http://vunit.github.io/hdl_libraries.html.
+   vu.add_vhdl_builtins()
+   # or
+   # vu.add_verilog_builtins()
+
    # Create library 'lib'
    lib = vu.add_library("lib")
 

examples/vhdl/array/run.py

@@ -19,6 +19,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_osvvm()
 
 SRC_PATH = Path(__file__).parent / "src"

examples/vhdl/array_axis_vcs/run.py

@@ -22,6 +22,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_verification_components()
 
 SRC_PATH = Path(__file__).parent / "src"

examples/vhdl/axi_dma/run.py

@@ -21,6 +21,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_osvvm()
 VU.add_verification_components()
 

examples/vhdl/check/run.py

@@ -17,6 +17,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 # Enable location preprocessing but exclude all but check_false to make the example less bloated
 VU.enable_location_preprocessing(

examples/vhdl/com/run.py

@@ -19,6 +19,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_com()
 VU.add_verification_components()
 VU.add_osvvm()

examples/vhdl/composite_generics/run.py

@@ -22,6 +22,7 @@ def encode(tb_cfg):
 
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 TB_LIB = VU.add_library("tb_lib")
 TB_LIB.add_source_files(Path(__file__).parent / "test" / "*.vhd")

examples/vhdl/coverage/run.py

@@ -18,6 +18,7 @@ def post_run(results):
 
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 LIB = VU.add_library("lib")
 LIB.add_source_files(Path(__file__).parent / "*.vhd")

examples/vhdl/generate_tests/run.py

@@ -63,6 +63,8 @@ def generate_tests(obj, signs, data_widths):
 
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 LIB = VU.add_library("lib")
 LIB.add_source_files(Path(__file__).parent / "test" / "*.vhd")
 

examples/vhdl/json4vhdl/run.py

@@ -22,6 +22,7 @@
 TEST_PATH = Path(__file__).parent / "src" / "test"
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_json4vhdl()
 
 LIB = VU.add_library("test")

examples/vhdl/logging/run.py

@@ -17,6 +17,8 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 VU.add_library("lib").add_source_files(Path(__file__).parent / "*.vhd")
 
 VU.main()

examples/vhdl/run/run.py

@@ -19,6 +19,7 @@
 ROOT = Path(__file__).parent
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 LIB = VU.add_library("lib")
 LIB.add_source_files(ROOT / "*.vhd")

examples/vhdl/third_party_integration/run.py

@@ -10,5 +10,8 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 VU.add_library("lib").add_source_files(Path(__file__).parent / "test" / "*.vhd")
+
 VU.main()

examples/vhdl/uart/run.py

@@ -18,6 +18,7 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_osvvm()
 VU.add_verification_components()
 

examples/vhdl/user_guide/run.py

@@ -18,5 +18,8 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 VU.add_library("lib").add_source_files(Path(__file__).parent / "*.vhd")
+
 VU.main()

examples/vhdl/user_guide/vhdl1993/run.py

@@ -18,5 +18,8 @@
 from vunit import VUnit
 
 VU = VUnit.from_argv(vhdl_standard="93")
+VU.add_vhdl_builtins()
+
 VU.add_library("lib").add_source_files(Path(__file__).parent / "*.vhd")
+
 VU.main()

examples/vhdl/vivado/run.py

@@ -20,6 +20,7 @@
 SRC_PATH = ROOT / "src"
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 VU.add_library("lib").add_source_files(SRC_PATH / "*.vhd")
 VU.add_library("tb_lib").add_source_files(SRC_PATH / "test" / "*.vhd")

tests/acceptance/artificial/vhdl/run.py

@@ -11,10 +11,12 @@
 root = Path(__file__).parent
 
 vu = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 lib = vu.add_library("lib")
 lib2 = vu.add_library("lib2")
-files = glob(str(root / "*.vhd"))
-for file in files:
+
+for file in glob(str(root / "*.vhd")):
     if "tb_set_generic" in file:
         lib2.add_source_files(file)
     else:

tests/acceptance/test_dependencies.py

@@ -49,6 +49,7 @@ def run(value):
                 argv.append("--clean")
 
             ui = VUnit.from_argv(argv=argv)
+            ui.add_vhdl_builtins()
             lib = ui.add_library("lib")
             lib.add_source_files(tb_pkg_file_name)
             lib.add_source_files(pkg_file_name)

tests/unit/test_ui.py

@@ -1243,7 +1243,6 @@ def _create_ui_real_sim(self, *args):
         """Create an instance of the VUnit public interface class"""
         return VUnit.from_argv(
             argv=["--output-path=%s" % self._output_path, "--clean"] + list(args),
-            compile_builtins=False,
         )
 
     def _run_main(self, ui, code=0, post_run=None):

vunit/ui/__init__.py

@@ -59,14 +59,12 @@ class VUnit(object):  # pylint: disable=too-many-instance-attributes, too-many-p
     def from_argv(
         cls,
         argv=None,
-        compile_builtins: Optional[bool] = True,
         vhdl_standard: Optional[str] = None,
     ):
         """
         Create VUnit instance from command line arguments.
 
         :param argv: Use explicit argv instead of actual command line argument
-        :param compile_builtins: Do not compile builtins. Used for VUnit internal testing.
         :param vhdl_standard: The VHDL standard used to compile files,
                               if None the VUNIT_VHDL_STANDARD environment variable is used
         :returns: A :class:`.VUnit` object instance
@@ -77,28 +75,21 @@ def from_argv(
 
              from vunit import VUnit
              prj = VUnit.from_argv()
+             prj.add_vhdl_builtins()
 
         .. IMPORTANT::
-          Option ``compile_builtins`` is deprecated and it will be removed in an upcoming release.
-          VHDL users will need to call method :meth:`add_vhdl_builtins` explicitly in order to preserve the
+          As of VUnit v5, option ``compile_builtins`` is removed.
+          VHDL users need to call method :meth:`add_vhdl_builtins` explicitly in order to preserve the
           functionality.
           See :vunit_issue:`777`.
-          It is therefore recommended to now use the following procedure:
-
-          .. code-block:: python
-
-             from vunit import VUnit
-             prj = VUnit.from_argv(compile_builtins=False)
-             prj.add_vhdl_builtins()
         """
         args = VUnitCLI().parse_args(argv=argv)
-        return cls.from_args(args, compile_builtins=compile_builtins, vhdl_standard=vhdl_standard)
+        return cls.from_args(args, vhdl_standard=vhdl_standard)
 
     @classmethod
     def from_args(
         cls,
         args,
-        compile_builtins: Optional[bool] = True,
         vhdl_standard: Optional[str] = None,
     ):
         """
@@ -108,23 +99,21 @@ def from_args(
         adding custom command line options.
 
         :param args: The parsed argument namespace object
-        :param compile_builtins: Do not compile builtins. Used for VUnit internal testing.
         :param vhdl_standard: The VHDL standard used to compile files,
                               if None the VUNIT_VHDL_STANDARD environment variable is used
         :returns: A :class:`.VUnit` object instance
 
         .. IMPORTANT::
-          Option ``compile_builtins`` is deprecated and it will be removed in an upcoming release.
-          VHDL users will need to call method :meth:`add_vhdl_builtins` explicitly in order to preserve the
+          As of VUnit v5, option ``compile_builtins`` is removed.
+          VHDL users need to call method :meth:`add_vhdl_builtins` explicitly in order to preserve the
           functionality.
           See :vunit_issue:`777`.
         """
-        return cls(args, compile_builtins=compile_builtins, vhdl_standard=vhdl_standard)
+        return cls(args, vhdl_standard=vhdl_standard)
 
     def __init__(
         self,
         args,
-        compile_builtins: Optional[bool] = True,
         vhdl_standard: Optional[str] = None,
     ):
         self._args = args
@@ -179,13 +168,8 @@ def test_filter(name, attribute_names):
             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'.
-
+                """As of VUnit v5, option ``compile_builtins`` of methods 'from_args' and 'from_argv' is removed.
+HDL builtins need to be added explicitly.
 See https://github.com/VUnit/vunit/issues/777.
 """
             )
@@ -1008,9 +992,8 @@ def add_vhdl_builtins(self, external=None):
             )
 
         .. IMPORTANT::
-          Option ``compile_builtins`` of methods :meth:`from_argv` and :meth:`from_args` is deprecated and it will be
-          removed in an upcoming release.
-          VHDL users will need to call this method explicitly in order to preserve the functionality.
+          As of VUnit v5, option ``compile_builtins`` of methods :meth:`from_argv` and :meth:`from_args` is removed.
+          VHDL users need to call this method explicitly in order to preserve the functionality.
           See :vunit_issue:`777`.
         """
         self._builtins.add_vhdl_builtins(external=external)

vunit/vhdl/array/run.py

@@ -11,6 +11,7 @@
 ROOT = Path(__file__).parent
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 VU.add_array_util()
 VU.library("vunit_lib").add_source_files(ROOT / "test" / "*.vhd")
 

vunit/vhdl/check/run.py

@@ -16,6 +16,7 @@
 generate_check_match.main()
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
 
 LIB = VU.add_library("lib")
 LIB.add_source_files(Path(ROOT) / "vunit" / "vhdl" / "check" / "test" / "test_support.vhd")

vunit/vhdl/com/run.py

@@ -10,7 +10,9 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
 UI.add_com()
+
 TB_COM_LIB = UI.add_library("tb_com_lib")
 TB_COM_LIB.add_source_files(ROOT / "test" / "*.vhd")
 TB_COM_LIB.package("custom_types_pkg").generate_codecs(

vunit/vhdl/data_types/run.py

@@ -11,6 +11,8 @@
 ROOT = Path(__file__).parent
 
 VU = VUnit.from_argv()
+VU.add_vhdl_builtins()
+
 LIB = VU.library("vunit_lib")
 LIB.add_source_files(ROOT / ".." / "logging" / "test" / "test_support_pkg.vhd")
 for fname in glob(str(ROOT / "test" / "*.vhd")):

vunit/vhdl/dictionary/run.py

@@ -10,6 +10,8 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
+
 UI.add_library("lib").add_source_files(ROOT / "test" / "*.vhd")
 
 UI.main()

vunit/vhdl/logging/run.py

@@ -15,6 +15,7 @@ def main():
     root = Path(__file__).parent
 
     ui = VUnit.from_argv()
+    ui.add_vhdl_builtins()
 
     vunit_lib = ui.library("vunit_lib")
     files = glob.glob(str(root / "test" / "*.vhd"))

vunit/vhdl/path/run.py

@@ -10,6 +10,8 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
+
 UI.add_library("lib").add_source_files(ROOT / "test" / "*.vhd")
 
 UI.main()

vunit/vhdl/random/run.py

@@ -10,7 +10,9 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
 UI.add_random()
+
 UI.library("vunit_lib").add_source_files(ROOT / "test" / "*.vhd")
 
 UI.main()

vunit/vhdl/run/run.py

@@ -10,6 +10,8 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
+
 UI.add_library("tb_run_lib").add_source_files(ROOT / "test" / "*.vhd")
 
 UI.main()

vunit/vhdl/string_ops/run.py

@@ -10,6 +10,8 @@
 ROOT = Path(__file__).parent
 
 UI = VUnit.from_argv()
+UI.add_vhdl_builtins()
+
 UI.add_library("lib").add_source_files(ROOT / "test" / "*.vhd")
 
 UI.main()