search

VUnit / vunit

VUnit is a unit testing framework for VHDL/SystemVerilog
http://vunit.github.io/
Other
698 stars 250 forks source link

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

Open umarcor opened 2 years ago

umarcor commented 2 years ago

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:

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 commented 1 year ago

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 commented 1 year ago

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 https://github.com/VUnit/vunit/pull/764. That's something we discussed in 2019 (https://github.com/VUnit/vunit/issues/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:

Some relevant references in this regard: