VUnit · eine · Apr 23, 2023 · Oct 21, 2021 · Oct 21, 2021 · Nov 9, 2021
diff --git a/docs/about.rst b/docs/about.rst
@@ -42,7 +42,7 @@ Main Features
  * Outputs JUnit report files for better `Jenkins`_ :ref:`integration <continuous_integration>`.
  * Builds on the commonly used `xUnit`_ architecture.
 
-* :ref:`Built-in VHDL utility libraries <vhdl_libraries>`:
+* :ref:`Built-in HDL utility libraries <hdl_libraries>`:
 
  * :doc:`Run library <./run/user_guide>` providing functionality for declaring multiple test cases within HDL
  testbenches.
@@ -84,7 +84,7 @@ Those are made available through the built-ins API, which is based on the librar
 
 Both the core and builtins are available in the public :ref:`python_interface` of VUnit.
 Details about how to execute a project are explained in :ref:`cli`.
-Further info about the optional libraries is found in :ref:`vhdl_libraries`.
+Further info about the optional libraries is found in :ref:`hdl_libraries`.
 
 Experimental co-simulation through GHDL's VHPIDIRECT is supported in `VUnit/cosim <https://vunit.github.io/cosim/>`__.
 

diff --git a/docs/blog/2018_02_12_vunit3.rst b/docs/blog/2018_02_12_vunit3.rst
@@ -75,7 +75,7 @@ Verification Components
 -----------------------
 
 In VUnit 3.0 we have a *beta* version of a :ref:`verification
-component <vc_library>` library. Using the improved ``com`` message
+component <vc_user_guide>` library. Using the improved ``com`` message
 passing it is very easy to create advanced verification components and
 we hope to get many pull requests from users for other bus types in
 the future. We've already seen some initiatives from the VUnit community
@@ -93,7 +93,7 @@ Out of the box we provide the following verification components:
  - UART RX/TX
  - (B)RAM master
 
-For more information see the :ref:`verification component library user guide <vc_library>`.
+For more information see the :ref:`verification component library user guide <vc_user_guide>`.
 
 Logging
 -------

diff --git a/docs/check/user_guide.rst b/docs/check/user_guide.rst
@@ -1,7 +1,7 @@
 .. _check_library:
 
-Check Library
-=============
+Check Library User Guide
+========================
 
 Introduction
 ------------
@@ -712,6 +712,7 @@ of this check comes when you enable the check preprocessor in your VUnit run scr
 .. 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`` and then parses ``expr`` as a VHDL relation. From

diff --git a/docs/com/user_guide.rst b/docs/com/user_guide.rst
@@ -1,8 +1,8 @@
 .. _com_user_guide:
 
-#####################
-Communication Library
-#####################
+################################
+Communication Library User Guide
+################################
 
 ************
 Introduction
@@ -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

diff --git a/docs/conf.py b/docs/conf.py
@@ -115,6 +115,7 @@
 intersphinx_mapping = {
  "python": ("https://docs.python.org/3.8/", None),
  "pytest": ("https://docs.pytest.org/en/latest/", None),
+ "osvb": ("https://umarcor.github.io/osvb", None),
 }
 
 # -- ExtLinks -----------------------------------------------------------------

diff --git a/docs/data_types/user_guide.rst b/docs/data_types/user_guide.rst
@@ -1,7 +1,7 @@
 .. _data_types_library:
 
-Data Types
-##########
+Data Types User Guide
+#####################
 
 VUnit comes with a number of convenient data types included:
 

diff --git a/docs/examples.py b/docs/examples.py
@@ -71,6 +71,7 @@ def _get_eg_doc(location: Path, ref):
  title = eg_doc.split("---", 1)[0][0:-1]
  return "\n".join(
  [
+ f".. _examples:{location.parent.name}:{location.name}:\n",
  title,
  "-" * len(title),
  f":vunit_example:`➚ examples/{ref} <{ref!s}>`\n",

diff --git a/docs/hdl_libraries.rst b/docs/hdl_libraries.rst
@@ -0,0 +1,90 @@
+.. _hdl_libraries:
+
+HDL Libraries
+#############
+
+VHDL
+====
+
+Builtins
+--------
+
+By default, VUnit provides bare minimal functionality for running testbenches.
+In practice, most users want to use HDL utilities to reduce verbosity and improve reporting when writting tests.
+VUnit includes several optional libraries in a group named *VHDL builtins* (see :meth:`add_vhdl_builtins() <vunit.ui.VUnit.add_vhdl_builtins>`):
+
+* :vunit_file:`core <vunit/vhdl/core>`
+* :vunit_file:`logging <vunit/vhdl/logging>` (see :ref:`logging_library`)
+* :vunit_file:`string_ops <vunit/vhdl/string_ops>`
+* :vunit_file:`check <vunit/vhdl/check>` (see :ref:`check_library`)
+* :vunit_file:`dictionary <vunit/vhdl/dictionary>`
+* :vunit_file:`run <vunit/vhdl/run>` (see :ref:`run_library`)
+* :vunit_file:`path <vunit/vhdl/path>`
+
+Most of the utilities are based on some internal data types providing dynamic arrays and queues (FIFOs).
+See :ref:`data_types_library`.
+
+Communication
+-------------
+
+The VUnit communication library (``com``) provides a high-level communication mechanism based on the
+`actor model <http://en.wikipedia.org/wiki/Actor_model>`__.
+
+See :meth:`add_com() <vunit.ui.VUnit.add_com>` and :ref:`com_user_guide`.
+
+.. NOTE::
+ The Communication Library depends on the builtins, which are added implicitly.
+
+Verification Components
+-----------------------
+
+.. note:: This library is released as a *BETA* version. This means non-backwards compatible changes are still likely
+ based on feedback from our users.
+
+The VUnit Verification Component Library (VCL) contains a number of useful
+:ref:`Verification Components <verification_components>` (VC) as well as a set of utilities for writing your own
+verification component.
+Verification components allow a better overview in the test bench by raising the abstraction level of bus transactions.
+Even if you do not need the advanced features that VCs offer you may still benefit from using peer-verified models of an
+AXI-bus instead of re-implementing it yourself.
+
+See :meth:`add_verification_components() <vunit.ui.VUnit.add_verification_components>` and :ref:`vc_user_guide`.
+
+.. NOTE::
+ The VCL depends on both the Communication Library and OSVVM, which are added implicitly.
+
+Random
+------
+
+VUnit provides random integer vector and pointer generation, based on built-in :ref:`Data Types <data_types_library>`
+and OSVVM.
+
+See :meth:`add_random() <vunit.ui.VUnit.add_random>`.
+
+OSVVM
+-----
+
+VUnit includes the core of `OSVVM <https://github.com/osvvm/>`__ as a submodule and internal dependency of optional
+libraries such as Random or Verification Components.
+However, it can be added explicitly through :meth:`add_osvvm() <vunit.ui.VUnit.add_osvvm>`.
+
+Moreover, multiple approaches are supported for using `OSVVMLibraries <https://github.com/OSVVM/OsvvmLibraries>`__ in
+VUnit.
+See :ref:`OSVB: Examples » SISO AXI4 Stream <osvb:Examples:AXI4Stream>`.
+
+JSON-for-VHDL
+-------------
+
+VUnit includes `JSON-for-VHDL <https://github.com/Paebbels/JSON-for-VHDL>`__ as a submodule.
+JSON-for-VHDL is an alternative to composite top-level generics, which supports any depth in the content structure.
+
+See :meth:`add_json4vhdl() <vunit.ui.VUnit.add_json4vhdl>`, :vunit_file:`json4vhdl.py <vunit/json4vhdl.py>` and example
+:ref:`JSON-for-VHDL <examples:vhdl:json4vhdl>`.
+
+System Verilog
+==============
+
+Builtins
+--------
+
+See :meth:`add_verilog_builtins() <vunit.ui.VUnit.add_verilog_builtins>` and :vunit_file:`vunit_pkg.sv <vunit/verilog/vunit_pkg.sv>`.
diff --git a/docs/index.rst b/docs/index.rst
@@ -29,13 +29,25 @@ often"* approach through automation. :ref:`Read more <about>`
  testimonials/testimonials
 
 .. toctree::
- :caption: Documentation
+ :caption: Guides
  :hidden:
 
  user_guide
+ id/user_guide
+ logging/user_guide
+ check/user_guide
+ run/user_guide
+ com/user_guide
+ verification_components/user_guide
+ data_types/user_guide
+
+.. toctree::
+ :caption: Reference
+ :hidden:
+
  cli
  py/ui
- vhdl_libraries
+ hdl_libraries
  examples
 
 .. toctree::

diff --git a/docs/logging/user_guide.rst b/docs/logging/user_guide.rst
@@ -1,7 +1,7 @@
 .. _logging_library:
 
-Logging Library
-===============
+Logging Library User Guide
+==========================
 
 Introduction
 ------------
@@ -303,6 +303,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:

diff --git a/docs/news.d/559.breaking.rst b/docs/news.d/559.breaking.rst
@@ -0,0 +1,4 @@
+HDL builtins are not compiled by default.
+To preserve the functionality, the run script is now required to explicitly use methods
+:meth:`add_vhdl_builtins() <vunit.ui.VUnit.add_vhdl_builtins>` or
+:meth:`add_verilog_builtins() <vunit.ui.VUnit.add_verilog_builtins>`.
diff --git a/docs/news.d/764.breaking.rst b/docs/news.d/764.breaking.rst
@@ -0,0 +1,4 @@
+HDL builtins are not compiled by default.
+To preserve the functionality, the run script is now required to explicitly use methods
+:meth:`add_vhdl_builtins() <vunit.ui.VUnit.add_vhdl_builtins>` or
+:meth:`add_verilog_builtins() <vunit.ui.VUnit.add_verilog_builtins>`.
diff --git a/docs/news.d/764.doc.rst b/docs/news.d/764.doc.rst
@@ -0,0 +1 @@
+Rename 'VHDL Libraries' to :ref:`hdl_libraries`. Add section :ref:`Guides <user_guide>`.
diff --git a/docs/news.d/777.breaking.rst b/docs/news.d/777.breaking.rst
@@ -0,0 +1,4 @@
+HDL builtins are not compiled by default.
+To preserve the functionality, the run script is now required to explicitly use methods
+:meth:`add_vhdl_builtins() <vunit.ui.VUnit.add_vhdl_builtins>` or
+:meth:`add_verilog_builtins() <vunit.ui.VUnit.add_verilog_builtins>`.
diff --git a/docs/release_notes/3.0.0.rst b/docs/release_notes/3.0.0.rst
@@ -1,4 +1,4 @@
-- *beta* version of a :ref:`verification component <vc_library>` library.
+- *beta* version of a :ref:`verification component <vc_user_guide>` library.
 
  - AXI read/write slaves
  - Memory model

diff --git a/docs/run/user_guide.rst b/docs/run/user_guide.rst
@@ -1,7 +1,7 @@
 .. _run_library:
 
-Run Library
-===========
+Run Library User Guide
+======================
 
 Introduction
 ------------

diff --git a/docs/user_guide.rst b/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")
 

diff --git a/docs/verification_components/user_guide.rst b/docs/verification_components/user_guide.rst
@@ -1,18 +1,12 @@
-.. _vc_library:
+.. _vc_user_guide:
 
-Verification Component Library
-===============================
+Verification Components User Guide
+==================================
 
 .. NOTE::
  This library is released as a *BETA* version.
  This means non-backwards compatible changes are still likely based on feedback from our users.
 
-The VUnit Verification Component Library (VCL) contains a number of useful :ref:`Verification Components <verification_components>`
-(VC) as well as a set of utilities for writing your own verification component.
-Verification components allow a better overview in the test bench by raising the abstraction level of bus transactions.
-Even if you do not need the advanced features that VCs offer you may still benefit from using pre-verified models of an
-AXI-bus instead of re-implementing it yourself.
-
 Included verification components (VCs):
 
 - Avalon Memory-Mapped master

diff --git a/docs/vhdl_libraries.rst b/docs/vhdl_libraries.rst
diff --git a/examples/verilog/uart/run.py b/examples/verilog/uart/run.py
@@ -15,11 +15,13 @@
 """
 
 from pathlib import Path
-from vunit.verilog import VUnit
+from vunit import VUnit
 
 SRC_PATH = Path(__file__).parent / "src"
 
 VU = VUnit.from_argv()
+VU.add_verilog_builtins()
+
 VU.add_library("uart_lib").add_source_files(SRC_PATH / "*.sv")
 VU.add_library("tb_uart_lib").add_source_files(SRC_PATH / "test" / "*.sv")
 

diff --git a/examples/verilog/user_guide/run.py b/examples/verilog/user_guide/run.py
@@ -15,11 +15,13 @@
 """
 
 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 / "*.sv")
 
 VU.main()
diff --git a/examples/verilog/verilog_ams/run.py b/examples/verilog/verilog_ams/run.py
@@ -7,11 +7,13 @@
 # Copyright (c) 2014-2023, 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()
+
 LIB = VU.add_library("lib")
 LIB.add_source_files(ROOT / "*.sv")
 LIB.add_source_files(ROOT / "*.vams").set_compile_option("modelsim.vlog_flags", ["-ams"])

diff --git a/examples/vhdl/array/run.py b/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"

diff --git a/examples/vhdl/array_axis_vcs/run.py b/examples/vhdl/array_axis_vcs/run.py
@@ -13,7 +13,7 @@
 Shows how to use ``integer_array_t``, ``axi_stream_master_t`` and ``axi_stream_slave_t``.
 A CSV file is read, the content is sent in a row-major order to an AXI Stream buffer
 (FIFO) and it is received back to be saved in a different file. Further information can
-be found in the :ref:`verification component library user guide <vc_library>`,
+be found in the :ref:`verification component library user guide <vc_user_guide>`,
 in subsection :ref:`Stream <stream_vci>` and in
 :vunit_file:`vhdl/verification_components/test/tb_axi_stream.vhd <vunit/vhdl/verification_components/test/tb_axi_stream.vhd>`.
 """
@@ -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"

diff --git a/examples/vhdl/axi_dma/run.py b/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()