Paebbels/ruff 3.0b1

OsvvmScriptsCore.tcl

@@ -92,8 +92,9 @@ proc StartUp {} {
 
 
 namespace eval ::osvvm {
-
-
+  variable _ruff_preamble {
+    Here could be some documentation for the namespace.
+  }
 
 # -------------------------------------------------
 # IterateFile
@@ -959,6 +960,25 @@ proc ListLibraries {} {
 # Library
 #
 proc library {LibraryName {PathToLib ""}} {
+  # Set the active VHDL library to *LibraryName* (working library).
+  #
+  #  LibraryName - Name of the active VHDL library.
+  #  PathToLib - If not specified, use the library directory specified by :ref:`RUFF/osvvm/SetLibraryDirectory`. |br|
+  #
+  # If a VHDL library named *LibraryName* doesn't exist, create a new VHDL library *LibraryName* in the specified
+  # library directory.
+  #
+  # This command influences how :ref:`RUFF/osvvm/analyze` behaves.
+  #
+  # .. todo::
+  #
+  #    * Make *LibraryName* found in library directory specified by path the active library.
+  #
+  # .. seealso::
+  #
+  #    * :ref:`RUFF/osvvm/SetLibraryDirectory`
+  #    * :ref:`RUFF/osvvm/GetLibraryDirectory`
+  #
   variable VhdlWorkingLibrary
   variable LibraryList
   variable VhdlLibraryFullPath
@@ -1089,26 +1109,27 @@ proc LinkCurrentLibraries {} {
 #
 proc analyze {FileName args} {
   # Analyze an HDL source file.
-	#
+  #
   #  FileName - Path to the HDL source file.
   #  args     - Further options.
-	#
-	# This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used
-	# analyze option depend on the current context. For example the use VHDL library this source file and its design units
-	# are compiled into, depend on the last [library] call.
-	#
-	# **Procedures influencing the context for the `analyze` command:**
-	#
-	# * [library] - set the VHDl working library
-	# * [SetVHDLVersion] - tbd
-	# * [SetExtendedAnalyzeOptions] - tbd
-	# * [SetVhdlAnalyzeOptions] - tbd
-	#
+  #
+  # This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used
+  # analyze option depend on the current context. For example the use VHDL library this source file and its design units
+  # are compiled into, depend on the last [library] call.
+  #
+  # **Procedures influencing the context for the `analyze` command:**
+  #
+  # * [library] - set the VHDL working library
+  # * [SetVHDLVersion] - tbd
+  # * [SetExtendedAnalyzeOptions] - tbd
+  # * [SetVhdlAnalyzeOptions] - tbd
+  #
   # **Supported HDL sourcefile languages:**
-	# * VHDL `*.vhd`/`*.vhdl`
-	# * Verilog `*.v`
-	# * SystemVerilog `*.sv`
-  variable AnalyzeErrorCount 
+  # * VHDL `*.vhd`/`*.vhdl`
+  # * Verilog `*.v`
+  # * SystemVerilog `*.sv`
+  #
+  variable AnalyzeErrorCount
   variable AnalyzeErrorStopCount
   variable ConsecutiveAnalyzeErrors 
 
@@ -1473,7 +1494,7 @@ proc RunTest {FileName {SimName ""} args} {
   puts "RunTest $RunArgs"               ; # EchoOsvvmCmd
   set CompoundCommand TRUE
 
-	if {$SimName eq ""} {
+  if {$SimName eq ""} {
     set SimName [file rootname [file tail $FileName]]
     TestName $SimName
   } else {
@@ -1807,13 +1828,35 @@ proc GetSimulatorResolution {} {
 # SetLibraryDirectory
 #
 proc SetLibraryDirectory {{LibraryDirectory "."}} {
+  # Set the directory into which VHDL libraries will be created.
+  #
+  #  LibraryDirectory - Directory to use. |br| If not set, use :ref:`UG/Concepts/CurrentSimulationDirectory`. |br|
+  #
+  # By default, VHDL libraries are created in :file:`<LibraryDirectory>/VHDL_LIBS/<tool version>/`.
+  #
+  # This command influences how :ref:`RUFF/osvvm/library` behaves.
+  #
+  # .. seealso::
+  #
+  #    * :ref:`RUFF/osvvm/library`
+  #    * :ref:`RUFF/osvvm/GetLibraryDirectory`
+  #
   variable VhdlLibraryParentDirectory
 
   set VhdlLibraryParentDirectory [file normalize $LibraryDirectory]
-
 }
 
 proc GetLibraryDirectory {} {
+  # Get the Library directory.
+  #
+  # Returns the directory into which VHDL libraries will be created. |br|
+  # If not modified by :ref:`RUFF/osvvm/SetLibraryDirectory` it defaults to :file:`<LibraryDirectory>/VHDL_LIBS/<tool version>/`.
+  #
+  # .. seealso::
+  #
+  #    * :ref:`RUFF/osvvm/library`
+  #    * :ref:`RUFF/osvvm/SetLibraryDirectory`
+  #
   variable VhdlLibraryParentDirectory
 
   if {[info exists VhdlLibraryParentDirectory]} {

doc/CoSim/PCIe.rst

@@ -0,0 +1,4 @@
+.. _COSIM/PCIe:
+
+PCIe
+####

doc/CoSim/index.rst

@@ -0,0 +1,4 @@
+.. _COMSIM:
+
+Co-Simulation
+#############

doc/Glossary.rst

@@ -3,8 +3,52 @@ Glossary
 
 .. glossary::
 
-   OSVVM
+   GTKWave
      tbd
 
-   TCL
+     .. rubric:: Further reading
+
+     * GitHub: https://github.com/gtkwave/gtkwave
+     * Website: https://gtkwave.github.io/gtkwave/ |br| https://gtkwave.sourceforge.net/
+
+   MIT
+     **M**\ odel **I**\ ndependent **T**\ ransactions
+
+     * :ref:`MIT`
+
+   OSVVM
+     **O**\ pen-**S**\ ource **V**\ HDL **V**\ erification **M**\ ethodology
+
+     .. rubric:: Further reading
+
+     * GitHub: https://github.com/OSVVM/OsvvmLibraries
+     * Website: https://osvvm.github.io/
+
+   Surfer
      tbd
+
+     .. rubric:: Further reading
+
+     * Website: https://surfer-project.org/
+
+   Tcl
+     **T**\ ool **C**\ ommand **L**\ anguage
+
+     .. rubric:: Further reading
+
+     * Wikipedia: https://en.wikipedia.org/wiki/Tcl
+     * Website: https://www.tcl-lang.org/
+
+   VC
+     **V**\ erification **C**\ omponent
+
+   VTI
+     **V**\ irtual **T**\ ransaction **I**\ nterface
+
+   YAML
+     **Y**\ AML **A**\ in't **M**\ arkup **L**\ anguage
+
+     .. rubric:: Further reading
+
+     * Wikipedia: https://en.wikipedia.org/wiki/YAML
+     * Website: https://yaml.org/

doc/Installation.rst

@@ -3,17 +3,114 @@
 Installation/Updates
 ####################
 
-Clone OSVVM Libraries
-*********************
+.. image:: https://img.shields.io/badge/OSVVM-OSVVM--Scripts-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333
+   :alt: Sourcecode on GitHub
+   :height: 22
+   :target: https://github.com/OSVVM/OSVVM-Scripts
+.. image:: https://img.shields.io/github/v/tag/OSVVM/OsvvmLibraries
+   :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest
+   :alt: GitHub Release
+
+OSVVM is hosted and developed at https://github.com/OSVVM. It's components are split into multiple Git repositories,
+which can be used individually or as a group. The all-in-one repository is called
+`OsvvmLibraries <https://github.com/OSVVM/OsvvmLibraries>`__. **OSVVM-Scripts** is part of **OsvvmLibraries**.
+
+See :ref:`INSTALL/Download` for downloadable archives.
+
+
+.. _INSTALL/Clone:
+
+Clone OsvvmLibraries
+********************
+
+OsvvmLibraries aggregates all OSVVM repositories into a single parent repository, which has OSVVM's components
+registered as Git submodules. |br|
+When cloning ensure to append the ``–recursive`` flag.
+
+.. code-block:: bash
+
+   git clone --recursive https://github.com/OSVVM/OsvvmLibraries.git
+
+.. seealso::
+
+   Git Documentation: `git clone <https://git-scm.com/docs/git-clone>`__
+
+
+.. _INSTALL/Submodule:
+
+Register OsvvmLibraries as Git Submodule
+****************************************
+
+Usually, OSVVM will be part of a bigger HDL project structure also maintained in Git. Therefore, it's best to integrate
+OSVVM as a submodule into that project. The following commands assume, OSVVM gets added into ``./lib/OsvvmLibraries``.
+
+.. code-block:: bash
+
+   cd <project>/lib
+   git submodule add https://github.com/OSVVM/OsvvmLibraries.git
+   git submodule update --init --recursive
+
+.. seealso::
+
+   Git Documentation: `git submodule add <https://git-scm.com/docs/git-submodule>`__
+
+
+.. _INSTALL/IndividualSubmodules:
+
+Register Individual VCs as Git Submodule
+****************************************
+
+.. todo::
+
+   describe individual submodule workflow
+
+
+.. _INSTALL/Updating:
+
+Updating OSVVM or OSVVM Components
+**********************************
+
+.. todo::
+
+   describe update process using Git
+
+
+.. _INSTALL/Download:
 
 Download OSVVM Libraries
 ************************
 
-OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page.
+.. image:: https://img.shields.io/github/v/release/OSVVM/OsvvmLibraries
+   :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest
+   :alt: GitHub Release
 
-On GitHub, all OSVVM libraries are a submodule of the repository OsvvmLibraries. Download all OSVVM libraries using
-``git clone`` with the ``–recursive`` flag:
+OsvvmLibraries is also offered as an archive at https://github.com/OSVVM/OsvvmLibraries/releases/latest
 
-.. code-block:: bash
+* ``https://github.com/OSVVM/OsvvmLibraries/releases/download/<version>/OsvvmLibraries-<version>.tar.gz``
+* ``https://github.com/OSVVM/OsvvmLibraries/releases/download/<version>/OsvvmLibraries-<version>.tar.zstd``
+* ``https://github.com/OSVVM/OsvvmLibraries/releases/download/<version>/OsvvmLibraries-<version>.zip``
+
+.. attention::
+
+   Downloading the archive provided by GitHub's source code download doesn't include the submodule's code. Therefore
+   OSVVM added a CI job for packaging all sources (incl. submodules) into a single archive.
+
+
+.. todo::
+
+   OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page.
+
+   `Downlaods from osvvm.org <https://osvvm.org/downloads>`__
+
+.. _INSTALL/BusinessContinuity:
+
+Business Continuity Planning
+****************************
+
+.. todo:
+
+   describe fork structure
 
-   git clone --recursive https://github.com/osvvm/OsvvmLibraries
+   1. fork on GitHub
+   2. mirror to local Git server (e.g. GitLab)
+   3. clone to local machine