[Breaking Change] Deprecation of 'compile_builtins' and removal in v5

[umarcor]

Option compile_builtins of methods from_args and from_argv is to be removed in an upcoming release of VUnit. Until v4.7.0 (included), compile_builtins is enabled by default. Therefore, removing the option (thus, having it disabled by default), is a breaking change that will affect most users, particularly newcomers copying and pasting examples/tutorials. This issue contains guidelines to adapt the scripts.

References:

• Do not add builtins by default #559
• add 'compile_builtins' deprecation warning #757
• remove compile_builtins and vunit.verilog #764
• vunit.github.io: Python Interface » vunit.ui » add_verilog_builtins
• vunit.github.io: Python Interface » vunit.ui » add_vhdl_builtins
• vunit.github.io: Python Interface » vunit.ui » from_args
• vunit.github.io: Python Interface » vunit.ui » from_argv

VHDL only

Traditional procedure (until v4.6.0):

from vunit import VUnit
VU = VUnit.from_argv()

Recommended procedure with v4.7.0 (current master):

from vunit import VUnit
VU = VUnit.from_argv(compile_builtins=False)  # Stop using the builtins ahead of time.
VU.add_vhdl_builtins()  # Add the VHDL builtins explicitly!

Upcoming procedure with v5:

from vunit import VUnit
VU = VUnit.from_argv()  # Do not use compile_builtins.
VU.add_vhdl_builtins()  # Add the VHDL builtins explicitly!

Verilog only

Traditional procedure (until v4.6.0):

from vunit.verilog import VUnit
VU = VUnit.from_argv()

Recommended procedure with v4.7.0 (current master):

from vunit import VUnit  # Change this to use the default class instead of vunit.verilog!
VU = VUnit.from_argv(compile_builtins=False)  # Ensure that VHDL builtins are not added.
VU.add_verilog_builtins()  # Add the verilog builtins explicitly!

Upcoming procedure with v5:

from vunit import VUnit  # Use the default class instead of vunit.verilog!
VU = VUnit.from_argv()  # Do not use compile_builtins.
VU.add_verilog_builtins()  # Add the verilog builtins explicitly!

Mixed language (VHDL and Verilog, or Verilog and VHDL)

Traditional procedure (until v4.6.0):

# Default class (VHDL first)
from vunit import VUnit
VU = VUnit.from_argv()
VU.add_verilog_builtins()

# Verilog class (Verilog first)
from vunit.verilog import VUnit
VU = VUnit.from_argv()
VU.add_vhdl_builtins()

Recommended procedure with v4.7.0 (current master):

# VHDL first
from vunit import VUnit
VU = VUnit.from_argv(compile_builtins=False)  # Stop using the builtins ahead of time.
VU.add_vhdl_builtins()  # Add the VHDL builtins explicitly!
VU.add_verilog_builtins()

# Verilog first
from vunit import VUnit
VU = VUnit.from_argv(compile_builtins=False)  # Ensure that VHDL builtins are not added ahead of time.
VU.add_verilog_builtins()  # Add the verilog builtins explicitly!
VU.add_vhdl_builtins()

Upcoming procedure with v5:

# VHDL first
from vunit import VUnit
VU = VUnit.from_argv()  # Do not use compile_builtins.
VU.add_vhdl_builtins()  # Add the VHDL builtins explicitly!
VU.add_verilog_builtins()

# Verilog first
from vunit import VUnit  # Use the default class instead of vunit.verilog!
VU = VUnit.from_argv()  # Do not use compile_builtins
VU.add_verilog_builtins()  # Add the verilog builtins explicitly!
VU.add_vhdl_builtins()

[GlenNicholls]

Quick question, what is the reason for this change? Is this to support the use-case where a user/team might want to pre-compile the builtins for their simulators to speed up test runs?

I have nothing against the change, just curious why it's being made.

[umarcor]

There are both technical and tactical reasons.

On the technical side, having separated commands/options to add VHDL and Verilog builtins (instead of overriding the same one) allows us to more easily share the features that are common, regardless of the language; or even using both in mixed-language desings. We avoid a VUnit class for Verilog. Note that verilog.py is removed in #764. That's something we discussed in 2019 (#559), but we did not implement yet because it is a breaking change and we did not have any other particular reason. I think the use case you ask about is unaffected by this change. In both solutions you can not compile the bultins and add them as an external precompiled resource.

On the tactical side, we want to better communicate VUnit's vision of the broader (open source) hardware verification ecosystem.
As you know, VUnit is composed by three main parts (see http://vunit.github.io/about.html#overview): the python-HDL runner interface, the Python management and reporting API, and HDL utility libraries. VUnit's approach is modular, so that each user can pick the features they need, and they can combine them with their own or with third-party code. Using resources from projects such as OSVVM or UVVM has always been a supported use case.
During the first ~5y after VUnit was released, there was no open source test management alternative comparable to VUnit for HDL development and CI. We hoped that OSVVM and UVVM would collaborate to better integrate the HDL utilities with VUnit's Python management and reporting API. Unfortunately, due to legit commercial interests, both projects decided to reinvent the wheels themselves, in order to keep their users captive through obscurity. In the process, they claimed/claim that VUnit is a monolith, and argue(d) they don't want their users to be exposed to VUnit's HDL features at all (ideally, they'd want users not to know they even exist). They did also complain about the usage of the term "methodology", which they argued with each other about. While I understand why they decided to do so, I don't share that (broken/fractured) vision of the community; and although I'm not brave enough to use "we" here, I believe it's a shared feeling among VUnit developers/maintainers. Therefore, we are doing an effort to better communicate:

• To users, what's VUnit's vision, and how they can combine multiple frameworks/methodologies using VHDL and/or SV. By technically managing VUnit's HDL utilities the same way we manage OSVVM or VCs, we make an statement about not having first-class HDL features. We might eventually even submodule those, even though we have no technical reason to address that at the moment.
• To OSVVM/UVVM developers, how they can let their fears aside and embrace open development and collaboration. Despite their efforts in the last 4-5y, VUnit is still the best management solution for CI. The community would be stronger if they focused on the stuff they do best, which is complex enough already. E.g. OSVVM's Coverage, VCs and the new CoSim solutions are pretty good.

Some relevant references in this regard:

• The updated What is VUnit?
• FAQ: What is VUnit's Relation to Other Verification Frameworks?
  • Common log interface #776
  • Add configuration support #785
• GitHub Facts About the HDL Industry
• Combining VUnit and OSVVM: umarcor.github.io/osvb/egs/axi4stream.html. Expected outcomes:
  • Using OSVVM's AXI4 Stream VC and managing the tests through VUnit.
  • Using EDAA to import OSVVM's project files into VUnit.
    • See https://github.com/edaa-org/pyEDAA.ProjectModel/blob/main/pyEDAA/ProjectModel/OSVVM.py
    • See also https://github.com/edaa-org/pyEDAA.ProjectModel/tree/main/pyEDAA/ProjectModel/Xilinx