Re: Getting libgnome* into shape

[Martin Baulig <martin home-of-linux org>]

Michael Meeks <michael ximian com> writes:

>         Yes I understand that perhaps for Gnome 2.0 we will need to link
> to libgnome1-compat everywhere - but I hold out high hopes that while we
> will never ( possible _ever_ cf. your allusion to X ) be able to change
> the Gnome 2.0 core APIs - we _will_ be able to change the applications on
> top for Gnome 2.0.1 2.0.2, 2.2, 2.3 etc. to progressively remove any
> libgnome1-compat staleness.
> 
>         Of course - if we glup the whole load of cruft together - we're
> just scuppered forever; not clever.

We'll also have the problem that - starting with the libgnome 2.0.0 tarball -
we need to keep binary compatibility in all subsequent releases. This also
means that there won't be any chance to remove any of the deprecated methods,
even if it's not used anywhere anymore. So having them in the core library
means that they'll have to stay there until GNOME 3.

> > Another thing is that we do drop some stuff on the way to libgnome/ui
> > from libcompat.  And it will be easier to drop things in the future
> > this way. Not to mention that it reduces the work in maintaining the
> > thing by quite a bit.
> 
>         Not at all, I think it just allows evil hacks with using
> deprecated code internaly, and kills some of the cleanliness of separation
> of stale crud into another module - this seems to be happening already. Of
> course, it's always far easier to pile vile hack on vile hack - sometimes
> it's even quicker; but it's not good for the long term.

There are also two hidden dangers which are both hard to detect:

a) "Using the internals I of a non-deprecated widget X in deprecated code Y"

   If Y is used frequently, there's the hidden danger that X may be missing
   some accessor functions which you need to use it efficiently - and if you
   only use Y but not X, it may even mean that X is unusable without I because
   there are problems in its design.

   Having a non-deprecated widget X means that - whatever you want to do with X -
   it must be possible without accessing its internals directly, but only using
   its public API.

   If this fails, there's almost certainly a problem with X's design.

While a) is in most cases fixable by adding one or two new new functions to the
frozen library, b) is much worse:

b) "Using a subset D the public or private API of a deprecated widget Y in the
    implementation I of a non-deprecated widget X".

   IMO this is a very serious bug with severity CRITICAL if not even BLOCKER.

   If Y is deprecated, then there was a reason for this - and it also means that Y
   will go away at some point in the future. This means, that at some point in the
   future, you'll need to change I in a way that it doesn't use D anymore - but
   without changing X, because that's a public API.

   There are three cases:

     bi) D has been replaced with a new public and non-deprecated widget Z.

         In this case, it should be possible to rewrite I to use Z - but this may or
         may not work without doing binary incompatible changes to X.

         Example: You're using GnomeDialog in a non-deprecated widget, can be fixed by
                  using GtkDialog.

     bii) D is an internal feature of Y and "Y without D" is not deprecated.

          => this is case a) for the widget Y  -- a parts of Y's public API has
                                                  been removed, but it may not be
                                                  possible to use Y without it.

         Example: Use're sucking out the GtkEntry's text directly - can be fixed by
                  using the accessor function.

     biii) Same as bii), but D was removed because it doesn't exist anymore, isn't
           used anymore or was a very bad design.

           If X relies on D, there's the hidden danger that X may be deprecated as
           well but that this hasn't been detected in time.

         Example: Use of GNOME 1.x's sound API in non-deprecated code.

         Example (worse): A non-deprecated public API which uses the GNOME 1.x sound
                          API in its implementation.

   Basically, if you're using a deprecated API in X's implementation - then X can't
   be part of the public GNOME 2.0 API - it's either deprecated as well or unfinished
   and immature.

> > We have release gnome-libs 1.x.  That is a supported API.  We have
> > repeatadly said we will fully support this API.
> 
>         That's just nonsense - in no way do we 'fully support this API'
> and you know it - what tripe :-) there are loads of minor changes to be
> made to port to Gnome 2.0. It'd be a really nice argument if it was true
> though.

Same here, I fully agree with Michael.

To make things even worse: there are even APIs which were already deprecated in
GNOME 1.4.x. Now, from GNOME 1.x to GNOME 2.0, we're making a major API change -
and the next chance to remove all this stuff will be GNOME 3.

> > We cannot, in order to have some holy grail of clean APIs, screw over
> > the developers.
> 
>         And this is the reason for the libgnome1-compat library - please
> engage with the real arguments.

There's also a big difference between helping developers by supporting all the
old APIs and confusing and screwing new developers away by having more than one
non-deprecated API for any given feature.

A good example for this is this config stuff which George committed to libgnome
and which I reverted again:

George added back the GNOME 1.x version gnome-config.[ch] and a new gnome-gconf.[ch]
and said these were both non-deprecated APIs.

This was a major change to the whole GNOME 2 platform since it's impact was that we
now have three non-deprecated config systems: gnome_config, bonobo-config and GConf,
what a mess !

The opposite of this was what I did yesterday: I reverted his mess and put back the
ditem moniker (but I'll move it into bonobo-config tomorrow for "political reasons").
This means that we now have the old situation again: there's only one non-deprecated
and recommended config system for GNOME 2.0 - bonobo-config.

And for "developer-level compatibility" (providing compatibility for application
developers), we have:

  * libgnome1-compat/libgnome/gnome-config.[ch]

    For compatibility with GNOME 1.x applications.
    This API will go away in near future.

  * GConf

    For compatibility with newer GNOME 1.4 applications like Nautilus.

    Since bonobo-config still uses GConf internally, there's also no need to port
    any existing code to use bonobo-config.

And for "user-level compatibility" (allowing users to read/write their old config
files), we have:

  * GConf

    None needed, bonobo-config uses the same format.

  * gnome-config

    My ditem moniker - will be in bonobo-config tomorrow, will be ready in a few days.

And this "user-level compatibility" works transparently with bonobo-config - if you
ported your application to use bonobo-config, you don't need to worry about "user-level
compatibility" - bonobo-config can do it for you.

[The recommended way to convert a GNOME 1.x config file to GNOME 2:

 * port your application to use bonobo-config.

 * have your application read all its old config files using my "ditem" moniker

 * have your application save all its config.

 * Done.
]

> > 1)  It's an implementation detail anyways.  This does not break the API.
> 
>         As long as there is no include gconf.h in the installed headers, I
> can cope with this with a whole load of mental screaming about horrendous
> lack of taste, and general brokenness; preferably no GErrors would be nice
> as well.
> 
> >     I thought we decided initially that we were going to use
> > bonobo-conf as a wrapper around gconf, but that gconf was going to be
> > a backend
> 
>         And indeed, that's how it should be used; so ?
> 
> > 2)  All three of us are a lot more comfortable with the gconf API
> 
>         Oh please; this is just feebleness. It may be slightly less taxing
> on the brain but it is a terminal evolutionary dead end; tragic.
> 
> > 3)  GConf is already required by the platform so if we have the
> >     "manifestly broken gconf C client headers" we'll have those anyway
> 
>         Yes - but there's no need to include them; make people explicitely
> ask to use broken code, don't give it to them by default.

One moment, this is more than an implementation detail:

We agreed that we'll use GConf as backend in bonobo-config - but I don't remember
that we made any constrains about how this should happen.

"Using GConf as backend in bonobo-config" - let's call it (*) - is what we agreed
upon - but for me this doesn't imply that all GNOME 2.0 apps need to depend on the
GConf client API.

To be more clear, IMO dropping the GConf C API and accessing the gconfd directly
from bonobo-config would conform with (*). Sure, this can't happen just from today
to tomorrow, but I won't see any problem with doing this between GNOME 2.x and
GNOME 2.(x+1).

As an implementation detail, bonobo-config's gconf moniker can be implemented
either as shared library or as external process. Changing this needs to happen
between 2.x and 2.(x+1), not between 2.x.y and 2.x.(y+1) - but it won't violate (*).

As another implementation detail, completely dropping GConf's C API and moving
the gconf moniker directly into the gconfd also won't violate (*).

As long as we only access GConf via bonobo-config, we have the flexibility to do
any of these things in a future 2.2, 2.3, .... release if we think it's appropriate.

Especially the last point - dropping GConf's C API and moving the moniker into the
gconfd - seems to correct way to go for me - but of course we don't have any time
to do it now - maybe it can happen for 2.1, maybe for 2.2, maybe for 2.3.

If you start using GConf directly in any of the core libraries, we won't be able to
do this anymore.

And it also makes it very hard to completely drop GConf in future - for instance
because in 1 year from now, there's a completely new config backend which is at
least as powerful as GConf, but which is also used by KDE - and imagine, how cool
it'd be if we were able to switch to this new backend with just a one-line change
in bonobo-config !

> > 4)  We are trying to get a stable library out sooner.  So it seems to
> >     me that adding an extra layer (and one that has NOT been tested
> >     out in the wild yet) seems not quite a way to go.
> 
>         Um - another way of looking at it might be to realise that the
> code is currently there - and it works; so there is no "adding an extra
> layer" - that's just bleating, you are effectively wasting time by
> changing things that don't need to be changed, and slowing down the
> release of a stable API. - But as Maintainer that is your perogative I
> suppose.

Well, we already had a stable and API frozen release - before you thawed it again.

> > We also need a help API.  We cannot have libraries with such large
> > missing holes.  We cannot release GNOME2 without a help API.  We must
> > remember the users, at least every once in a while.
> 
>         Ok - reasonable; however this doesn't sound like the most
> horrendously complicated thing to do - requiring 2 weeks work. AND as you
> are so fond of saying we must have 1000% compatibility with Gnome 1.4 so
> why don't we just copy the old gnome-help API ?: 2 minutes.

Didn't Havoc say that the next major GTK+ release (1.6.x or however it'll be called,
not the one which will go with GNOME 2, but the one from the next unstable/devel/stable
cycles) will contain a help API ?

> > For one widget?  Making more shared libs will just kill our startup
> > time.
> 
>         By privatizing I imply that the object should not be exposing its
> internals via public members; but instead using a private (opaque) data
> structure - to allow it to be changed in future without ABI breakage.
> Nothing to do with shared libraries.
> 
>         As Martin suggests - this API would be far more appropriate in
> gnome-games where it is actualy used.

Btw. if you have a look at the automake and libtool manual, there's an option to create
a non-installed shared library which will be linked into an executable. And just in case
you already forgot it - the "good old way" of creating a private .a file (a static
library) and linking it into an executable still exists in GNU/Linux :-)

And have you compiled gnome-scores.c and looked at the size of the .o file - I don't see
how a 434 lines C file can produce an object file which is so large that it can't be
statically linked into all games.

-- 
Martin Baulig
martin gnome org (private)
baulig suse de (work)