Examples formatting Standards

[radonnachie]

Just to get a final word on the format standards of the examples.

/cc @umarcor

• All files end with an empty line.
• No trailing white spaces at the end of lines.
• Tabs (not spaces) size 4. (For now just be consistent within each file)
• VHDL files
  • Foreign attribute declaration in one line attribute foreign of getLogicVecBSize : function is "VHPIDIRECT getLogicVecBSize";.
  • Empty Lines between:
    • Sub/Type declarations
      • Keep types and their access types paired
    • Subprogram declarations
      • Keep subprogram declarations, definitions and their attribute declarations tightly grouped.
    • Variables, constants and signals groups
      • Group each similar declaration
  • Procedures and Function bodies end with more than just end; (at least end process/function;).
• Bash files (run.sh)
  • Two empty lines between sections within the compilation.
  • Echo a discription of the step before its execution
  • Pair the echo and the command without an empty line between
  • Empty line before Echoes
• C files
  • TBConfirmed
• File Naming (covers only the more basic examples, but can infer general preferences)
  • C files
    • main.c must contain a main()
    • VHPIDIRECT sources are caux.c
    • If there are both main.c and caux.c, provide appropriate caux.h (Add header files to examples and rename main.c #5)
  • VHDL files
    • Packages pkg in pkg.vhd
    • Entities ent in ent.vhd
    • Toplevel entity tb in tb.vhd
  • Build and run Bash files
    • run.sh

[umarcor]

• All files end with an empty line.
• No trailing white spaces at the end of lines.

I believe these can be easily configured on the editor.

Tabs (not spaces) size 4.

I think I normally use 2 spaces. However, it's ok to set it to 4. I can adapt.

Procedures and Function bodies end with just end;

Unlike other items, which are meant to make reading easier, this can have the opposite effect. Hence, I'm ok with changing it if you wish.

---

For C and shell scripts, I think we can add some linter to CI. For VHDL, we need to handle it in a best effort basis.

[radonnachie]

I quite like the idea of leaving the tab space as 2. I prefer tabs over spaces, but we'd just like each file to be consistent, so I won't ask you to change to tabs!

with just end;

I am feeling a small wish to have the end;s be more explicit. for the reason you mentioned.

some linter to CI.

Should I restrict the standards to vhdl files only then?

[umarcor]

I quite like the idea of leaving the tab space as 2. I prefer tabs over spaces, but we'd just like each file to be consistent, so I won't ask you to change to tabs!

I believe that I have set VSCode so it detects what's used. That's why I'm good as long as it is consistent per file 🤣 . However, when I write new files I always use 2, and I find it hard to refrain myself from removing half the indentation when I find 4...

I am feeling a small wish to have the end;s be more explicit. for the reason you mentioned.

Let's make them explicit. However, how explicit? For example, I think that entities and architectures support end;, end entity; and end entity name;. Processes accept the two later, as long as a label is provided. I think that just "try not to use end; only", is enough. And leave it up to the contributors to be little or very verbose.

Should I restrict the standards to vhdl files only then?

I'm not aware of any tools that can help us enforce the style rules that you listed for bash. The same applies to the file naming convention. Hence, for now, I think we need to keep all of what's already defined.

Regarding C, I'd really like to use some heavily opinionated linter/formatter, such as black for Python or golang's build-int gofmt. I believe that the best solution to spend little time discussing styling issues is to have a tool decide them for you. We should prioritize consistency, not preferences. Unfortunately, I have absolutely no idea about similar tools for C.

BTW, we might want to guess how to use Sphinx to document C sources (similar to doxygen). That would be specially interesting to show the header for the C interface as an API.

[radonnachie]

try not to use end; only

👍

I have researched Sphinx auto documenting C sources before. I can only imagine it coming in to play for the ghdl.h at the moment though. So I wouldn't say that it is pressing.
VScode has a VHDL formatter, but it capitilises keywords, and doesn't seem that customisable.

Let's try find a C formatter 👍

[umarcor]

I have researched Sphinx auto documenting C sources before. I can only imagine it coming in to play for the ghdl.h at the moment though. So I wouldn't say that it is pressing.

Agree. Once we have it ready for ghdl.h, we can investigate how to use it for other smaller files (such as the cinterface/intro). Nonetheless, it is not prioritary at all for now.

VScode has a VHDL formatter, but it capitilises keywords, and doesn't seem that customisable.

This is work in progress: GHDL (language-server), rust_hdl and PyVHDLParser. See jeremiah-c-leary/vhdl-style-guide#312 for a detailed discussion. AFAIK, there is no other open source VHDL parsing/analysis project which is expected to support VHDL 2008 and semantic analysis. There are lots of attempts, but the scope of most of them is limited to earlier versions of the standard. Others try to use parser generators such as ANTLR, but I believe that's a dead-end.

Regarding customisation, I don't mind it at all. I prefer consistency over customisation. I'm now proposing specific style guidelines because we need to have some so that new users (which are the target of these examples/docs) do not get distracted by format differences. Nevertheless, I'm open to drop all of them as soon as any tool decides for us.

Let's try find a C formatter 👍

I was having a quick look yesterday. It seems that clang-format might fit our needs. The docker container that we are using for tests includes GHDL with LLVM backend. Hence, part of the dependencies are already installed.