[PATCH libgpiod 0/7] build: detach the libgpiod API version from the libgpiod package version

[PATCH libgpiod 0/7] build: detach the libgpiod API version from the libgpiod package version

[Bartosz Golaszewski]

The versioning of libgpiod has become quite messy due to the rapid
evolution of the project in its initial stages (which forced an ABI
version change without bumping the API) and later extension with several
bindings and tools kept in the same repository.

Currently the library API version and the package version are the same
but we're at a stage where the core C API will most likely remain quite
stable but we're still extending other features of the project, like
the DBus API, tools and possibly other bindings. Bumping the C API
version because we added new features to included programs makes no
sense so this series proposes to detach the core C API version from the
libgpiod package version (except for the major version updates but I
don't expect there to be one anytime soon).

The core C API will also apply to C++ and GLib bindings as they track
the C API closely. Rust and Python bindings already have their own API
versions.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
Bartosz Golaszewski (7):
      bindings: cxx: move misc.hpp inclusion to the correct place
      build: define a separate API version for the core C library
      core: change the behavior of gpiod_api_version()
      tests: update library API version string tests
      tools: display C API *and* libgpiod package version for '-v'
      dbus: manager: display C API *and* libgpiod package version for '-v'
      dbus: gpiocli: display the libgpiod package version for --version

 bindings/cxx/gpiod.hpp                 | 1 +
 bindings/cxx/gpiodcxx/line-request.hpp | 2 --
 bindings/cxx/tests/tests-misc.cpp      | 2 +-
 bindings/glib/tests/tests-misc.c       | 2 +-
 bindings/python/tests/tests_module.py  | 2 +-
 configure.ac                           | 4 ++++
 dbus/client/gpiocli.c                  | 2 +-
 dbus/manager/gpio-manager.c            | 5 +++--
 lib/misc.c                             | 2 +-
 tests/tests-misc.c                     | 2 +-
 tools/tools-common.c                   | 3 ++-
 11 files changed, 16 insertions(+), 11 deletions(-)
---
base-commit: d0006cc3d57b0e8fe090a1596934340c34e69ab4
change-id: 20250901-api-version-detach-67d8e984d529

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

[PATCH libgpiod 1/7] bindings: cxx: move misc.hpp inclusion to the correct place

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

The symbols from gpiodcxx/misc.hpp are correctly exported to users of
gpiod.hpp because it's implicitly pulled in by line-request.hpp but
that's incorrect: line-request.hpp has no need for any of the symbols
from misc.hpp and it should be part of the set of headers included by
the top-level gpiod.hpp. Move it to the correct place.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 bindings/cxx/gpiod.hpp                 | 1 +
 bindings/cxx/gpiodcxx/line-request.hpp | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/bindings/cxx/gpiod.hpp b/bindings/cxx/gpiod.hpp
index 606994dd606a19d63bfcccff90fdce972148397f..c5fda421ffadad83f5f7dd1e60eed1de55354095 100644
--- a/bindings/cxx/gpiod.hpp
+++ b/bindings/cxx/gpiod.hpp
@@ -35,6 +35,7 @@
 #include "gpiodcxx/line-info.hpp"
 #include "gpiodcxx/line-request.hpp"
 #include "gpiodcxx/line-settings.hpp"
+#include "gpiodcxx/misc.hpp"
 #include "gpiodcxx/request-builder.hpp"
 #include "gpiodcxx/request-config.hpp"
 #undef __LIBGPIOD_GPIOD_CXX_INSIDE__
diff --git a/bindings/cxx/gpiodcxx/line-request.hpp b/bindings/cxx/gpiodcxx/line-request.hpp
index 96050191317f1790c6322d93439af6f93bcbd960..e41f31a115ce86d469236f33730112333a495519 100644
--- a/bindings/cxx/gpiodcxx/line-request.hpp
+++ b/bindings/cxx/gpiodcxx/line-request.hpp
@@ -17,8 +17,6 @@
 #include <iostream>
 #include <memory>
 
-#include "misc.hpp"
-
 namespace gpiod {
 
 class chip;

-- 
2.48.1

[PATCH libgpiod 2/7] build: define a separate API version for the core C library

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

The core C API of libgpiod has become quite stable and unlikely to
change soon. We will still be adding some new features to the included
programs and some of the bindings (notably: Python and Rust) but it
doesn't make sense to bump the C API which hasn't changed, just becuase
we're doing a minor release of the larger package.

Define a separate libgpiod C API version in configure.ac. This will
affect the C, C++ and GLib APIs as the latter two track the C API
closely. Rust and Python bindings already have their own API versions.

Set the API version to v2.2.0 as it hasn't changed in the libgpiod v2.3
release cycle yet.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 configure.ac | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/configure.ac b/configure.ac
index fe9673904c5ffcda2c7aa6783b28a93793a01c0c..4d4996053dafcbf95c60ba1396910fec4826ad7e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -35,6 +35,10 @@ AC_SUBST(ABI_GPIOSIM_VERSION, [1.1.0])
 # ... and another one for GLib bindings:
 AC_SUBST(ABI_GLIB_VERSION, [1.0.0])
 
+# Core libgpiod API version.
+AC_SUBST(API_VERSION, [2.2.0])
+AC_DEFINE_UNQUOTED([GPIOD_API_VERSION_STR], ["$API_VERSION"], [Library API version string.])
+
 AC_CONFIG_AUX_DIR([autostuff])
 AC_CONFIG_MACRO_DIRS([m4])
 AM_INIT_AUTOMAKE([foreign subdir-objects])

-- 
2.48.1

[PATCH libgpiod 3/7] core: change the behavior of gpiod_api_version()

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Make gpiod_api_version() return the human-readable form of the libgpiod
C API instead of the libgpiod package version.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 lib/misc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/misc.c b/lib/misc.c
index e109f8086b4c22edccfb5e88b89e4bf2fac4feee..33d68379032f6dfdc17d40c13ac08a5d911dc93f 100644
--- a/lib/misc.c
+++ b/lib/misc.c
@@ -12,5 +12,5 @@ GPIOD_API bool gpiod_is_gpiochip_device(const char *path)
 
 GPIOD_API const char *gpiod_api_version(void)
 {
-	return GPIOD_VERSION_STR;
+	return GPIOD_API_VERSION_STR;
 }

-- 
2.48.1

[PATCH libgpiod 4/7] tests: update library API version string tests

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

The version string returned by gpiod_api_version() is now stricter and
will always be of the form: x.y.z where x, y and z are unsigned integer
numbers. We no longer have to parse various suffixes so update the test
cases tree-wide.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 bindings/cxx/tests/tests-misc.cpp     | 2 +-
 bindings/glib/tests/tests-misc.c      | 2 +-
 bindings/python/tests/tests_module.py | 2 +-
 tests/tests-misc.c                    | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/bindings/cxx/tests/tests-misc.cpp b/bindings/cxx/tests/tests-misc.cpp
index 33fc3faf029d7969f547f5c528abee6bd9f02020..8fef2e18f9dd494cdd0818bd3d2225111a869871 100644
--- a/bindings/cxx/tests/tests-misc.cpp
+++ b/bindings/cxx/tests/tests-misc.cpp
@@ -71,7 +71,7 @@ TEST_CASE("api_version() returns a valid API version", "[misc]")
 	SECTION("check api_version() format")
 	{
 		REQUIRE_THAT(::gpiod::api_version(),
-			     regex_matcher("^\\d+\\.\\d+(\\.\\d+|\\-devel|\\-rc\\d+)?$"));
+			     regex_matcher("^\\d+\\.\\d+\\.\\d+"));
 	}
 }
 
diff --git a/bindings/glib/tests/tests-misc.c b/bindings/glib/tests/tests-misc.c
index 356e408ec4c2240bb2211d2a064f85794da625fa..37f9d6849f9f8dc7155cc22d51dd5bda8bc5e4c2 100644
--- a/bindings/glib/tests/tests-misc.c
+++ b/bindings/glib/tests/tests-misc.c
@@ -56,7 +56,7 @@ GPIOD_TEST_CASE(is_gpiochip_link_good)
 
 GPIOD_TEST_CASE(version_string)
 {
-	static const gchar *const pattern = "^\\d+\\.\\d+(\\.\\d+|\\-devel|\\-rc\\d+)?$";
+	static const gchar *const pattern = "^\\d+\\.\\d+\\.\\d+";
 
 	g_autoptr(GError) err = NULL;
 	g_autoptr(GRegex) regex = NULL;
diff --git a/bindings/python/tests/tests_module.py b/bindings/python/tests/tests_module.py
index 7120c6346ba4666adb250d0880d5777dbb7666ea..406bfe7c4c486bce34848246e2e58ce028cfde4a 100644
--- a/bindings/python/tests/tests_module.py
+++ b/bindings/python/tests/tests_module.py
@@ -50,7 +50,7 @@ class IsGPIOChip(TestCase):
 
 
 class VersionString(TestCase):
-    VERSION_PATTERN = "^\\d+\\.\\d+(\\.\\d+|\\-devel|\\-rc\\d+)?$"
+    VERSION_PATTERN = "^\\d+\\.\\d+\\.\\d+$"
 
     def test_api_version_string(self) -> None:
         self.assertRegex(gpiod.api_version, VersionString.VERSION_PATTERN)
diff --git a/tests/tests-misc.c b/tests/tests-misc.c
index 9d4f3dedbae6f0e415d85be52d7b47dad01cce43..00f3272d2ebc199801792209b428503912b97309 100644
--- a/tests/tests-misc.c
+++ b/tests/tests-misc.c
@@ -68,7 +68,7 @@ GPIOD_TEST_CASE(is_gpiochip_null_path)
 
 GPIOD_TEST_CASE(version_string)
 {
-	static const gchar *const pattern = "^\\d+\\.\\d+(\\.\\d+|\\-devel|\\-rc\\d+)?$";
+	static const gchar *const pattern = "^\\d+\\.\\d+\\.\\d+";
 
 	g_autoptr(GError) err = NULL;
 	g_autoptr(GRegex) regex = NULL;

-- 
2.48.1

[PATCH libgpiod 5/7] tools: display C API *and* libgpiod package version for '-v'

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

With the recent changes to the versioning scheme and the disassociation
of the core C API from the libgpiod package version, it now makes sense
to display both in the output of '<tool> --version' for all gpio-tools.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 tools/tools-common.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/tools-common.c b/tools/tools-common.c
index a684fcbd22eb32ccc822b83d5bf96fa9b976a9e9..8c2d5bc055ce48982d45d667aa975ec14cffc925 100644
--- a/tools/tools-common.c
+++ b/tools/tools-common.c
@@ -93,7 +93,8 @@ void die_perror(const char *fmt, ...)
 
 void print_version(void)
 {
-	printf("%s (libgpiod) v%s\n", get_prog_short_name(), gpiod_api_version());
+	printf("%s v%s (libgpiod v%s)\n",
+	       get_prog_short_name(), GPIOD_VERSION_STR, gpiod_api_version());
 	printf("Copyright (C) 2017-2023 Bartosz Golaszewski\n");
 	printf("License: GPL-2.0-or-later\n");
 	printf("This is free software: you are free to change and redistribute it.\n");

-- 
2.48.1

[PATCH libgpiod 6/7] dbus: manager: display C API *and* libgpiod package version for '-v'

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

With the recent changes to the versioning scheme and the disassociation
of the core C API from the libgpiod package version, it now makes sense
to display both in the output of 'gpio-manager --version'.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 dbus/manager/gpio-manager.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/dbus/manager/gpio-manager.c b/dbus/manager/gpio-manager.c
index 03ca7ab828e4f7ca57ca992f244a0c0afeb5b6a9..3aaf1c9f5480645382d35a11e790faa806de66b5 100644
--- a/dbus/manager/gpio-manager.c
+++ b/dbus/manager/gpio-manager.c
@@ -77,8 +77,9 @@ static void on_name_lost(GDBusConnection *con,
 
 static void print_version_and_exit(void)
 {
-	g_print("%s (libgpiod) v%s\nD-Bus API version: %d\n",
-		g_get_prgname(), gpiodglib_api_version(), GPIODBUS_API_VERSION);
+	g_print("%s v%s (libgpiod v%s)\nD-Bus API version: %d\n",
+		g_get_prgname(), GPIOD_VERSION_STR,
+		gpiodglib_api_version(), GPIODBUS_API_VERSION);
 
 	exit(EXIT_SUCCESS);
 }

-- 
2.48.1

[PATCH libgpiod 7/7] dbus: gpiocli: display the libgpiod package version for --version

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Currently gpiocli does not display the libgpiod API version in the
output of gpiocli --version because it's not linked against libgpiod -
it's only a consumer of the DBus API.

However, with the recent changes to the versioning scheme and the
disassociation of the core C API from the libgpiod package version, it
now makes sense to display the latter so add it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
---
 dbus/client/gpiocli.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dbus/client/gpiocli.c b/dbus/client/gpiocli.c
index 26d641be570b0508d87dee1c17e197b2ccff2d7d..4ab5d3f9bb24f0d1cdef20e369ab00de097a4674 100644
--- a/dbus/client/gpiocli.c
+++ b/dbus/client/gpiocli.c
@@ -116,7 +116,7 @@ static gchar *make_description(void)
 
 static void show_version_and_exit(void)
 {
-	g_print("gpiocli (libgpiod) v%s\nD-Bus API version: %d\n",
+	g_print("gpiocli v%s\nD-Bus API version: %d\n",
 		GPIOD_VERSION_STR, GPIODBUS_API_VERSION);
 
 	exit(EXIT_SUCCESS);

-- 
2.48.1

Re: [PATCH libgpiod 0/7] build: detach the libgpiod API version from the libgpiod package version

[Erik Schilling]

On Wed Sep 3, 2025 at 3:01 PM CEST, Bartosz Golaszewski wrote:
> The versioning of libgpiod has become quite messy due to the rapid
> evolution of the project in its initial stages (which forced an ABI
> version change without bumping the API) and later extension with several
> bindings and tools kept in the same repository.
>
> Currently the library API version and the package version are the same
> but we're at a stage where the core C API will most likely remain quite
> stable but we're still extending other features of the project, like
> the DBus API, tools and possibly other bindings. Bumping the C API
> version because we added new features to included programs makes no
> sense so this series proposes to detach the core C API version from the
> libgpiod package version (except for the major version updates but I
> don't expect there to be one anytime soon).
>
> The core C API will also apply to C++ and GLib bindings as they track
> the C API closely. Rust and Python bindings already have their own API
> versions.
>
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
> ---
> Bartosz Golaszewski (7):
>       bindings: cxx: move misc.hpp inclusion to the correct place
>       build: define a separate API version for the core C library
>       core: change the behavior of gpiod_api_version()
>       tests: update library API version string tests
>       tools: display C API *and* libgpiod package version for '-v'
>       dbus: manager: display C API *and* libgpiod package version for '-v'
>       dbus: gpiocli: display the libgpiod package version for --version
>
>  bindings/cxx/gpiod.hpp                 | 1 +
>  bindings/cxx/gpiodcxx/line-request.hpp | 2 --
>  bindings/cxx/tests/tests-misc.cpp      | 2 +-
>  bindings/glib/tests/tests-misc.c       | 2 +-
>  bindings/python/tests/tests_module.py  | 2 +-
>  configure.ac                           | 4 ++++
>  dbus/client/gpiocli.c                  | 2 +-
>  dbus/manager/gpio-manager.c            | 5 +++--
>  lib/misc.c                             | 2 +-
>  tests/tests-misc.c                     | 2 +-
>  tools/tools-common.c                   | 3 ++-
>  11 files changed, 16 insertions(+), 11 deletions(-)
> ---
> base-commit: d0006cc3d57b0e8fe090a1596934340c34e69ab4
> change-id: 20250901-api-version-detach-67d8e984d529
>
> Best regards,
> -- 
> Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Looks reasonable to me!

Acked-by: Erik Wierich <erik@riscstar.com>