New user, need an example project file

[aspdigital]

The subject says it all. I have no idea where to start with creating and maintaining a project file, starting with what it's supposed to be called and where it should live.

A simple example would be most helpful!

[GlenNicholls]

Reference the readme on the homepage for this repo https://github.com/VHDL-LS/rust_hdl_vscode

[GlenNicholls]

That contains an example, required file name, and the places (and priority) it will look for that file. I’m closing this, feel free to open a new issue if you run into issues with the info present in the readme.

[aspdigital]

But wait, the documentation is not clear. If it was I would not have asked.

Under [libraries] do I need to create an entry for work, as in work.files = [ 'top.vhdl', 'foo.vhdl' ], correct? If so, that part is not as "obvious" as Tom would like or you think.

Are there any other sections in the vhdl_ls.toml file that need to be defined?

[GlenNicholls]

@aspdigital I am honestly not sure about work, that is a good question and one @kraigher would be able to answer better. work should not be considered an actual library as the LRM considers it to be the currently compiled library to simplify self-library references without needing to know how the "outside" (scripts, tools, etc.) maps that code to an actual library. I'm simplifying, but that is the gist. Unfortunately, vendors treat that portion of the LRM differently than the intention in old implementations and have carried that legacy forward. With all of that said, work is not required in the TOML file.

As for how to define your top-level-like code like TBs, top-levels, etc., I would personally put them under a library like top, but work will likely work for that purpose as well as long as the other dependent libraries and whatnot are defined beforehand in the TOML. For reference, Vivado sim/synth puts code not mapped to a library under xil_defaultlib (unless you change the default in project settings) because VHDL is library-focused, and work can be confusing when used outside self-library references because it then holds multiple meanings. I don't have a good link to explain this further at the moment, but find a copy of the LRM and read through the descriptions of work and it should hopefully make more sense if I butchered the quick explanation.

For example, the below code is valid because the "work library" is implicit during the compilation of many sources compiled at the same time before the next library is declared. Many builtins like std are treated similarly, i.e. you don't have to declare library std; before using something from std like stop or many other utilities in that library/package. You can simply do use std.<whatever>; or in your code std.stop IIRC.

<"library work;" not declared here and that is completely valid>
use work.my_pkg.all;
...
ent_decl: my_ent
<new file starts here>
... -- OR similarly
ent_decl: entity work.my_ent

I think a better question here is how to define sources that do not belong to a library like a top-level or a testbench. My guess is the following is valid (I have not verified though):

# File names are either absolute or relative to the parent folder of the
# vhdl_ls.toml file and supports glob-style patterns.

[libraries]

# Defines library lib2
lib2.files = [
  'pkg2.vhd',
  'src/**/*.vhd',
]

# Defines library "work"
work.files = [
  'pkg1.vhd',
  'tb_ent.vhd',
]

I closed the issue because the question was not clear as the documentation (with the exception of the work not being thoroughly covered) covers everything about the TOML format. There is nothing else that the TOML requires for configuration. However, off the top of my head, I do not know how to declare sources that don't belong to a library. Again, I think @kraigher would need to clarify that. But, if you have a convention like xil_defaultlib, the language server will still be able to handle that as long as the compile order of the TOML is correct.

[aspdigital]

So to get back to my original question. I simply asked: "how do I tell the language server which files are in my project?"

Assuming most of the files are analyzed into the work directory, then my guess -- based on the skinny example in the readme.md -- is that I need to put an entry in vhdl_ls.toml in the [libraries] section as you "guessed" in your example above. If you're the maintainer or otherwise involved with the project, one would hope you would do more than "guess."

The documentation doesn't cover "everything about the TOML format." I asked, "Are there any other sections in the vhdl_ls.toml file that need to be defined?" and that is not a question about the TOML format, it's a question about what goes into the file. If the only entry in vhdl_ls.toml is a [libraries] section, that's fine, but just indicate that's the case.

[GlenNicholls]

Let's take a step back and I'll explain this a bit better.

So to get back to my original question. I simply asked: "how do I tell the language server which files are in my project?"

Let's assume the following project:

.
├── vhdl_ls.toml
├── constraints/
├── external/
│   ├── lib1/
│   │   └── f1.vhd
│   └── lib2/
│       └── f1.vhd
├── scripts/
├── src/
│   └── top.vhd
└── test/

The folder you open in VSCode for example is the workspace root that the readme references in item 3. In this example, we are opening the above example project at the project/repo root which is where the vhdl_ls.toml is. Assume the compile order is lib1/f1.vhd, lib2/f1.vhd, top.vhd. Our vhdl_ls.toml would then look like the following:

[libraries]

lib1.files = ['external/lib1/f1.vhd']

lib2.files = ['external/lib2/f1.vhd']

top.files = ['src/top.vhd']

You could change the top library name to anything. The point I was trying to make before is that projects usually have files that aren't associated with a library like a top-level, in this case, top.vhd. Vivado for example defaults to xil_defaultlib for files that aren't mapped to a library explicitly from the GUI or TCL. The part I was unsure of is if vhdl_ls.toml supports not specifying a library name. Since the readme doesn't specify this, my guess is no. But, it doesn't matter what library you put your top files in as long as you put all of them in the same "default" library if they're referencing each other.

EDIT: some simulators and other tools put VHDL files not in a library in work which is confusing. As I mention below, that is not the intention of work. If you want more details about this from people who maintain the LRM, you can ask at https://app.gitter.im/#/room/#vhdl_General:gitter.im

Assuming most of the files are analyzed into the work directory, then my guess -- based on the skinny example in the readme.md -- is that I need to put an entry in vhdl_ls.toml in the [libraries] section as you "guessed" in your example above.

The other point I was trying to make is that if you're referencing work in your code, you don't specify a work library. work is just a keyword for referencing other "objects" for the library/fileset that is currently being analyzed/compiled. So no, you don't need to put work.files in vhdl_ls.toml. If you do declare a work library in a VHDL project, work now has two meanings and can be confusing. As I mentioned, I don't know if vhdl_ls.toml will have issues with declaring a work library, I've never tried it because that's not what the intention for work is in the LRM. If you want to put your top files in work, feel free to give it a shot, and if you don't get errors/warnings then it's probably fine.

The documentation doesn't cover "everything about the TOML format." I asked, "Are there any other sections in the vhdl_ls.toml file that need to be defined?"

No. There is nothing else you define in vhdl_ls.toml other than libraries. Reference the rust_hdl example project.

---

If you're the maintainer or otherwise involved with the project, one would hope you would do more than "guess."

Just a contributor trying to help answer your questions. I closed the issue because I didn't see anything incorrect in the readme and this ended up turning into a discussion clarifying the usage of the tool. This, for future reference, can also be discussed at https://app.gitter.im/#/room/#VHDL-LS:matrix.org as well.

If you still believe there's an issue here, feel free to re-open and one of the maintainers can review it.

If the only entry in vhdl_ls.toml is a [libraries] section, that's fine, but just indicate that's the case.

The readme is the documentation for the tool currently, so it's expected you take it at face value. I see your point, I'm assuming the config will eventually have more options as the project matures. At that time, I would expect the readme will be updated with a table that describes the available config sections and how to use them.