Libelektra: Replace kdbproposal.h

[kodebach]

As noted in #2809 kdbproposal.h is not a good solution. It would be better to have a macro that enables experimental stuff. For example:

In our header (kdbfoo.h) we would have:

int elektraFoo (int x);

#ifdef ELEKTRA_EXPERIMENTAL

int elektraNewFoo(int x, int y);

#endif

To use the experimental symbols a user would write:

#define ELEKTRA_EXPERIMENTAL
#include <kdbfoo.h>

We could also use an integer similar to _POSIX_C_SOURCE to enable multiple different experimental versions. Then a user can opt in to only one experimental API and not automatically enable all future experimental APIs.

[markus2330]

Thank you for writing down the proposal!

I definitely agree that we need to get rid of libproposal. This is a must-have for 1.0.

How far we should go with include magic is a difficult question. If you combine your idea from here and from #2809 we could also build something like:

#define ELEKTRA_USE_VERSION 105
#include <elektra/kdb.h>

and then you get the symbols of elektra 1.5.*, either by #if or also #define for renames (e.g. signature changes), with an implementation in kdb.h like:

#if ELEKTRA_USE_VERSION >= 105
int symbol_defined_in_105()
#endif
#if ELEKTRA_USE_VERSION >= 103
#define old_name symbol_renamed_in_103
#endif

[markus2330]

@PhilippGackstatter What do you think of this proposal?

It would be important to get rid of libproposal for 1.0.

[PhilippGackstatter]

In our header (kdbfoo.h) we would have:

@kodebach wrote in #2809

`kdbproposal.h' is a bad solution. It is a different header file and therefore not forward compatible.

So would we have a different header or would the new APIs live in kdb.h and just behind some feature flag?

#define ELEKTRA_USE_VERSION 105
#include <elektra/kdb.h>

and then you get the symbols of elektra 1.5.*, either by #if or also #define for renames (e.g. signature changes), with an implementation in kdb.h like:

So this is for a user to opt in to the experimental apis for elektra 1.05, for example? I think it makes more sense to not use version numbers, as they don't really express what you opt in to. I'd rather use a feature name to make that clear on first glance

#define ELEKTRA_UNSTABLE_EXTERNAL_ITERATORS
#include <elektra/kdb.h>
// use external iterator

This would be very straigthforward and

a user can opt in to only one experimental API and not automatically enable all future experimental APIs.

[kodebach]

So would we have a different header or would the new APIs live in kdb.h and just behind some feature flag?

If it is in a different header, it should be included in kdb.h. The idea is that you don't have to change your #includes once a function becomes stable.

I'd rather use a feature name to make that clear on first glance

That is definitely a better idea

[PhilippGackstatter]

If it is in a different header, it should be included in kdb.h. The idea is that you don't have to change your #includes once a function becomes stable.

So we could just include kdbproposal.h into kdb.h, and then hide all the features behind flags. This way the experimental APIs would still live outside kdb.h.
Once we're stabilizing an API we can move it into kdb.h such that it is available without the flag. But for the users everything continues to work, except they wouldn't need the flag anymore.

[markus2330]

Yes, I also like the idea.

And actually no preparations for this are necessary?

For removing kdbproposals.h I created a new issue: #2993

[PhilippGackstatter]

@markus2330 Can you elaborate on what you want to do now?

What I suggested (and maybe failed to do so clearly) was to hide the experimental APIs behind feature flags in kdbproposal.h (so it wouldn't be removed). Then include that into kdb.h. Users only have to import kdb.h but can use the experimental APIs by using some #define ELEKTRA_UNSTABLE_EXTERNAL_ITERATORS or similar.

[markus2330]

Exactly. The idea is that we remove kdbproposal.h but when we introduce experimental features (or maybe even some features of #2993) we guard these prototypes with such experimental defines.

[markus2330]

My question was: do we need to modify kdb.h now so that we can later add such defines?

[PhilippGackstatter]

The idea is that we remove kdbproposal.h

So where (in what file) do the prototypes live? Directly in kdb.h?

// KDB methods
KDB * kdbOpen(Key *errorKey);
...

// Experimental APIs
#ifdef ELEKTRA_UNSTABLE_POP_AT_CURSOR
Key * ksPopAtCursor (KeySet * ks, cursor_t c);
#endif

My question was: do we need to modify kdb.h now so that we can later add such defines?

I think the anwer is no. It seems straightforward to me (as seen above), but I also haven't worked much with the preprocesor before, so maybe I'm missing something.

[markus2330]

So where (in what file) do the prototypes live? Directly in kdb.h?

Yes.

So we basically only need to fix docu in doc/todo/API to resolve this issue.

Should we require everything to go through experimental phases?

[kodebach]

Should we require everything to go through experimental phases?

If there is a possibility that the API changes in future, it should be made experimental. Straightforward things, like the proposed function to expose the meta Keyset, probably don't need an experimental phase.

[PhilippGackstatter]

Straightforward things, like the proposed function to expose the meta Keyset, probably don't need an experimental phase.

Yes I agree. I think this has to be decided on a case-by-case basis, but I would always tend towards introducing an API in an experimental phase first.

[markus2330]

Thank you for the input! I updated doc/todo/API

The resulting issue is #2993