Skip to content

armgit / BUI

Public Imported from GitHub
0

Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI

kit version

Preetham Pemmasani267be2060859
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 1bf4f3e..6703466 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -87,6 +87,10 @@ if(BUI_BUILD_TESTS)
add_executable(bui_theme_test tests/theme_test.c)
target_link_libraries(bui_theme_test PRIVATE bui::kit)
add_test(NAME bui_theme_test COMMAND bui_theme_test)
+ # the kit's version: header macros and the library agree
+ add_executable(bui_version_test tests/version_test.c)
+ target_link_libraries(bui_version_test PRIVATE bui::kit)
+ add_test(NAME bui_version_test COMMAND bui_version_test)
# images: every format, decode at size, the cache and loader, no leaks
add_executable(bui_image_test tests/image_test.c)
target_link_libraries(bui_image_test PRIVATE bui::kit)
diff --git a/bindings/python/src/buipy_kit.c b/bindings/python/src/buipy_kit.c
index b1d7856..da563de 100644
--- a/bindings/python/src/buipy_kit.c
+++ b/bindings/python/src/buipy_kit.c
@@ -1892,6 +1892,11 @@ static PyObject *kit_set_theme(PyObject *m, PyObject *arg)
Py_RETURN_NONE;
}
+static PyObject *kit_version(PyObject *m, PyObject *unused)
+{
+ return PyUnicode_FromString(BK_version_string());
+}
+
static PyObject *kit_theme_name(PyObject *m, PyObject *unused)
{
return PyUnicode_FromString(BK_theme_name());
@@ -2190,6 +2195,7 @@ static PyMethodDef kit_functions[] = {
{"kit_unit", kit_unit, METH_NOARGS, "U.widget_unit in pixels."},
{"kit_set_font", kit_set_font, METH_O, "UI font family."},
{"kit_set_theme", kit_set_theme, METH_O, "Theme: 'dark' (default) or 'light' (Blender's presets)."},
+ {"kit_version", kit_version, METH_NOARGS, "The kit's version, 'MAJOR.MINOR.PATCH' (the same as BUI's)."},
{"kit_theme_name", kit_theme_name, METH_NOARGS, "The active theme: 'dark' or 'light'."},
{"kit_theme_color", kit_theme_color, METH_O, "A theme color as (r, g, b, a) 0..1, e.g. 'region_bg', 'regular.inner'."},
{"kit_icon_names", kit_icon_names, METH_NOARGS, "All icon names."},
diff --git a/bindings/rust/blenderui-sys/src/lib.rs b/bindings/rust/blenderui-sys/src/lib.rs
index dce5a05..4a4c43e 100644
--- a/bindings/rust/blenderui-sys/src/lib.rs
+++ b/bindings/rust/blenderui-sys/src/lib.rs
@@ -225,6 +225,8 @@ unsafe extern "C" {
pub fn BK_set_font(family: *const c_char);
pub fn BK_set_theme(name: *const c_char) -> c_int;
pub fn BK_theme_name() -> *const c_char;
+ pub fn BK_version() -> c_int;
+ pub fn BK_version_string() -> *const c_char;
pub fn BK_theme_color(key: *const c_char, r_rgba: *mut c_float) -> c_int;
// nodes
diff --git a/bindings/rust/blenderui-sys/tests/version.rs b/bindings/rust/blenderui-sys/tests/version.rs
new file mode 100644
index 0000000..c56a528
--- /dev/null
+++ b/bindings/rust/blenderui-sys/tests/version.rs
@@ -0,0 +1,13 @@
+//! The kit's version is the crate's version: the header, the library and Cargo agree.
+
+use std::ffi::CStr;
+
+#[test]
+fn kit_version_is_the_crate_version() {
+ // SAFETY: the kit returns a static, NUL-terminated string.
+ let s = unsafe { CStr::from_ptr(blenderui_sys::BK_version_string()) }.to_str().unwrap();
+ assert_eq!(s, env!("CARGO_PKG_VERSION"));
+ let mut parts = s.split('.').map(|p| p.parse::<i32>().unwrap());
+ let number = parts.next().unwrap() * 10000 + parts.next().unwrap() * 100 + parts.next().unwrap();
+ assert_eq!(unsafe { blenderui_sys::BK_version() }, number);
+}
diff --git a/docs/c-api.md b/docs/c-api.md
index 7480fcc..c53eb0e 100644
--- a/docs/c-api.md
+++ b/docs/c-api.md
@@ -153,6 +153,36 @@ BK_video_free(v); /* after nodes / items let go */
video, the GPU renderers, the file browser) are CMake options from
`features.json`; see [Binary size](https://bui.preetham.top/docs/reference/binary-size/).
+## Versioning and stability
+
+The C API is versioned with BUI itself, as `MAJOR.MINOR.PATCH`. `BUI_kit.h` says which version it is, and the library reports its own:
+
+```c
+#include "BUI_kit.h"
+
+#if !BUI_KIT_VERSION_AT_LEAST(0, 4, 0)
+# error "BUI 0.4.0 or newer is required"
+#endif
+
+/* at run time, when the header and the library can differ (a shared build, a binding) */
+if (BK_version() != BUI_KIT_VERSION) {
+ fprintf(stderr, "BUI %s linked, header is %s\n", BK_version_string(), BUI_KIT_VERSION_STRING);
+}
+```
+
+The macros are `BUI_KIT_VERSION_MAJOR`, `_MINOR`, `_PATCH`, `BUI_KIT_VERSION_STRING` (`"0.4.0"`) and `BUI_KIT_VERSION` (one number: 0.4.0 is 400, 1.2.3 is 10203). The Python wheels, Rust crates and npm packages carry the same number, and a release is refused when any of them differs.
+
+**Before 1.0 there is no promise that the API stays the same.** Any release may add to it, and a release may change or remove a function. Every change that breaks existing code is listed under "C API changes" in `CHANGELOG.md`, with what to use instead. Pin a release number, not a commit.
+
+**From 1.0 on, semantic versioning:**
+
+- a MAJOR release may break the API;
+- a MINOR release only adds to it;
+- a PATCH release only fixes bugs;
+- a function marked `BUI_DEPRECATED` stays for at least one MINOR release, and the compiler warns where you use it.
+
+**ABI.** Nodes, contexts and the other handles are opaque and stay that way. The structs you fill in or read (`BKHost`, `BKMenuSpec`, `BKImageInfo`, `BKImageStats`, `BKCanvasItem`, `BKCustomEvent`) can gain fields before 1.0, so rebuild against the header of the library you link.
+
## Showing the kit in your own window
The kit always draws into a `BuiRaster`: the software raster, or Direct3D 11
diff --git a/kit/include/BUI_kit.h b/kit/include/BUI_kit.h
index d7a95a4..4a6d78a 100644
--- a/kit/include/BUI_kit.h
+++ b/kit/include/BUI_kit.h
@@ -16,10 +16,55 @@
#include "GPU_raster.h"
+/* ---- Version and stability ------------------------------------------------
+ *
+ * The C API is versioned with BUI itself, as MAJOR.MINOR.PATCH: this header,
+ * the Python wheels, the Rust crates and the npm packages all carry the same
+ * number (tools/check_versions.py fails a release when they differ).
+ *
+ * Before 1.0 there is no promise that the API stays the same: any release may
+ * add to it, and a release may change or remove a function. Every change that
+ * breaks existing code is listed under "C API changes" in CHANGELOG.md, with
+ * what to use instead. Pin a release, not a commit.
+ *
+ * From 1.0 on, semantic versioning: a MAJOR release may break the API, a MINOR
+ * release only adds to it, a PATCH release only fixes bugs, and a deprecated
+ * function (BUI_DEPRECATED) stays for at least one MINOR release.
+ *
+ * ABI: nodes, contexts and the other handles are opaque and stay that way. The
+ * structs you fill in or read (BKHost, BKMenuSpec, BKImageInfo, BKImageStats,
+ * BKCanvasItem, BKCustomEvent) can gain fields before 1.0, so rebuild against
+ * the header of the library you link. BK_version() reports the version of the
+ * library at run time; compare it with BUI_KIT_VERSION from this header when
+ * the two can differ (a shared build, a binding). */
+#define BUI_KIT_VERSION_MAJOR 0
+#define BUI_KIT_VERSION_MINOR 4
+#define BUI_KIT_VERSION_PATCH 0
+#define BUI_KIT_VERSION_STRING "0.4.0"
+/* One number to compare: 0.4.0 is 400, 1.2.3 is 10203. */
+#define BUI_KIT_VERSION \
+ (BUI_KIT_VERSION_MAJOR * 10000 + BUI_KIT_VERSION_MINOR * 100 + BUI_KIT_VERSION_PATCH)
+#define BUI_KIT_VERSION_AT_LEAST(major, minor, patch) \
+ (BUI_KIT_VERSION >= (major) * 10000 + (minor) * 100 + (patch))
+
+/* Marks a function that will be removed; the compiler warns where it is used. */
+#if defined(__GNUC__) || defined(__clang__)
+# define BUI_DEPRECATED(message) __attribute__((deprecated(message)))
+#elif defined(_MSC_VER)
+# define BUI_DEPRECATED(message) __declspec(deprecated(message))
+#else
+# define BUI_DEPRECATED(message)
+#endif
+
#ifdef __cplusplus
extern "C" {
#endif
+/* The version of the library you are linked against: BUI_KIT_VERSION as it was
+ * when the library was built, and the same as "MAJOR.MINOR.PATCH". */
+int BK_version(void);
+const char *BK_version_string(void);
+
typedef struct BKNode BKNode;
typedef struct BKContext BKContext;
typedef struct BKTreeItem BKTreeItem;
diff --git a/kit/intern/kit_core.c b/kit/intern/kit_core.c
index 3de02ee..1dbe6a5 100644
--- a/kit/intern/kit_core.c
+++ b/kit/intern/kit_core.c
@@ -1490,6 +1490,16 @@ int BK_set_theme(const char *name)
return 1;
}
+int BK_version(void)
+{
+ return BUI_KIT_VERSION;
+}
+
+const char *BK_version_string(void)
+{
+ return BUI_KIT_VERSION_STRING;
+}
+
const char *BK_theme_name(void)
{
bk_theme_env_init();
diff --git a/tests/version_test.c b/tests/version_test.c
new file mode 100644
index 0000000..02513f7
--- /dev/null
+++ b/tests/version_test.c
@@ -0,0 +1,35 @@
+/* The kit's version: the header's macros and the library agree, and they are
+ * well formed.
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later */
+
+#include <stdio.h>
+#include <string.h>
+
+#include "BUI_kit.h"
+
+static int g_fail = 0;
+#define CHECK(c) \
+ do { \
+ if (!(c)) { \
+ printf("FAIL %s:%d: %s\n", __FILE__, __LINE__, #c); \
+ g_fail = 1; \
+ } \
+ } while (0)
+
+int main(void)
+{
+ char expect[32];
+ snprintf(expect, sizeof(expect), "%d.%d.%d", BUI_KIT_VERSION_MAJOR, BUI_KIT_VERSION_MINOR,
+ BUI_KIT_VERSION_PATCH);
+ CHECK(strcmp(BUI_KIT_VERSION_STRING, expect) == 0); /* the string and the numbers agree */
+ CHECK(strcmp(BK_version_string(), BUI_KIT_VERSION_STRING) == 0);
+ CHECK(BK_version() == BUI_KIT_VERSION);
+ CHECK(BUI_KIT_VERSION_AT_LEAST(BUI_KIT_VERSION_MAJOR, BUI_KIT_VERSION_MINOR, BUI_KIT_VERSION_PATCH));
+ CHECK(!BUI_KIT_VERSION_AT_LEAST(BUI_KIT_VERSION_MAJOR + 1, 0, 0));
+ CHECK(BUI_KIT_VERSION_MINOR < 100 && BUI_KIT_VERSION_PATCH < 100); /* the number scheme holds */
+ if (!g_fail) {
+ printf("version test passed: %s\n", BK_version_string());
+ }
+ return g_fail;
+}
diff --git a/tools/bump_version.py b/tools/bump_version.py
index df47f08..2c2bac2 100644
--- a/tools/bump_version.py
+++ b/tools/bump_version.py
@@ -104,6 +104,13 @@ def plan_edits(new: str, npm: str | None) -> dict[Path, str]:
put(PY_VERSION, re.sub(r'(__version__\s*=\s*")[^"]+(")', rf"\g<1>{new}\g<2>", read(PY_VERSION)))
+ header = ROOT / "kit" / "include" / "BUI_kit.h"
+ htext = read(header)
+ for part, value in zip(("MAJOR", "MINOR", "PATCH"), new.split(".")):
+ htext = re.sub(rf"(#define BUI_KIT_VERSION_{part}\s+)\d+", rf"\g<1>{value}", htext)
+ htext = re.sub(r'(#define BUI_KIT_VERSION_STRING\s+")[^"]+(")', rf"\g<1>{new}\g<2>", htext)
+ put(header, htext)
+
ws = RUST / "Cargo.toml"
text = read(ws)
m = re.search(r"\[workspace\.package\](.*?)(?=^\[|\Z)", text, re.S | re.M)
diff --git a/tools/check_versions.py b/tools/check_versions.py
index 029fd8f..9976f4a 100644
--- a/tools/check_versions.py
+++ b/tools/check_versions.py
@@ -38,6 +38,14 @@ def main() -> int:
found["bindings/rust/Cargo.toml [workspace.package]"] = re.search(
r'^version\s*=\s*"([^"]+)"', read(RUST / "Cargo.toml"), re.M).group(1)
+ header = read(ROOT / "kit" / "include" / "BUI_kit.h")
+ parts = [re.search(rf"#define BUI_KIT_VERSION_{p}\s+(\d+)", header) for p in ("MAJOR", "MINOR", "PATCH")]
+ string = re.search(r'#define BUI_KIT_VERSION_STRING\s+"([^"]+)"', header)
+ if not all(parts) or not string:
+ sys.exit("kit/include/BUI_kit.h: the BUI_KIT_VERSION_* macros are missing or malformed")
+ found["kit/include/BUI_kit.h (numbers)"] = ".".join(p.group(1) for p in parts)
+ found["kit/include/BUI_kit.h (string)"] = string.group(1)
+
# the published crates name their siblings with an exact version
for crate in ("blenderui", "blenderui-macros", "blenderui-imgui", "blenderui-table", "blenderui-vlist", "blenderui-paint"):
text = read(RUST / crate / "Cargo.toml")
diff --git a/website/src/content/docs/c/c-api.mdx b/website/src/content/docs/c/c-api.mdx
index 4f8781b..f6ec5bf 100644
--- a/website/src/content/docs/c/c-api.mdx
+++ b/website/src/content/docs/c/c-api.mdx
@@ -266,6 +266,36 @@ BK_custom_set(node, &cls, my_data);
`BK_eval_number` is the same expression evaluator that lets Blender users type `2*pi` into a rotation field. Now your C program can, too. Your calculator app may feel threatened.
</Callout>
+## Versioning and stability
+
+The C API is versioned with BUI itself, as `MAJOR.MINOR.PATCH`. `BUI_kit.h` says which version it is, and the library reports its own:
+
+```c
+#include "BUI_kit.h"
+
+#if !BUI_KIT_VERSION_AT_LEAST(0, 4, 0)
+# error "BUI 0.4.0 or newer is required"
+#endif
+
+/* at run time, when the header and the library can differ (a shared build, a binding) */
+if (BK_version() != BUI_KIT_VERSION) {
+ fprintf(stderr, "BUI %s linked, header is %s\n", BK_version_string(), BUI_KIT_VERSION_STRING);
+}
+```
+
+The macros are `BUI_KIT_VERSION_MAJOR`, `_MINOR`, `_PATCH`, `BUI_KIT_VERSION_STRING` (`"0.4.0"`) and `BUI_KIT_VERSION` (one number: 0.4.0 is 400, 1.2.3 is 10203). The Python wheels, Rust crates and npm packages carry the same number, and a release is refused when any of them differs.
+
+**Before 1.0 there is no promise that the API stays the same.** Any release may add to it, and a release may change or remove a function. Every change that breaks existing code is listed under "C API changes" in `CHANGELOG.md`, with what to use instead. Pin a release number, not a commit.
+
+**From 1.0 on, semantic versioning:**
+
+- a MAJOR release may break the API;
+- a MINOR release only adds to it;
+- a PATCH release only fixes bugs;
+- a function marked `BUI_DEPRECATED` stays for at least one MINOR release, and the compiler warns where you use it.
+
+**ABI.** Nodes, contexts and the other handles are opaque and stay that way. The structs you fill in or read (`BKHost`, `BKMenuSpec`, `BKImageInfo`, `BKImageStats`, `BKCanvasItem`, `BKCustomEvent`) can gain fields before 1.0, so rebuild against the header of the library you link.
+
## Next steps
<CardGrid>