Mercurial > ibis > ibis / file revision

/*
 * Ibis - IRCv3 Library
 * Copyright (C) 2022-2024 Ibis Developers
 *
 * Ibis is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * 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 2.1 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 <https://www.gnu.org/licenses/>.
 */

#if !defined(IBIS_GLOBAL_HEADER_INSIDE) && !defined(IBIS_COMPILATION)
# error "only <ibis.h> may be included directly"
#endif

#ifndef IBIS_VERSION_H
#define IBIS_VERSION_H

#include <glib.h>

#include "ibisversionconsts.h"

/* clang-format tries to remove the space after 'if', which confuses
 * gobject-introspection, so turn it off temporarily. */
/* clang-format off */
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
	!defined(IBIS_STATIC_COMPILATION)
/* clang-format on */
#define _IBIS_EXPORT __declspec(dllexport)
#define _IBIS_IMPORT __declspec(dllimport)
#elif __GNUC__ >= 4
#define _IBIS_EXPORT __attribute__((visibility("default")))
#define _IBIS_IMPORT
#else
#define _IBIS_EXPORT
#define _IBIS_IMPORT
#endif
#ifdef IBIS_COMPILATION
#define _IBIS_API _IBIS_EXPORT
#else
#define _IBIS_API _IBIS_IMPORT
#endif

#define _IBIS_EXTERN _IBIS_API extern

#ifdef IBIS_DISABLE_DEPRECATION_WARNINGS
#define IBIS_DEPRECATED _IBIS_EXTERN
#define IBIS_DEPRECATED_FOR(f) _IBIS_EXTERN
#define IBIS_UNAVAILABLE(maj, min) _IBIS_EXTERN
#define IBIS_UNAVAILABLE_STATIC_INLINE(maj, min)
#define IBIS_UNAVAILABLE_TYPE(maj, min)
#else
#define IBIS_DEPRECATED G_DEPRECATED _IBIS_EXTERN
#define IBIS_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f) _IBIS_EXTERN
#define IBIS_UNAVAILABLE(maj, min) G_UNAVAILABLE(maj, min) _IBIS_EXTERN
#define IBIS_UNAVAILABLE_STATIC_INLINE(maj, min) G_UNAVAILABLE(maj, min)
#define IBIS_UNAVAILABLE_TYPE(maj, min) G_UNAVAILABLE(maj, min)
#endif

/**
 * IBIS_VERSION_MIN_REQUIRED:
 *
 * A macro that should be defined by the user prior to including the `ibis.h`
 * header.
 *
 * The definition should be one of the predefined Ibis version macros:
 * %IBIS_VERSION_0_1, %IBIS_VERSION_0_2, ...
 *
 * This macro defines the earliest version of Ibis that the package is required
 * to be able to compile against.
 *
 * If the compiler is configured to warn about the use of deprecated functions,
 * then using functions that were deprecated in version
 * %IBIS_VERSION_MIN_REQUIRED or earlier will cause warnings (but using
 * functions deprecated in later releases will not).
 *
 * Since: 0.1
 */

/**
 * IBIS_VERSION_CUR_STABLE:
 *
 * A macro that evaluates to the current stable version of ibis, in a format
 * that can be used by the C pre-processor.
 *
 * Since: 0.1
 */
#define IBIS_VERSION_CUR_STABLE \
	(G_ENCODE_VERSION(IBIS_MAJOR_VERSION, IBIS_MINOR_VERSION))

#ifndef IBIS_VERSION_MIN_REQUIRED
#define IBIS_VERSION_MIN_REQUIRED (IBIS_VERSION_CUR_STABLE)
#elif IBIS_VERSION_MIN_REQUIRED == 0
#undef IBIS_VERSION_MIN_REQUIRED
#define IBIS_VERSION_MIN_REQUIRED (IBIS_VERSION_CUR_STABLE + 1)
#endif /* IBIS_VERSION_MIN_REQUIRED */

#if !defined(IBIS_VERSION_MAX_ALLOWED) || (IBIS_VERSION_MAX_ALLOWED == 0)
#undef IBIS_VERSION_MAX_ALLOWED
#define IBIS_VERSION_MAX_ALLOWED (IBIS_VERSION_CUR_STABLE)
#endif /* IBIS_VERSION_MAX_ALLOWED */

/* sanity checks */
#if IBIS_VERSION_MIN_REQUIRED > IBIS_VERSION_CUR_STABLE
#error "IBIS_VERSION_MIN_REQUIRED must be <= IBIS_VERSION_CUR_STABLE"
#endif
#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_MIN_REQUIRED
#error "IBIS_VERSION_MAX_ALLOWED must be >= IBIS_VERSION_MIN_REQUIRED"
#endif
#if IBIS_VERSION_MIN_REQUIRED < G_ENCODE_VERSION(0, 1)
#error "IBIS_VERSION_MIN_REQUIRED must be >= IBIS_VERSION_0_1"
#endif

#define IBIS_VAR _IBIS_EXTERN
#define IBIS_AVAILABLE_IN_ALL _IBIS_EXTERN

/**
 * IBIS_VERSION_0_1:
 *
 * A macro that evaluates to the 0.1 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.1
 */
#define IBIS_VERSION_0_1 (G_ENCODE_VERSION(0, 1))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_1
#define IBIS_AVAILABLE_IN_0_1 IBIS_UNAVAILABLE(0, 1)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_1 IBIS_UNAVAILABLE_STATIC_INLINE(0, 1)
#define IBIS_AVAILABLE_MACRO_IN_0_1 IBIS_UNAVAILABLE_MACRO(0, 1)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_1 IBIS_UNAVAILABLE_ENUMERATOR(0, 1)
#define IBIS_AVAILABLE_TYPE_IN_0_1 IBIS_UNAVAILABLE_TYPE(0, 1)
#else
#define IBIS_AVAILABLE_IN_0_1 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_1
#define IBIS_AVAILABLE_MACRO_IN_0_1
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_1
#define IBIS_AVAILABLE_TYPE_IN_0_1
#endif

/**
 * IBIS_VERSION_0_2:
 *
 * A macro that evaluates to the 0.2 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.2
 */
#define IBIS_VERSION_0_2 (G_ENCODE_VERSION(0, 2))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_2
#define IBIS_AVAILABLE_IN_0_2 IBIS_UNAVAILABLE(0, 2)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_2 IBIS_UNAVAILABLE_STATIC_INLINE(0, 2)
#define IBIS_AVAILABLE_MACRO_IN_0_2 IBIS_UNAVAILABLE_MACRO(0, 2)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_2 IBIS_UNAVAILABLE_ENUMERATOR(0, 2)
#define IBIS_AVAILABLE_TYPE_IN_0_2 IBIS_UNAVAILABLE_TYPE(0, 2)
#else
#define IBIS_AVAILABLE_IN_0_2 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_2
#define IBIS_AVAILABLE_MACRO_IN_0_2
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_2
#define IBIS_AVAILABLE_TYPE_IN_0_2
#endif

/**
 * IBIS_VERSION_0_3:
 *
 * A macro that evaluates to the 0.3 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.3
 */
#define IBIS_VERSION_0_3 (G_ENCODE_VERSION(0, 3))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_3
#define IBIS_AVAILABLE_IN_0_3 IBIS_UNAVAILABLE(0, 3)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_3 IBIS_UNAVAILABLE_STATIC_INLINE(0, 3)
#define IBIS_AVAILABLE_MACRO_IN_0_3 IBIS_UNAVAILABLE_MACRO(0, 3)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_3 IBIS_UNAVAILABLE_ENUMERATOR(0, 3)
#define IBIS_AVAILABLE_TYPE_IN_0_3 IBIS_UNAVAILABLE_TYPE(0, 3)
#else
#define IBIS_AVAILABLE_IN_0_3 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_3
#define IBIS_AVAILABLE_MACRO_IN_0_3
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_3
#define IBIS_AVAILABLE_TYPE_IN_0_3
#endif

/**
 * IBIS_VERSION_0_4:
 *
 * A macro that evaluates to the 0.4 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.4
 */
#define IBIS_VERSION_0_4 (G_ENCODE_VERSION(0, 4))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_4
#define IBIS_AVAILABLE_IN_0_4 IBIS_UNAVAILABLE(0, 4)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_4 IBIS_UNAVAILABLE_STATIC_INLINE(0, 4)
#define IBIS_AVAILABLE_MACRO_IN_0_4 IBIS_UNAVAILABLE_MACRO(0, 4)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_4 IBIS_UNAVAILABLE_ENUMERATOR(0, 4)
#define IBIS_AVAILABLE_TYPE_IN_0_4 IBIS_UNAVAILABLE_TYPE(0, 4)
#else
#define IBIS_AVAILABLE_IN_0_4 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_4
#define IBIS_AVAILABLE_MACRO_IN_0_4
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_4
#define IBIS_AVAILABLE_TYPE_IN_0_4
#endif

/**
 * IBIS_VERSION_0_5:
 *
 * A macro that evaluates to the 0.5 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.5
 */
#define IBIS_VERSION_0_5 (G_ENCODE_VERSION(0, 5))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_5
#define IBIS_AVAILABLE_IN_0_5 IBIS_UNAVAILABLE(0, 5)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_5 IBIS_UNAVAILABLE_STATIC_INLINE(0, 5)
#define IBIS_AVAILABLE_MACRO_IN_0_5 IBIS_UNAVAILABLE_MACRO(0, 5)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_5 IBIS_UNAVAILABLE_ENUMERATOR(0, 5)
#define IBIS_AVAILABLE_TYPE_IN_0_5 IBIS_UNAVAILABLE_TYPE(0, 5)
#else
#define IBIS_AVAILABLE_IN_0_5 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_5
#define IBIS_AVAILABLE_MACRO_IN_0_5
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_5
#define IBIS_AVAILABLE_TYPE_IN_0_5
#endif

/**
 * IBIS_VERSION_0_6:
 *
 * A macro that evaluates to the 0.6 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.6
 */
#define IBIS_VERSION_0_6 (G_ENCODE_VERSION(0, 6))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_6
#define IBIS_AVAILABLE_IN_0_6 IBIS_UNAVAILABLE(0, 6)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_6 IBIS_UNAVAILABLE_STATIC_INLINE(0, 6)
#define IBIS_AVAILABLE_MACRO_IN_0_6 IBIS_UNAVAILABLE_MACRO(0, 6)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_6 IBIS_UNAVAILABLE_ENUMERATOR(0, 6)
#define IBIS_AVAILABLE_TYPE_IN_0_6 IBIS_UNAVAILABLE_TYPE(0, 6)
#else
#define IBIS_AVAILABLE_IN_0_6 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_6
#define IBIS_AVAILABLE_MACRO_IN_0_6
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_6
#define IBIS_AVAILABLE_TYPE_IN_0_6
#endif

/**
 * IBIS_VERSION_0_7:
 *
 * A macro that evaluates to the 0.7 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.7
 */
#define IBIS_VERSION_0_7 (G_ENCODE_VERSION(0, 7))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_7
#define IBIS_AVAILABLE_IN_0_7 IBIS_UNAVAILABLE(0, 7)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_7 IBIS_UNAVAILABLE_STATIC_INLINE(0, 7)
#define IBIS_AVAILABLE_MACRO_IN_0_7 IBIS_UNAVAILABLE_MACRO(0, 7)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_7 IBIS_UNAVAILABLE_ENUMERATOR(0, 7)
#define IBIS_AVAILABLE_TYPE_IN_0_7 IBIS_UNAVAILABLE_TYPE(0, 7)
#else
#define IBIS_AVAILABLE_IN_0_7 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_7
#define IBIS_AVAILABLE_MACRO_IN_0_7
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_7
#define IBIS_AVAILABLE_TYPE_IN_0_7
#endif

/**
 * IBIS_VERSION_0_8:
 *
 * A macro that evaluates to the 0.8 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.8
 */
#define IBIS_VERSION_0_8 (G_ENCODE_VERSION(0, 8))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_8
#define IBIS_AVAILABLE_IN_0_8 IBIS_UNAVAILABLE(0, 8)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_8 IBIS_UNAVAILABLE_STATIC_INLINE(0, 8)
#define IBIS_AVAILABLE_MACRO_IN_0_8 IBIS_UNAVAILABLE_MACRO(0, 8)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_8 IBIS_UNAVAILABLE_ENUMERATOR(0, 8)
#define IBIS_AVAILABLE_TYPE_IN_0_8 IBIS_UNAVAILABLE_TYPE(0, 8)
#else
#define IBIS_AVAILABLE_IN_0_8 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_8
#define IBIS_AVAILABLE_MACRO_IN_0_8
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_8
#define IBIS_AVAILABLE_TYPE_IN_0_8
#endif

/**
 * IBIS_VERSION_0_9:
 *
 * A macro that evaluates to the 0.9 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.9
 */
#define IBIS_VERSION_0_9 (G_ENCODE_VERSION(0, 9))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_9
#define IBIS_AVAILABLE_IN_0_9 IBIS_UNAVAILABLE(0, 9)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_9 IBIS_UNAVAILABLE_STATIC_INLINE(0, 9)
#define IBIS_AVAILABLE_MACRO_IN_0_9 IBIS_UNAVAILABLE_MACRO(0, 9)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_9 IBIS_UNAVAILABLE_ENUMERATOR(0, 9)
#define IBIS_AVAILABLE_TYPE_IN_0_9 IBIS_UNAVAILABLE_TYPE(0, 9)
#else
#define IBIS_AVAILABLE_IN_0_9 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_9
#define IBIS_AVAILABLE_MACRO_IN_0_9
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_9
#define IBIS_AVAILABLE_TYPE_IN_0_9
#endif

/**
 * IBIS_VERSION_0_10:
 *
 * A macro that evaluates to the 0.10 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.10
 */
#define IBIS_VERSION_0_10 (G_ENCODE_VERSION(0, 10))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_10
#define IBIS_AVAILABLE_IN_0_10 IBIS_UNAVAILABLE(0, 10)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_10 IBIS_UNAVAILABLE_STATIC_INLINE(0, 10)
#define IBIS_AVAILABLE_MACRO_IN_0_10 IBIS_UNAVAILABLE_MACRO(0, 10)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_10 IBIS_UNAVAILABLE_ENUMERATOR(0, 10)
#define IBIS_AVAILABLE_TYPE_IN_0_10 IBIS_UNAVAILABLE_TYPE(0, 10)
#else
#define IBIS_AVAILABLE_IN_0_10 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_10
#define IBIS_AVAILABLE_MACRO_IN_0_10
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_10
#define IBIS_AVAILABLE_TYPE_IN_0_10
#endif

/**
 * IBIS_VERSION_0_11:
 *
 * A macro that evaluates to the 0.11 version of ibis, in a format that can be
 * used by the C pre-processor.
 *
 * Since: 0.11
 */
#define IBIS_VERSION_0_11 (G_ENCODE_VERSION(0, 11))

#if IBIS_VERSION_MAX_ALLOWED < IBIS_VERSION_0_11
#define IBIS_AVAILABLE_IN_0_11 IBIS_UNAVAILABLE(0, 11)
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_11 IBIS_UNAVAILABLE_STATIC_INLINE(0, 11)
#define IBIS_AVAILABLE_MACRO_IN_0_11 IBIS_UNAVAILABLE_MACRO(0, 11)
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_11 IBIS_UNAVAILABLE_ENUMERATOR(0, 11)
#define IBIS_AVAILABLE_TYPE_IN_0_11 IBIS_UNAVAILABLE_TYPE(0, 11)
#else
#define IBIS_AVAILABLE_IN_0_11 _IBIS_EXTERN
#define IBIS_AVAILABLE_STATIC_INLINE_IN_0_11
#define IBIS_AVAILABLE_MACRO_IN_0_11
#define IBIS_AVAILABLE_ENUMERATOR_IN_0_11
#define IBIS_AVAILABLE_TYPE_IN_0_11
#endif

G_BEGIN_DECLS

/**
 * IBIS_CHECK_VERSION:
 * @major: The major version to check for.
 * @minor: The minor version to check for.
 * @micro: The micro version to check for.
 *
 * Checks the version of ibis being compiled against. See [func@check_version]
 * for a runtime check.
 *
 * Returns: %TRUE if the version is the same or newer than the passed-in
 *          version.
 *
 * Since: 0.1
 */
#define IBIS_CHECK_VERSION(major, minor, micro) ((major) == IBIS_MAJOR_VERSION && \
                                                 ((minor) < IBIS_MINOR_VERSION || \
                                                  ((minor) == IBIS_MINOR_VERSION && (micro) <= IBIS_MICRO_VERSION)))

/**
 * ibis_check_version:
 * @required_major: the required major version.
 * @required_minor: the required minor version.
 * @required_micro: the required micro version.
 *
 * Checks that the ibis version is compatible with the requested version.
 *
 * Returns: %NULL if the versions are compatible, or a string describing
 *          the version mismatch if not compatible.
 *
 * Since: 0.1
 */
IBIS_AVAILABLE_IN_ALL
const char *ibis_check_version(guint required_major, guint required_minor, guint required_micro);

/**
 * ibis_version:
 *
 * The full version string of the running ibis.
 *
 * Since: 0.1
 */
IBIS_VAR const char *ibis_version;

/**
 * ibis_major_version:
 *
 * The major version of the running ibis. Contrast with #IBIS_MAJOR_VERSION,
 * which expands at compile time to the major version of ibis being compiled
 * against.
 *
 * Since: 0.1
 */
IBIS_VAR const guint ibis_major_version;

/**
 * ibis_minor_version:
 *
 * The minor version of the running ibis. Contrast with #IBIS_MINOR_VERSION,
 * which expands at compile time to the minor version of ibis being compiled
 * against.
 *
 * Since: 0.1
 */
IBIS_VAR const guint ibis_minor_version;

/**
 * ibis_micro_version:
 *
 * The micro version of the running ibis. Contrast with #IBIS_MICRO_VERSION,
 * which expands at compile time to the micro version of ibis being compiled
 * against.
 *
 * Since: 0.1
 */
IBIS_VAR const guint ibis_micro_version;

G_END_DECLS

#endif /* IBIS_VERSION_CONSTS_H */