Stable API for libgbs

[mmitch]

Issue #41 has our first "customer" that seems to use libgbs as a library. So we probably need a stable API from now on.
I don't know if our API was stable over the last years – and if it was, I don't know if it was deliberately stable or rather by accident. At least i have until now never thought "I should not change this", it was more like "if it needs refactoring, just do it".

I think this task includes at least two aspects:

• define our API (perhaps provider extra header files for libgbs that are different from the ones used internally)
• add tests or a demo application that ensures stable operation of this API

This task relates strongly to issue #41 because with that issue a lot if internal changes and refactorings happen.
We either have to provide an extra compatibility layer to support the older, historical API or we make a cut and define a new API (probably with a version change to 1.0.0) and ensure compatibility from then on.

This issue is an invite for discussion :-)

[mmitch]

Can libgbs_whitelist.txt be considered our API definition?

[emoon]

Given that the API area is quite small I personally don't mind breaking changes that much as long as the version number indicates it (i.e bump of major version) it would be great to have a changelog.md or similar that describes what has changed tho and what is expected of the user to alter their code to get everything up and running again.

[mmitch]

Things I think of doing:

• create extra files for the API
• add a version indicator to the API files
• automatically create API documentation
• add an install target for --enable-sharedlibgbs (currently neither the library nor the header file get installed on make install)
  • oops, we do have that already!
  • update version number of lib in Linux?
  • install libgbs.h as well
  • register installed lib with pkg-config
• discuss and double-check all names
• use the API callbacks internally
• check if libgbs_whitelist.txt is still needed
• provide a sample application for documentation
• auto-build the sample application to ensure API compatibility
• add enum for Gameboy hardware types (currently a char* used to select the audio filter)
• check return types (currently we're on "everything is a long" when it could be a bool or an int as well)

This time, I will try to make smaller branches/Pull Requests or work directly on master.

[ranma]

check if libgbs_whitelist.txt is still needed

It was never technically fully needed, but it is a safety to not accidentally export more symbols than intended, since by default all public symbols are exported.
There is also an unused advanced feature for versioning in the linker config (you can actually do some api changes without renaming the lib): https://gcc.gnu.org/wiki/SymbolVersioning