libghdl is broken and installed completely wrong

[Patrick Lehmann]

The list of complains is quite long, so let me try to structure all individual flaws, mistakes and bugs step-by-step. As a background: I'm a co-maintainer and developer at GHDL. I support GHDL for pyGHDL and using libghdl as standalone as well as providing vendor library compile scripts, helping with CI and make/compile scripts for MSYS2 and Windows.

All findings and investigations are also collected here: https://github.com/ghdl/ghdl/issues/2710

1. Multiple *.deb packages and parallel installs
------------------------------------------------
I noticed GHDL was split into multiple packages, so the user can decided on the GHDL backend as well having multiple backends in parallel. This is so far good, but a generic /usr/bin/ghdl is installed as a shell script to switch between backend.
1.1 The environment variable GHDL_BACKEND is not documented.
1.2 The internal exit code 2 is already used by GHDL. (If I'm right minimum 10 error codes are used by GHDL itself. For details and getting a free error code, it's recommended to contact the developers, but don't pick randomly a new exit code!
1.3 Why is alternatives not used to allow variant switching?

2. Unclear backend for libghdl
------------------------------
libghdl is also build for different backend. Thus, it's important which variant is installed.
2.1 The description in APT does not explain which backend is used by libghdl.
2.2 A user should be able to select the libghdl backend variant.
    Note: For using libghdl with pyGHDL, a libghdl with mcode backend is very suitable. Others
    might prefer the LLVM backend as it's faster, but produces *.o files and an executable on disk,
    while mcode runs completely in memory.

3. Missing header for libghdl
-----------------------------
3.1 When installing libghdl-dev, no libghdl header file is installed.
3.2 In reference to 2.*, each variant of libghdl might have different headers, due to varying APIs.
    Note: This should be checked with the developers if yes/no it's different and if it might happen in the future.
    Please also note: headers might be modified/constructed by ./configure e.g. for default paths, etc.

4. Headers in differing directories
-----------------------------------
4.1 Some headers are installed into /usr/include/ghdl, others to /usr/lib/ghdl/include
4.2 The VHPI and VPI headers are located in /usr/lib/ghdl/include/ghdl.
    The second ghdl needs to be removed.

5. Wrong installation space for ghdl1-llvm
------------------------------------------
ghdl1-llvm is a binary and should not be installed into /usr/lib

6. libghdl can't find it's pre-compiled VHDL source files
--------------------------------------------------------
libghdl is installed into /usr/lib/x86_64-linux-gnu.
6.1 The libghdl-4_1_0.so is not following the conventions of so files in Linux.
6.2 libghdl cannot find it's pre-compiled VHDL sources, because it was moved to a different directory without patching the paths.
6.3 If fixed, libghdl would share it's pre-compiled VHDL sources with ghdl itself. It's currently unsure if packages rules are setup to keep ghdl, libghdl, libghdl-dev in sync, otherwise ich backend variant and each version needs it's own pre-compiled VHDL source files.
6.4 If libghdl will be installed as libghdl-mcode and libghdl-llvm, how to switch *.so files, when alternatives isn't used?
    Note: It might be handy for users to use ghdl with LLVM backend and libghdl with mcode backend.

7. Missing pyGHDL
-----------------
The most popular reason for libghdl is the usage with pyGHDL as either pyGHDL.libghdl for low-level Python bindings to libghdl.so or with pyGHDL.DOM to get a VHDL CodeDOM (Code Document Object Model). The pyGDL version is tightly linked to the libghdl version and vise versa. So it's recommended to install pyGHDL with same GitHash as libghdl.

That said:
7.1 It should be part of libghdl or another package to install python3-pyGHDL 4.1.0 (depending on libghdl-mcode)

As a summary:
-------------
A) The packaging of GHDL as a binary is questionable (1.*, 5.*).
B) libghdl is completly broken and useless (2.*, 6.*).
C) I strongly believe libghdl was never used and tested.

Suggestions:
------------
a) Please rething if alternative switching shouldn't be done by alternatives. This could also have (independent) rules for libghdl.
   If not, fix the shell script and use a different return code.
b) Patch the libghdl-....so file name to follow Linux rules until GHDL has fixed it in it's makefiles.
c) Create at-least 2 variants of libghdl for mcode and llvm backends.
   GCC support will be dropped soon, so no need for libghdl-gcc. Moreover, GCC - like LLVM - creates *.o files, which is back for a Python in memory execution.
d) Fix the installation directory of ghdl1-llvm.
   See also cpp, which called by gcc and still present in /usr/bin
e) Check installation directory of libghdl. If directory needs to be /usr/lib/x86_64-linux-gnu, then you need to patch the relative paths to the pre-compiled sources.
   And/or request an update to the make files in GHDL if the current installation directory is wrong.
f) Check if all ghdl packages are synchronzed by rules, otherwise an update of ghdl-llvm will break the others due to shared src and vhdl directories.
g) Check if you want to offer a python3-pyGHDL package.