doc: add use case of -frelaxed

[radonnachie]

Description

• Cleaned examples/ReadMe to reference quick start, then ghdl-cosim
• Added example use case of -frelaxed
  • from doc: add VHPIDIRECT demo #1059 comment by @umarcor >If you want to keep using shared variables but not protected types, and you want to use a generic in the package to set the size, I believe you can use --std=08 -frelaxed. That is done in https://github.com/VUnit/vunit/tree/master/examples/vhdl/array.
• added tag for foreign declarations

Related

• Part of concluding VHPIDIRECT, HDL_LOGIC_STATE/CHAR, C access example,  umarcor/ghdl#1

Hosted

• https://ghdl-rad.readthedocs.io/en/doc-addition/examples/README.html

❤️ Thank you!

[umarcor]

Currently, this PR conflicts with #1216, because doc/examples/README.rst is removed there. I decided to remove it because there are only VHPIDIRECT related examples/references ATM, and these are all moved to ghdl-cosim. If other examples are contributed in the future (PSL / formal verification, synthesis/PNR, https://ghdl.readthedocs.io/en/latest/development/Documentation.html...), the section can be added again. Nevertheless, I think that the content that you proposed to be added does fit in https://github.com/ghdl/ghdl-cosim/blob/master/doc/index.rst.

By the same token, the modification to Foreign.rst now corresponds to COSIM:VHPIDIRECT:Declarations in https://github.com/ghdl/ghdl-cosim/blob/master/doc/vhpidirect/declarations.rst.

I think that the addition in doc/examples/quick_start/README.rst is good.

[radonnachie]

So I'll move the changes in doc/examples/README.rst and in Foreign.rst to a ghdl-cosim/.../doc... PR?

[umarcor]

So I'll move the changes in doc/examples/README.rst and in Foreign.rst to a ghdl-cosim/.../doc... PR?

The change in Foreign.rst is not required (it'd be redundant with COSIM:VHPIDIRECT:Declarations). I would add the following (from your proposal) to https://github.com/ghdl/ghdl-cosim/blob/master/doc/index.rst as a hint:

It is suggested that users who are new to either GHDL or VHDL read, and execute, the examples in :ref:USING:QuickStart first.

The following sections contain advanced examples using specific features of the language, the tool,
or interaction with third-party projects.

[umarcor]

I just found that I had moved the comment to: https://ghdl.github.io/ghdl-cosim/vhpidirect/examples/index.html (https://github.com/ghdl/ghdl-cosim/blob/master/doc/vhpidirect/examples/index.rst). It's up to you to reword/relocate it.