Auto-generate VHDL LS `.toml` library configuration from OSVVM `.pro` files

[BekdoucheAmine]

Description
To my knowledge, integrating OSVVM libraries with the VS Code VHDL Language Server currently requires manually defining libraries and file paths in the .vhdl_ls.toml file.

Therefore, I propose a TCL-based solution (this could also be implemented in Python, but maintaining TCL preserves consistency with the existing OSVVM scripting workflow). The feature would parse OSVVM build.pro files recursively, starting from the main OsvvmLibraries.pro, and automatically generate the corresponding .toml library configuration for VS Code.

Motivation

• Reduce manual configuration for VHDL LS
• Ensure .toml always matches OSVVM build structure
• Improve developer onboarding and reproducibility
• Enable scalable integration as new OSVVM libraries are added

Proposed Behavior

• Parse the root OsvvmLibraries.pro file
• Recursively follow include directives
• Collect all analyzed VHDL source files
• Group files by library
• Generate or update .vhdl_ls.toml automatically

Example Workflow

1. Run the TCL setup script, which invokes the procedure responsible for generating or updating .vhdl_ls.toml.
2. The script parses the OSVVM .pro hierarchy recursively, resolving include, use, and analyze directives.
3. All discovered VHDL source files are grouped by library and written into .vhdl_ls.toml, keeping the VS Code VHDL LS configuration synchronized with the OSVVM build structure.

[JimLewis]

This is easier than you expect. No parsing required. In your simulator do the following.

# Load alternate meaning for OSVVM script API analyze (and all the others)
source $OsvvmLibraries/Scripts/VendorScripts_CompileList.tcl

# Run the script for which you want the information - such as all of OSVVM
build $OsvvmLibraries

# for each library, this produces a list of files in the file named: LibraryName_ToolName.files
# every time you run build, it appends to the files.

# to restore the original behavior of OSVVM scripts do:
StartUp

To change the file names and what is in them change the action in
VendorScripts_CompileList.tcl

# -------------------------------------------------
# analyze
#
proc vendor_analyze_vhdl {LibraryName FileName args} {

# put all files in the same file named OneList.files and normalize the file names
set AllFiles [open OneList.files a]
puts $AllFiles [file normalize $FileName]
close $AllFiles
}

proc vendor_analyze_verilog {LibraryName FileName args} {
# put all files in the same file named OneList.files
set AllFiles [open OneList.files a]
puts $AllFiles [file normalize $FileName]
close $AllFiles
}

[JimLewis]

If you like, copy VendorScripts_CompileList.tcl to something like VendorScripts_GenerateVhdlLsToml.tcl and update it so it creates the appropriate and then do a pull request.

[JimLewis]

It may be possible to create a function then that Generates the Toml

proc GenerateVhdlLsToml {FileToBuild} {
source $OsvvmLibraries/Scripts/VendorScripts_CompileList.tcl
build $FileToBuild
StartUp
}

[BekdoucheAmine]

Got it, thanks! I’ll try copying VendorScripts_CompileList.tcl to a new script and modify it to generate .vhdl_ls.toml. My plan is to test it using build $OsvvmLibraries and ensure the generated .toml matches the structure expected by VHDL LS.

Here’s a rough idea of what I’m thinking in TCL:

# Generate a '.toml' file in the top directory
# Could be copied to the working directory or used directly
# Avoids a single file with tons of appended builds
set AllFiles [open "../.vhdl_ls.toml" w]
# Will work on formatting to match VHDL LS '.toml' structure
puts $AllFiles [file normalize $FileName]
close $AllFiles

Once it’s working, I can open a pull request with the new script.

[JimLewis]

If relative paths work in the toml, please use relative paths - but if they are relative, where does toml require them to be relative to? OSVVM relative paths for files will be relative to the simulation directory.

[BekdoucheAmine]

Thanks for the suggestion. From my experience with Open Logic, the VHDL LS .toml file is generated in Python using a format like this:

[libraries.olo]
files = [
    'C:\Path\to\open-logic\src\base\vhdl\olo_base_pkg_attribute.vhd',
    ...
    'C:\Path\to\open-logic\3rdParty\en_cl_fix\hdl\en_cl_fix_resize.vhd',
]

For OSVVM, I prefer staying within a single scripting language (TCL) rather than introducing Python.

Regarding relative paths: yes, they can work in .toml, but they must be relative to the VS Code workspace root, not the simulator working directory. OSVVM naturally generates paths relative to the simulation directory, so normalize is needed.

Please correct me if I’m wrong, but my assumption is that anyone working with OSVVM typically keeps the library in a central location and runs simulations from a separate working folder.

[JimLewis]

No worries. Once we have one thing that works, it can be adjusted as needed.

I expect it to be different for different organizations - with some do it yourself and some we will manange it in a central repository for you.

[dbee-lumacron]

This is easier than you expect. No parsing required. In your simulator do the following.

Load alternate meaning for OSVVM script API analyze (and all the others) source $OsvvmLibraries/Scripts/VendorScripts_CompileList.tcl

This is a really handy mechanism! It doesn't look like it's documented anywhere in the scripting user guide or readme.

Will this get added to table of "toolVendor/ToolName" in 8.1?

Presumably, we can use this on our own .pro file hierarchy to convert to compile_order.txt etc.

[JimLewis]

@dbee-lumacron Are you looking for documentation on CompileList or the toml generator? CompileList is currently an undocumented experimental feature.

The toml generator is a work in progress. I need review the code and then do the pull request. Then we will add the documentation.

If it is the toml generator, be sure to let me know and I will be sure to do a pull request sooner.

The current toml generator points out that libraries can be referenced in a non-contiguous fashion. As a result, it does some complicated code to read and parse the libraries in the toml file. I think it could be improved by using a dictionary - and then do one write once the dictionary is built. This then could be the foundation for writing out in other formats.

[BekdoucheAmine]

@JimLewis I agree, the code could definitely be improved by using a dictionary and then writing everything out once it’s built. That would make it cleaner and easier to extend to other formats.

My initial goal was to get a working version in place first. If that’s not a concern, I’m happy to refactor it to use a dict-based approach instead.

[dbee-lumacron]

I was referring to CompileList - no problem if it's still experimental.

I'm also interested in the toml exporter. I had created a vivado compile list -> dictionary -> toml, but I haven't hooked OSVVM into the vivado projects.

I agree a tcl dictionary object would be beneficial - perhaps in the creation of FuseSoC .core files too.

[JimLewis]

@BekdoucheAmine Agreed. It is always best to get something working first.

I added some things to the #73 to help you with addressing some issues that will come up with that.

@dbee-lumacron I am hoping that what gets done here becomes the foundation for other projects - Vivado and Altera are high on my wish list. WRT FuseSoC, OSVVM scripts need conditionals based on tool and tool version to support VHDL-2008 and VHDL-2019 feature inclusion (or exclusion) as well as address some bugs (such as in XSIM).

[Paebbels]

@dbee-lumacron, @BekdoucheAmine is you want to get access to OSVVM's *.pro files in Python, you can use https://github.com/edaa-org/pyEDAA.OSVVM. It also gives access to OSVVM's *.yaml files from Python.