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

published

Preetham Pemmasanid3c4fbd761b7
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
new file mode 100644
index 0000000..e25c0c4
--- /dev/null
+++ b/.github/workflows/wheels.yml
@@ -0,0 +1,120 @@
+# Build blenderui wheels + sdist, test them, and publish to PyPI on a tag.
+#
+# pull requests / pushes: build and test only
+# tag v* (e.g. v0.1.0): build, test, publish to PyPI (trusted publishing)
+# manual run: build, test, optionally publish to TestPyPI
+#
+# See docs/publishing.md for the one-time PyPI setup.
+
+name: wheels
+
+on:
+ push:
+ branches: [main]
+ tags: ["v*"]
+ pull_request:
+ workflow_dispatch:
+ inputs:
+ testpypi:
+ description: "Publish to TestPyPI"
+ type: boolean
+ default: false
+
+jobs:
+ wheels:
+ name: wheels (${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, windows-latest, macos-14, macos-13]
+ steps:
+ - uses: actions/checkout@v4
+
+ # Windows wheels are built with MinGW-w64 (UCRT) GCC: the toolchain the
+ # project is developed and tested with. The .pyd links the runtime
+ # statically and needs only system DLLs.
+ - name: MinGW-w64 (Windows)
+ if: runner.os == 'Windows'
+ id: msys2
+ uses: msys2/setup-msys2@v2
+ with:
+ msystem: UCRT64
+ install: mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make
+ path-type: inherit
+ - name: Put MinGW on PATH (Windows)
+ if: runner.os == 'Windows'
+ shell: bash
+ run: echo "${{ steps.msys2.outputs.msys2-location }}\\ucrt64\\bin" >> "$GITHUB_PATH"
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - name: Build and test wheels
+ run: |
+ python -m pip install "cibuildwheel>=3,<4"
+ python -m cibuildwheel --output-dir wheelhouse
+ env:
+ CIBW_ENVIRONMENT_WINDOWS: CMAKE_GENERATOR="MinGW Makefiles" CC=gcc CXX=g++
+ CIBW_ARCHS_MACOS: native
+ - uses: actions/upload-artifact@v4
+ with:
+ name: wheels-${{ matrix.os }}
+ path: wheelhouse/*.whl
+
+ sdist:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - run: |
+ python -m pip install build
+ python -m build --sdist
+ - uses: actions/upload-artifact@v4
+ with:
+ name: sdist
+ path: dist/*.tar.gz
+
+ # Full test suites on the source build (Windows: the native window host).
+ tests:
+ runs-on: windows-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - uses: msys2/setup-msys2@v2
+ id: msys2
+ with:
+ msystem: UCRT64
+ install: mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make
+ path-type: inherit
+ - shell: bash
+ run: |
+ export PATH="${{ steps.msys2.outputs.msys2-location }}/ucrt64/bin:$PATH"
+ cmake -S . -B build -G "MinGW Makefiles" -DPython3_EXECUTABLE="$(which python)"
+ cmake --build build -j 4
+ ctest --test-dir build --output-on-failure
+
+ publish:
+ needs: [wheels, sdist, tests]
+ if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && inputs.testpypi)
+ runs-on: ubuntu-latest
+ environment: ${{ startsWith(github.ref, 'refs/tags/v') && 'pypi' || 'testpypi' }}
+ permissions:
+ id-token: write # PyPI trusted publishing (no API token stored)
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ path: dist
+ merge-multiple: true
+ - name: Publish to PyPI
+ if: startsWith(github.ref, 'refs/tags/v')
+ uses: pypa/gh-action-pypi-publish@release/v1
+ - name: Publish to TestPyPI
+ if: "!startsWith(github.ref, 'refs/tags/v')"
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ repository-url: https://test.pypi.org/legacy/
diff --git a/.gitignore b/.gitignore
index 3a9d18e..fc4d5e5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,9 @@ build-ui/
*.obj
*.o
reference/
+
+# packaging
+dist/
+wheelhouse/
+*.egg-info/
+*.whl
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..cbddc09
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to **blenderui** (BUI). The format follows
+[Keep a Changelog](https://keepachangelog.com); versions follow
+[Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.1.0] - first release
+
+### Added
+- **C kit** (`kit/`): Blender's UI as a C runtime. It has the node tree,
+ Tk's packer and gridder in C, input and interaction (hover, drag grabs,
+ continuous cursor, menus, tooltips), widget drawing ported from Blender's
+ `interface_widgets.cc`, and damage-driven raster rendering. Also: undo and
+ redo, animation, the text area, canvas, scroll views, scrollbars and
+ multi-select.
+- **Native window host** for Windows (Win32): DPI-aware, vsync'd
+ animation, clipboard, cursors, window-manager features. Other platforms use
+ a stdlib-Tk-hosted window.
+- **`bui.tksyntax`**: the complete tkinter API (7846/7846 public names of
+ the tkinter and ttk classes), plus `ttk`, `messagebox`, `filedialog`,
+ `simpledialog`, `colorchooser`, `font` and `scrolledtext`. Run existing apps
+ unchanged with `python -m bui.tksyntax app.py`, `blenderui-tk app.py` or
+ `install()`.
+- **`bui.qtsyntax`**: a Qt-style API subset (widgets, layouts, signals,
+ `QPainter`, menus, timers).
+- **`bui.components`**: 45 Blender components (layouts, values, views,
+ menus, pie menus, the color picker, editors, templates).
+- Packaging as `blenderui` (scikit-build-core), with `import blenderui` as
+ an alias of `bui`.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5596087..dc1d0bd 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -9,7 +9,12 @@
# SPDX-License-Identifier: GPL-2.0-or-later
cmake_minimum_required(VERSION 3.20)
-project(bui LANGUAGES C CXX VERSION 0.1.0)
+
+# One version for the C library, the Python package and the PyPI wheel.
+file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/bindings/python/bui/_version.py" _bui_version_line
+ REGEX "^__version__")
+string(REGEX MATCH "[0-9]+[.][0-9]+[.][0-9]+" BUI_VERSION "${_bui_version_line}")
+project(bui LANGUAGES C CXX VERSION ${BUI_VERSION})
option(BUI_BUILD_TESTS "Build BUI test executables" ON)
option(BUI_BUILD_EXAMPLES "Build BUI example applications" OFF)
diff --git a/README.md b/README.md
index 4d7ccab..392c49e 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,10 @@ the color wheel, Ctrl+Z on any edit and you can drive it three ways:
All three share one C runtime (`kit/`). Python builds the widget tree and
runs your callbacks. Layout, input, drawing and presenting stay in C.
+```sh
+pip install blenderui # PyPI name (packaging is ready, first release pending)
+```
+
<p align="center">
<img src="docs/images/components.png" width="340" alt="Blender components">
<img src="docs/images/tkinter_items.png" width="300" alt="A plain tkinter program on BUI">
@@ -38,6 +42,8 @@ Right: an unmodified tkinter program (<code>examples/tk_unchanged_app.py</code>)
- [Blender components](#blender-components)
- [How it works](#how-it-works)
- [Performance](#performance)
+- [Roadmap: more languages and platforms](#roadmap-more-languages-and-platforms)
+- [Packaging](#packaging)
- [Documentation](#documentation)
- [Repository layout](#repository-layout)
- [Testing](#testing)
@@ -66,12 +72,33 @@ Right: an unmodified tkinter program (<code>examples/tk_unchanged_app.py</code>)
| **Qt syntax** (`bui.qtsyntax`) | 🟡 **Partial (~25%)** | The common subset works: widgets, layouts, signals, `QPainter`, menus, timers. Model/view, docks, toolbars, splitters and stylesheets are missing. [Details](docs/qt.md#coverage). |
| Component library (`bui.components`) | ✅ Working | 45 Blender components, including editors (color ramp, curves) and templates |
| C++ / Qt render-sink backends | ✅ Working | For embedding BUI drawing into your own renderer ([INTEGRATION.md](INTEGRATION.md)) |
-| Packaging (`pip install`) | ❌ Not yet | Build from source with CMake (below) |
+| Packaging (`pip install blenderui`) | 🟡 Scaffolded | `pyproject.toml` (scikit-build-core), CI wheels for Windows, Linux and macOS, trusted publishing. A locally built wheel passes all suites. First PyPI release pending. ([docs/publishing.md](docs/publishing.md)) |
+| Rust, egui, WebAssembly / React, more | 🗺️ Planned | See the [roadmap](#roadmap-more-languages-and-platforms) |
## Install and build
-Requirements: **CMake ≥ 3.20**, a **C11/C++17 compiler** (GCC / MinGW, Clang
-or MSVC), and **Python 3** with development headers (for the Python APIs).
+### From PyPI (once released)
+
+```sh
+pip install blenderui
+```
+
+```python
+import blenderui.tksyntax as tk # tkinter syntax
+from blenderui.components import App # Blender components
+from blenderui.qtsyntax import QWidget # Qt syntax
+```
+
+`blenderui` and `bui` are the same package (`blenderui.X` *is* `bui.X`);
+the examples below use `bui` because that's how the source tree is
+organised. Use `blenderui` in published code: the `bui` name on PyPI
+belongs to an unrelated project. A console script comes with it:
+`blenderui-tk app.py` runs a tkinter app on BUI.
+
+### From source
+
+Requirements: **CMake ≥ 3.20**, a **C11/C++17 compiler** (GCC / MinGW or
+Clang; MSVC is untested), and **Python 3.11+** with development headers.
```sh
git clone <this repository> BUI
@@ -239,6 +266,107 @@ Measured on the full component demo (520×900) on a desktop CPU:
The test suite enforces a 120 Hz budget: full frames under 8.3 ms, and
interaction frames under 1 ms.
+## Roadmap: more languages and platforms
+
+BUI's core is plain C with a small, stable surface (`kit/include/BUI_kit.h`
+for widgets, `api/bui_c_api.h` for render sinks). Its output is either a
+frame buffer (`BuiRaster`, ARGB pixels plus damage rectangles) or a stream
+of draw primitives. That makes every target below the same job: bind the C
+API, feed in input events, and present the pixels or primitives. None of
+them needs Python.
+
+| Target | Plan | Status |
+|---|---|---|
+| **Python**: tkinter, Qt, components | `bui.tksyntax`, `bui.qtsyntax`, `bui.components` | ✅ Done (Qt partial) |
+| **C / C++** | `BUI_kit.h`, render sinks, Qt/QPainter backend | ✅ Done |
+| **Rust** | `blenderui-sys` (bindgen over `BUI_kit.h`) and a safe `blenderui` crate: an owned node tree, closures for callbacks, `winit` windows | 🗺️ Planned |
+| **egui** | Two ways in: draw a BUI panel inside egui (raster to an `egui::TextureHandle`, with input forwarded), and a Blender-styled `egui::Visuals` theme | 🗺️ Planned |
+| **WebAssembly** | Compile the kit with Emscripten. The raster blits to a `<canvas>` (`putImageData` of the damage rectangles only), and DOM pointer and keyboard events go to `BK_press` / `BK_key` | 🗺️ Planned |
+| **React** | `@blenderui/react` on top of the WASM build: a reconciler that maps JSX to kit nodes (`<Panel>`, `<NumberSlider>` ...) | 🗺️ Planned |
+| **JavaScript / TypeScript** | `@blenderui/web` (the plain WASM API), and Node through N-API | 🗺️ Planned |
+| **Tauri / Electron** | The WASM build in the webview, or the native kit through the host language | 🗺️ Planned |
+| **C# / .NET** | P/Invoke over `BUI_kit.h` (WinForms / WPF / Avalonia hosts) | 🗺️ Planned |
+| **Go**, **Zig**, **Swift**, **Kotlin/JVM**, **Lua** | cgo / `@cImport` / Swift C interop / Panama FFI / LuaJIT FFI over the same header | 🗺️ Planned |
+| **Dear ImGui** | A backend that shows BUI panels in an ImGui window, plus a Blender-styled ImGui theme | 🗺️ Planned |
+| **Game engines**: Godot, Unity, Bevy | Editor-style tool panels: GDExtension, a native Unity plugin, a Bevy plugin through the Rust crate | 🗺️ Planned |
+| **Flutter** | `dart:ffi` bindings, with the frame buffer shown as a `Texture` | 🗺️ Planned |
+| **Native windows on Linux / macOS** | Wayland / X11 and Cocoa hosts in C, like the Win32 one (today the stdlib Tk window hosts them) | 🗺️ Planned |
+| **GPU renderers** | OpenGL / Vulkan / Metal / WebGPU render sinks for very large or high-DPI UIs (today a SIMD-friendly CPU raster, under 1 ms per frame) | 🗺️ Planned |
+
+<details>
+<summary>Intended API sketches (planned, not implemented yet)</summary>
+
+Rust:
+
+```rust
+use blenderui::{App, Panel, NumberSlider, Checkbox, Button};
+
+fn main() {
+ App::new("Tool", (360, 260))
+ .child(Panel::new("Object")
+ .child(NumberSlider::new("Size", 1.0).range(0.0, 10.0)
+ .on_change(|v| println!("size = {v}")))
+ .child(Checkbox::new("Smooth", true))
+ .child(Button::new("Apply").on_click(|| println!("apply"))))
+ .run();
+}
+```
+
+egui:
+
+```rust
+egui::Window::new("Properties").show(ctx, |ui| {
+ blenderui_egui::panel(ui, &mut state.bui_panel); // a BUI subtree inside egui
+});
+```
+
+React (WebAssembly):
+
+```jsx
+import { BlenderUI, Panel, NumberSlider, Checkbox } from "@blenderui/react";
+
+export default function Properties() {
+ const [size, setSize] = useState(1);
+ return (
+ <BlenderUI width={360} height={260}>
+ <Panel title="Object">
+ <NumberSlider label="Size" value={size} min={0} max={10} onChange={setSize} />
+ <Checkbox label="Smooth" defaultChecked />
+ </Panel>
+ </BlenderUI>
+ );
+}
+```
+
+</details>
+
+Work order: the Rust crate first (it also unlocks egui and Bevy), then
+the WebAssembly build (it unlocks React, JS/TS, Tauri and Electron), then
+native Linux / macOS windows.
+
+## Packaging
+
+The project is packaged as **`blenderui`** for PyPI: `pyproject.toml` with
+scikit-build-core, which drives the CMake build. One wheel contains the
+`buipy` extension plus the `bui` and `blenderui` packages.
+
+```sh
+python -m pip install build
+python -m build # dist/blenderui-<version>.tar.gz and a wheel
+```
+
+- **Version:** a single source, `bindings/python/bui/_version.py`, read by
+ CMake and by the packaging.
+- **CI:** `.github/workflows/wheels.yml` runs `cibuildwheel` for CPython
+ 3.11–3.14 on Windows (MinGW), Linux (manylinux) and macOS (arm64 and
+ x86_64), plus an sdist and the full ctest run. Pushing a `v*` tag
+ publishes to PyPI with trusted publishing (no tokens stored).
+- **Verified locally:** a wheel built on Windows installs into a clean
+ virtualenv and passes the component, syntax, render, tkinter-compat and
+ input suites.
+- **Release steps and one-time PyPI setup:** [docs/publishing.md](docs/publishing.md).
+ Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+
## Documentation
| Guide | What's inside |
@@ -248,6 +376,8 @@ interaction frames under 1 ms.
| [docs/qt.md](docs/qt.md) | Qt-syntax guide: classes, signals, layouts, painting, timers, coverage and gaps |
| [docs/components.md](docs/components.md) | `bui.components` reference: layout, values, views, menus, color, editors, `App` |
| [docs/c-api.md](docs/c-api.md) | The C kit (`BUI_kit.h`): nodes, properties, events, windows |
+| [docs/publishing.md](docs/publishing.md) | Packaging as `blenderui`, building wheels, CI, releasing to PyPI |
+| [CHANGELOG.md](CHANGELOG.md) | Release notes |
| [SYNTAX_COVERAGE.md](SYNTAX_COVERAGE.md) | Member-by-member coverage tables for both syntax layers |
| [INTEGRATION.md](INTEGRATION.md) | Embedding BUI drawing in C, C++, Qt or PySide hosts through render sinks |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Modules, dependency rules, what was taken from Blender and how |
@@ -260,6 +390,7 @@ Examples (`examples/`):
| `tk_syntax_demo.py` | tkinter syntax laid out like a Blender properties editor |
| `qt_syntax_demo.py` | Qt syntax: layouts, form widgets, signals |
| `components_demo.py` | Every Blender component, in a properties-editor layout |
+| `kit_hello.c` | The C kit from C: a slider and a button in a native window |
| `python_demo.py`, `svg_demo.c` | Low-level drawing into an SVG render sink |
## Repository layout
@@ -273,6 +404,8 @@ Examples (`examples/`):
| `api/` | Stable C ABI for render-sink hosts (`bui_c_api.h`) |
| `bindings/python/` | `buipy` extension (`src/`) and the `bui` package: `tksyntax/`, `qtsyntax.py`, `components/`, `host.py` |
| `backends/qt/` | C++ Qt/QPainter render-sink backend |
+| `bindings/python/blenderui/` | The `blenderui` import alias (the PyPI name) |
+| `pyproject.toml`, `.github/workflows/` | PyPI packaging (scikit-build-core) and the wheel and release CI |
| `examples/`, `tools/` | Demos, the icon generator, the docs screenshot generator |
## Testing
diff --git a/bindings/python/CMakeLists.txt b/bindings/python/CMakeLists.txt
index 2ad45ca..794c14d 100644
--- a/bindings/python/CMakeLists.txt
+++ b/bindings/python/CMakeLists.txt
@@ -20,6 +20,17 @@ set_target_properties(buipy PROPERTIES
RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bindings/python
)
+# Wheel layout (pip install blenderui / scikit-build-core): the extension and
+# the pure-Python packages side by side in site-packages.
+if(SKBUILD)
+ install(TARGETS buipy LIBRARY DESTINATION . RUNTIME DESTINATION .)
+ install(DIRECTORY bui blenderui DESTINATION .
+ PATTERN "__pycache__" EXCLUDE PATTERN "*.pyc" EXCLUDE)
+ if(MINGW) # no MinGW runtime DLLs next to the wheel's .pyd
+ target_link_options(buipy PRIVATE -static-libgcc -static)
+ endif()
+endif()
+
if(BUI_BUILD_TESTS)
# buipy comes from the build dir; the 'bui' package from this source dir.
if(WIN32)
diff --git a/bindings/python/blenderui/__init__.py b/bindings/python/blenderui/__init__.py
new file mode 100644
index 0000000..76cfb37
--- /dev/null
+++ b/bindings/python/blenderui/__init__.py
@@ -0,0 +1,56 @@
+"""blenderui: the PyPI name of BUI (``pip install blenderui``).
+
+``blenderui`` and ``bui`` are the same package: ``blenderui.X`` *is*
+``bui.X`` (the same module objects), so either spelling works::
+
+ import blenderui.tksyntax as tk
+ from blenderui.components import App, Panel
+
+Prefer ``blenderui`` in code you publish: another, unrelated project owns the
+name ``bui`` on PyPI.
+
+SPDX-License-Identifier: GPL-2.0-or-later
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+
+import bui as _bui
+from bui import * # noqa: F401,F403
+from bui._version import __version__ # noqa: F401
+
+_PREFIX = __name__ + "."
+
+
+class _AliasLoader(importlib.abc.Loader):
+ def __init__(self, target):
+ self.target = target
+
+ def create_module(self, spec):
+ return importlib.import_module(self.target)
+
+ def exec_module(self, module):
+ pass # already executed as bui.*
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder):
+ """Resolve ``blenderui.<path>`` to ``bui.<path>``."""
+
+ def find_spec(self, fullname, path=None, target=None):
+ if not fullname.startswith(_PREFIX):
+ return None
+ real = "bui." + fullname[len(_PREFIX):]
+ if importlib.util.find_spec(real) is None:
+ return None
+ return importlib.util.spec_from_loader(fullname, _AliasLoader(real))
+
+
+if not any(isinstance(f, _AliasFinder) for f in sys.meta_path):
+ sys.meta_path.insert(0, _AliasFinder())
+
+__path__ = [] # a package, so `import blenderui.x` consults the finder
+__all__ = getattr(_bui, "__all__", [n for n in dir(_bui) if not n.startswith("_")])
diff --git a/bindings/python/blenderui/__pycache__/__init__.cpython-314.pyc b/bindings/python/blenderui/__pycache__/__init__.cpython-314.pyc
new file mode 100644
index 0000000..056d484
Binary files /dev/null and b/bindings/python/blenderui/__pycache__/__init__.cpython-314.pyc differ
diff --git a/bindings/python/bui/__init__.py b/bindings/python/bui/__init__.py
index 893d7db..c798199 100644
--- a/bindings/python/bui/__init__.py
+++ b/bindings/python/bui/__init__.py
@@ -112,6 +112,9 @@ except ImportError as _e: # pragma: no cover
) from _e
+from bui._version import __version__ # noqa: E402
+
+
def version() -> str:
"""BUI library version as a string."""
return buipy.version()
diff --git a/bindings/python/bui/__pycache__/__init__.cpython-314.pyc b/bindings/python/bui/__pycache__/__init__.cpython-314.pyc
index c5aab02..54a09d5 100644
Binary files a/bindings/python/bui/__pycache__/__init__.cpython-314.pyc and b/bindings/python/bui/__pycache__/__init__.cpython-314.pyc differ
diff --git a/bindings/python/bui/__pycache__/_version.cpython-314.pyc b/bindings/python/bui/__pycache__/_version.cpython-314.pyc
new file mode 100644
index 0000000..fdbb69b
Binary files /dev/null and b/bindings/python/bui/__pycache__/_version.cpython-314.pyc differ
diff --git a/bindings/python/bui/_version.py b/bindings/python/bui/_version.py
new file mode 100644
index 0000000..b247734
--- /dev/null
+++ b/bindings/python/bui/_version.py
@@ -0,0 +1,6 @@
+"""The single source of the version (read by CMake and by the Python packaging).
+
+SPDX-License-Identifier: GPL-2.0-or-later
+"""
+
+__version__ = "0.1.0"
diff --git a/core/CMakeLists.txt b/core/CMakeLists.txt
index 58f93ec..d3a96e9 100644
--- a/core/CMakeLists.txt
+++ b/core/CMakeLists.txt
@@ -53,7 +53,11 @@ target_include_directories(bui_core PRIVATE
)
# Forced compat shim so upstream sources compile as-is in C mode (GCC/Clang).
-if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
+if(MSVC) # cl and clang-cl spell the forced include /FI
+ target_compile_options(bui_core PRIVATE
+ "/FI${CMAKE_CURRENT_SOURCE_DIR}/intern/bui_c_compat.h"
+ )
+elseif(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
target_compile_options(bui_core PRIVATE
"-include${CMAKE_CURRENT_SOURCE_DIR}/intern/bui_c_compat.h"
)
diff --git a/docs/publishing.md b/docs/publishing.md
new file mode 100644
index 0000000..ad90d2e
--- /dev/null
+++ b/docs/publishing.md
@@ -0,0 +1,96 @@
+# Packaging and publishing (`blenderui` on PyPI)
+
+| | |
+|---|---|
+| PyPI name | **`blenderui`** (`pip install blenderui`) |
+| Import names | `blenderui` (recommended) and `bui` (the same modules), plus the extension `buipy` |
+| Build backend | [scikit-build-core](https://scikit-build-core.readthedocs.io) driving the project's CMake (`pyproject.toml`) |
+| Version | `bindings/python/bui/_version.py`, the single source (CMake reads it too) |
+| Python | 3.11+ (CPython) |
+| Console script | `blenderui-tk app.py`, which is the same as `python -m bui.tksyntax app.py` |
+
+> The import name `bui` is kept for existing code. An unrelated project owns
+> `bui` on PyPI, so published code should use `import blenderui`. The two
+> can't both be installed under the same import name.
+
+## What a wheel contains
+
+```
+site-packages/
+ buipy.<abi>.pyd|.so the C kit + raster engine (one extension module)
+ bui/ tksyntax/, qtsyntax.py, components/, host.py ...
+ blenderui/ alias package: blenderui.X is bui.X
+ blenderui-<v>.dist-info/
+```
+
+On Windows the extension is built with MinGW-w64 GCC (UCRT) and statically
+linked against the GCC runtime. It depends only on system DLLs and
+`python3xx.dll`. A wheel is about 0.4 MB compressed; the sdist is about
+1.7 MB (it excludes `reference/` and build trees).
+
+## Build locally
+
+```sh
+python -m pip install build
+python -m build # sdist + wheel in dist/
+
+# Windows with MSYS2 MinGW (the tested toolchain):
+set CMAKE_GENERATOR=MinGW Makefiles
+set CC=gcc
+set CXX=g++
+python -m build
+```
+
+Test the wheel in a clean environment:
+
+```sh
+python -m venv /tmp/bui-venv
+/tmp/bui-venv/bin/pip install dist/blenderui-*.whl
+/tmp/bui-venv/bin/python -c "import blenderui, blenderui.tksyntax, blenderui.components; print(blenderui.__version__)"
+```
+
+The test suites (`bindings/python/tests/`) pass against an installed wheel.
+Remove the source tree from `sys.path` and keep `examples/` on it for
+`test_components`.
+
+## CI (`.github/workflows/wheels.yml`)
+
+| Job | Does |
+|---|---|
+| `wheels` | `cibuildwheel` for Linux (manylinux x86_64), Windows (MinGW, x86_64) and macOS (arm64 + x86_64), CPython 3.11–3.14; each wheel is imported as a smoke test |
+| `sdist` | `python -m build --sdist` |
+| `tests` | CMake build + `ctest` (all C and Python suites) on Windows |
+| `publish` | On a `v*` tag: upload everything to PyPI with trusted publishing. Manual run with `testpypi`: upload to TestPyPI. |
+
+## One-time PyPI setup
+
+1. Create the `blenderui` project on PyPI. Register it as a
+ [pending trusted publisher](https://docs.pypi.org/trusted-publishers/)
+ with this repository, workflow `wheels.yml`, environment `pypi`.
+2. Do the same on TestPyPI with environment `testpypi`.
+3. In the GitHub repository settings, create the environments `pypi` and
+ `testpypi` (optionally with required reviewers).
+4. Replace `OWNER` in `pyproject.toml` `[project.urls]` with the GitHub
+ owner.
+
+No API tokens are stored anywhere.
+
+## Release checklist
+
+1. Bump `bindings/python/bui/_version.py` (semantic versioning).
+2. Add the release to `CHANGELOG.md`.
+3. `ctest --test-dir build` passes locally. Optionally run the workflow by
+ hand with `testpypi` and `pip install -i https://test.pypi.org/simple blenderui`.
+4. `git tag v0.1.0 && git push --tags`. CI builds, tests and publishes.
+
+## Known gaps before 1.0
+
+- Linux and macOS wheels build in CI but haven't been exercised
+ interactively. Their window host is the stdlib Tk window, so the system
+ Python needs `tkinter` (for example `python3-tk`).
+- MSVC builds: the forced-include shim has an MSVC (`/FI`) path, but MSVC
+ isn't tested, which is why CI uses MinGW on Windows.
+- No `musllinux` or 32-bit wheels yet (skipped in `[tool.cibuildwheel]`).
+- The README's images use relative paths. PyPI shows them once
+ `[project.urls]` points to the public repository and the paths are made
+ absolute (or the images are hosted).
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..5424946
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,73 @@
+# blenderui: Blender's UI as a Python library (import blenderui / bui).
+# Built with scikit-build-core, which drives the CMake build of the C kit and
+# the buipy extension. See docs/publishing.md for the release checklist.
+
+[build-system]
+requires = ["scikit-build-core>=0.10"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "blenderui"
+dynamic = ["version"]
+description = "Blender's UI as a library: run tkinter apps unchanged, write Qt-style code, or use Blender components — all drawn by a fast C kit"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "GPL-2.0-or-later"
+license-files = ["LICENSE"]
+authors = [{ name = "BUI contributors" }]
+keywords = ["gui", "ui", "blender", "tkinter", "qt", "widgets", "toolkit"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "Programming Language :: C",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3 :: Only",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
+ "Programming Language :: Python :: 3.14",
+ "Programming Language :: Python :: Implementation :: CPython",
+ "Operating System :: Microsoft :: Windows",
+ "Operating System :: POSIX :: Linux",
+ "Operating System :: MacOS",
+ "Topic :: Software Development :: User Interfaces",
+ "Topic :: Software Development :: Widget Sets",
+]
+dependencies = []
+
+[project.optional-dependencies]
+qt = ["PySide6>=6.5"] # only for bui.qt.BuiCanvas (embedding in a real Qt app)
+test = []
+
+[project.urls]
+Documentation = "https://github.com/OWNER/BUI/tree/main/docs"
+Source = "https://github.com/OWNER/BUI"
+Issues = "https://github.com/OWNER/BUI/issues"
+Changelog = "https://github.com/OWNER/BUI/blob/main/CHANGELOG.md"
+
+[project.scripts]
+blenderui-tk = "bui.tksyntax.__main__:main" # blenderui-tk app.py == python -m bui.tksyntax app.py
+
+[tool.scikit-build]
+minimum-version = "build-system.requires"
+cmake.version = ">=3.20"
+build.targets = ["buipy"]
+wheel.packages = [] # CMake installs bui/, blenderui/ and buipy
+wheel.exclude = ["**/__pycache__/**"]
+sdist.exclude = ["reference/", "build*/", ".github/", "**/__pycache__/", "*.pyd", "*.so"]
+
+[tool.scikit-build.cmake.define]
+BUI_BUILD_TESTS = "OFF"
+BUI_BUILD_EXAMPLES = "OFF"
+BUI_BUILD_UI = "OFF"
+BUI_BUILD_QT_BACKEND = "OFF"
+BUI_BUILD_PYTHON_BINDINGS = "ON"
+
+[tool.scikit-build.metadata.version]
+provider = "scikit_build_core.metadata.regex"
+input = "bindings/python/bui/_version.py"
+
+[tool.cibuildwheel]
+build = "cp311-* cp312-* cp313-* cp314-*"
+skip = "*-musllinux_* *-win32 *_i686"
+test-command = "python -c \"import blenderui, buipy, blenderui.tksyntax, blenderui.components; print(blenderui.__version__)\""