From b1e52381f5a2d1d77a6b82c570a9c013c2555f8e Mon Sep 17 00:00:00 2001 From: Jehan Date: Sun, 31 Aug 2025 17:18:32 +0200 Subject: [PATCH] libgimp*, plug-ins: add and use new GIMP_WARNING_API_BREAK() macro. This macro will generate a #warning message when we'll move on to 3.99 series (which means we will be on our way to GIMP 4). And it will become an #error message on 4.0.0, hence preventing us from releasing unless we actually resolve all these warnings. Resolution may mean actually breaking the API/ABI, or just deciding that it's not a good idea in the end, or finding another solution. But something will have to be decided. Please everyone use this macro when you discover issues where it looks like we could improve the API (in a breaking way) so that we don't forget when approaching GIMP 4 (pushing further the improvement). Updating the 2 place where I was already using a GIMP_CHECK_VERSION() with #warning, and adding a new usage in the compose plug-in, per discussion in MR !2424. --- libgimp/gimpvectorloadprocedure.c | 5 +-- libgimpbase/gimpmetadata.c | 5 +-- libgimpbase/gimpversion-private.h | 66 +++++++++++++++++++++++++++++++ plug-ins/common/compose.c | 2 + 4 files changed, 72 insertions(+), 6 deletions(-) create mode 100644 libgimpbase/gimpversion-private.h diff --git a/libgimp/gimpvectorloadprocedure.c b/libgimp/gimpvectorloadprocedure.c index 2cbfab60b4..87c9c6a4ba 100644 --- a/libgimp/gimpvectorloadprocedure.c +++ b/libgimp/gimpvectorloadprocedure.c @@ -24,6 +24,7 @@ #include "gimp.h" +#include "libgimpbase/gimpversion-private.h" #include "libgimpbase/gimpwire.h" /* FIXME kill this include */ #include "gimpvectorloadprocedure.h" @@ -132,9 +133,7 @@ gimp_vector_load_procedure_constructed (GObject *object) FALSE, G_PARAM_READWRITE); -#if GIMP_CHECK_VERSION(3, 99, 0) -#warning Make per-coordinate x/y pixel density. Simplify plug-ins/common/file-svg.c code when not keeping ratio. -#endif + GIMP_WARNING_API_BREAK("Make per-coordinate x/y pixel density. Simplify plug-ins/common/file-svg.c code when not keeping ratio.") /* Note: the "pixel-density" is saved in pixels per inch. "physical-unit" * property is only there for display. diff --git a/libgimpbase/gimpmetadata.c b/libgimpbase/gimpmetadata.c index ca31fc5e3e..d466512853 100644 --- a/libgimpbase/gimpmetadata.c +++ b/libgimpbase/gimpmetadata.c @@ -28,6 +28,7 @@ #include #include +#include "libgimpbase/gimpversion-private.h" #include "libgimpmath/gimpmath.h" #include "gimpbasetypes.h" @@ -41,9 +42,7 @@ #include "libgimp/libgimp-intl.h" -#if GIMP_CHECK_VERSION(3, 99, 0) -#warning libgimpbase/gimpmetadata.h: rename GIMP_METADATA_SAVE_UPDATE as GIMP_METADATA_UPDATE? -#endif +GIMP_WARNING_API_BREAK("libgimpbase/gimpmetadata.h: rename GIMP_METADATA_SAVE_UPDATE as GIMP_METADATA_UPDATE?") /** * SECTION: gimpmetadata diff --git a/libgimpbase/gimpversion-private.h b/libgimpbase/gimpversion-private.h new file mode 100644 index 0000000000..3482281f19 --- /dev/null +++ b/libgimpbase/gimpversion-private.h @@ -0,0 +1,66 @@ +/* LIBGIMP - The GIMP Library + * Copyright (C) 1995-1997 Peter Mattis and Spencer Kimball + * + * gimpversion-private.h + * Copyright (C) 2025 Jehan + * + * This library is free software: you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 3 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library. If not, see + * . + */ + +#ifndef __GIMP_VERSION_PRIVATE_H__ +#define __GIMP_VERSION_PRIVATE_H__ + +#include + +G_BEGIN_DECLS + +/** + * GIMP_WARNING_API_BREAK: + * @message: the message to output either as build WARNING or ERROR. + * + * Internal macro to use when we consider an API break, so that we don't + * forget to look at it when the time comes: + * + * - When the minor version reaches 99 (e.g. 3.99), the message will be + * outputted as a compilation warning. + * - When the minor and micro versions are 0.0 (e.g. 4.0.0), the message + * will be outputted as compilation error, hence forbidding a major + * release unless we resolve all the API break warnings (in any way, + * it can be by actually breaking the API, or by deciding that this is + * not a valid change anymore). + * + * Note: this macro relies on the "GCC warning" pragma which was tested + * to work on clang too. Assuming/hoping it works on other compilers. + **/ + +#if GIMP_CHECK_VERSION(GIMP_MAJOR_VERSION, 99, 0) + #define GIMP_PRAGMA(pragma) _Pragma(#pragma) + #define GIMP_WARNING_MSG(message) GIMP_PRAGMA(GCC warning #message) + + #define GIMP_WARNING_API_BREAK(message) GIMP_WARNING_MSG(message) +#elif GIMP_MINOR_VERSION == 0 && GIMP_MICRO_VERSION == 0 + #define GIMP_PRAGMA(pragma) _Pragma(#pragma) + #define GIMP_ERROR_MSG(message) GIMP_PRAGMA(GCC error #message) + + #define GIMP_WARNING_API_BREAK(message) \ + GIMP_ERROR_MSG("API break warning needs to be handled before releasing: " message) +#else + #define GIMP_WARNING_API_BREAK(message) +#endif + + +G_END_DECLS + +#endif /* __GIMP_VERSION_PRIVATE_H__ */ diff --git a/plug-ins/common/compose.c b/plug-ins/common/compose.c index e03bdbcbe2..e0ca83f6b0 100644 --- a/plug-ins/common/compose.c +++ b/plug-ins/common/compose.c @@ -41,6 +41,7 @@ #include #include +#include "libgimpbase/gimpversion-private.h" #include "libgimp/stdplugins-intl.h" @@ -1036,6 +1037,7 @@ compose (const gchar *compose_type, } } + GIMP_WARNING_API_BREAK("Update 'decompose-type' choices? See discussion in MR !2424.") /* TODO: The strings used in decompose.c's "decompose-type" do not match * the values of compose_type for YCbCr values. We'll need to wait until * the next API break to fix. For now, we can do additional checks if the