Add header files to examples and rename main.c

[umarcor]

As @RocketRoss commented in umarcor#3 (comment) (see also umarcor#4 (comment)):

Split ghdl.h > ghdl.h + ghdl.c

I think this point may be a bone of contention, but I also think that software people get quite concerned when they see function definitions in header files.

Currently, all of the examples in this repo use a single C source named main.c to contain all the required C resources (prototypes, definitions, types, etc.). This is done for simplicity, to ensure that including using a single additional file is enough. Precisely, the location of the header might need to be specified with -I (as in https://github.com/umarcor/ghdl-cosim/blob/header/vhpidirect/cinterface/demo/run.sh#L11).

Nonetheless, as @RocketRoss pointed out, this is not desirable from C language's point of view. On the one hand, files that do not contain a main should not be named main.c. Which filename should we use instead? user? helpers? vhpidirect? On the other hand, headers should be provided, which should include prototypes but not definitions.

We should explain in one of the most simple examples that writing everything in a single file is technically possible, but not good coding practice.

[radonnachie]

We should explain in one of the most simple examples that writing everything in a single file is technically possible, but not good coding practice.

Sure. I like that the examples engender best practices. It seems such a shame to spend so much effort to make them so thorough and thoroughly neat/uniform/explicit and yet have these glaring imperfections. 🤷

So:
The c files contain code external to ghdl, but this is the ghdl-cosim sector, so external.c and the like is not quite fair (it is external to ghdl and would be fairer in ghdl documentation).

I'll try list a few options my mind conjures up:
auxillary.c
supporting.c\supp.c
supplementary.c\supp.c
complementary.c\comp.c
extra.c
additional.c
cooperative.c\coop.c\co-op.c

I like co-op.c... that list is unfiltered. Maybe it sparks something more.

It feels a pain to have to get extra nitpicky in the examples (-I for the .h), but again, it'll really round off the efforts.

[umarcor]

I like aux.c. There are already a ghdl_extra and ghdlex, so I'd try to keep away from similar extra, external, example, etc. Also, I prefer short names, and aux feels easier to understand than supp, comp, or add. I like co-op, but I hate the location of - in my ISO-ES keyboard. Since we are working with "foreign interfaces", I think that int.c might fit too, but it'd be misleading with the integer type.

Shall we go with aux.c, unless there is a main? What should we do when there are a main and other helper functions in C? Use a single aux.c, a single main.c or both of them (and two corresponding headers)?

If we expand examples that currently have a single C file to be 4, we should consider calling GCC explicitly before GHDL, in order to merge all the C sources in a single object file. Then, GHDL would only need to pick that one. In fact, this is interesting because it shows when it is recommended to call GCC explicitly.

I like that the examples engender best practices.

I think that code sources of examples should engender best practices, so that anyone who copies that only, gets a good working solution. Nevertheless, for completeness, we can (and should) explain other options in the docs, which users might find when they search for GHDL examples in the wild.

It feels a pain to have to get extra nitpicky in the examples (-I for the .h), but again, it'll really round off the efforts.

I believe that -I won't be required for most cases. Depending on how the build/linking is done, it might be possible to use *.c sources only or to have headers automicatically picked from $(pwd). We just need to take care of explaining these details when used for the first time.

[radonnachie]

• aux.c Only auxillary functions (No header required right? Not even bad practice)
• main.c Only main()
• aux.c/h, main.c Auxillary functions and a main()

I only see at most 3 files needed?
👍

int.c might fit too, but it'd be misleading with the integer type

we should consider calling GCC explicitly before GHDL, in order to merge all the C sources in a single object

we can (and should) explain other options in the docs

I believe that -I won't be required for most cases.

need to take care of explaining these details when used for the first time

[umarcor]

@RocketRoss, see ghdl/ghdl@8346c71. Shall we use caux or auxc (and update #9 accordingly)?

[radonnachie]

Darn... How did you even catch that find from Monsieur TGingold 👀

I like caux.c a little more than auxc.c...engenders pyaux.py. Also, is then inline with TGingold's push.