[Spice-devel] [protocol 0/3] Fixing the *_DEPRECATED set of macros

[Francois Gouget]

The following patch broke compilation of xf86-video-qxl:

commit b41220b1441b8adea6db9a98e9da1b43a8f426bb
Author: Christophe Fergeau <cfergeau at redhat.com>
Date:   Thu Mar 5 15:28:22 2015 +0100

    Mark unused public API methods/code as deprecated
    
    Acked-by: Jonathon Jongsma <jjongsma at redhat.com>


The reason is it introduces a #include <glib.h> in spice-server.h which 
is a *public* header! This means any application that needs to include 
spice-server.h, like xf86-video-qxl, must now check for GLib even if 
they don't use it, like xf86-video-qxl.

This does not make sense and thus the glib.h include must be removed. 
However it was added to get G_GNUC_DEPRECATED. Fortunately there is 
SPICE_GNUC_DEPRECATED, or maybe that's SPICE_DEPRECATED? It gets a bit 
confusing from here:

First the macros to tag deprecated functions:
* spice uses G_GNUC_DEPRECATED directly in spice-server.h as seen above.

* spice-gtk defines SPICE_DEPRECATED in spice-util.h as a wrapper around 
  G_GNUC_DEPRECATED, or an empty macro if SPICE_NO_DEPRECATED is 
  defined.

* spice-gtk also has a SPICE_GNUC_DEPRECATED_FOR() macro which is not 
  defined anywhere else and a corresponding wrapper, 
  SPICE_DEPRECATED_FOR(), which is a no-op if SPICE_NO_DEPRECATED is 
  defined.

* spice-protocol defines SPICE_GNUC_DEPRECATED in spice/macro.h but 
  uses the gcc __attribute__ macro directly instead of using 
  G_GNUC_DEPRECATED.


Second the macros to 'enable/disable' deprecated APIs:
* In spice-gtk defining SPICE_NO_DEPRECATED disables the warnings.

* In spice-protocol you must define SPICE_DEPRECATED to get access to 
  the deprecated vd_agent.h VD_AGENT_CLIPBOARD_MAX_SIZE_DEFAULT and 
  VD_AGENT_CLIPBOARD_MAX_SIZE_ENV macros.

Of course spice-gtk's source files use both spice-util.h and vd_agent.h, 
meaning they necessarily get the spice-protocol deprecated macros due to 
the SPICE_DEPRECATED naming conflict.


So here is the proposed solution:

* spice-protocol's SPICE_DEPRECATED is in a public header so keep it as 
  is. Extend it to mean the user wants to use deprecated APIs. This 
  includes:
  - Defining deprecated APIs and macros (as before).
  - Disabling warnings about the use of deprecated APIs so it takes 
    over spice-gtk's SPICE_NO_DEPRECATED role.

* Disable spice-protocol's SPICE_GNUC_DEPRECATED warnings when 
  SPICE_DEPRECATED is defined. 

* Add SPICE_GNUC_DEPRECATED_FOR() to spice-protocol next to 
  SPICE_GNUC_DEPRECATED.

* Extend spice-protocol's SPICE_GNUC_DEPRECATED to use G_GNUC_DEPRECATED 
  if available. This makes it a portable drop-in replacement for 
  G_GNUC_DEPRECATED in Spice's code, particularly in spice-server.h.

This implies spice and spice-gtk will need an up-to-date spice-protocol 
to compile.

-- 
Francois Gouget <fgouget at codeweavers.com>