WIP: C bindings

.github/workflows/ci.yml

@@ -294,3 +294,19 @@ jobs:
         name: Build benchmarks (w/yoga)
         env:
           RUSTFLAGS: "-C opt-level=0"
+
+  build-c-bindings:
+    name: Build C Bindings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: |
+          cd bindings/c
+          cargo build
+        name: Build ctaffy library
+      - run: |
+          cd bindings/c/examples
+          ./compile_basic.sh
+          LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../../target/debug ./basic
+        name: Build C Bindings

.gitignore

@@ -4,6 +4,7 @@
 /yoga_test_fixtures
 /yoga_test_fixtures_grouped
 /test_fixtures/_scratch
+_scratch
 
 **/*.rs.bk
 Cargo.lock

Cargo.toml

@@ -107,6 +107,7 @@ members = [
     "scripts/import-yoga-tests",
     "benches",
     "tests/common",
+    "bindings/c"
 ]
 # The cosmic_text example is excluded from the workspace as including it breaks compilation
 # of all crates in the workspace with our MSRV compiler

bindings/c/.gitignore

@@ -0,0 +1 @@
+examples/basic

bindings/c/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "ctaffy"
+version = "0.0.1"
+authors = [
+    "Nico Burns <[email protected]>",
+]
+edition = "2021"
+include = ["src/**/*", "Cargo.toml"]
+description = "C bindings to Taffy (A flexible UI layout library)"
+repository = "https://github.com/DioxusLabs/taffy"
+license = "MIT"
+
+[lib]
+name = "ctaffy"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[dependencies]
+taffy = { path = "../.." }

bindings/c/README.md

@@ -0,0 +1,97 @@
+# C API for Taffy (ctaffy)
+
+Taffy is a flexible, high-performance, cross-platform UI layout library written in Rust.
+
+This directory contains C bindings for Taffy. The API is a pure C API (no C++ features are used), and is designed to be easy to build other language bindings on top of. In addition to the documentation below, you may to read through the header file (`include/taffy.h`).
+
+## Examples
+
+There are readable examples in the examples directory.
+
+Assuming you have Rust and Cargo installed (and a C compiler), then this should work to run the basic example:
+
+```bash
+git clone https://github.com/DioxusLabs/taffy.git
+cd taffy/ctaffy/examples
+./compile-basic.sh
+./basic
+```
+
+## Naming Conventions
+
+- Everything in the Taffy C API is prefixed with `Taffy`, except enum variant names which are prefixed with `TAFFY_`
+- Structs and Enums are named in UpperCamelCase (e.g. `TaffyTree`, `TaffyStyle`)
+- Functions begin with the name of the struct they apply to, followed by an underscore, followed by the name of the function in UpperCamelCase (e.g. `TaffyTree_New`, `TaffyStyle_SetFlexBasis`)
+- Enum variants are SCREAMING_SNAKE_CASE
+
+## Error Handling
+
+Error handling is managed by the use of return codes and "result" structs. All functions in the API return either an `enum TaffyReturnCode` or one of the `struct Taffy*Result` structs (or `void` in the case of infallible operations that don't return anything).
+
+### Return codes
+
+Error handling is managed by the use of an enum `TaffyReturnCode`:
+
+```c
+typedef enum TaffyReturnCode {
+  TAFFY_RETURN_CODE_OK,
+  TAFFY_RETURN_CODE_NULL_STYLE_POINTER,
+  TAFFY_RETURN_CODE_NULL_TREE_POINTER,
+  // ... (see header file for full definition)
+} TaffyReturnCode;
+```
+
+`TAFFY_RETURN_CODE_OK` indicates that the operation succeeded. All other variant indicate
+
+### Result structs
+
+"Result structs" are used for functions that need to return another value in addition to a `TaffyReturnCode` indicating success/failure (such as style getters which need to return the relevant style value). As C doesn't support generic structs, there are several "Result structs": one for each type of value. But each struct follows the same structure as the following example (varying only in the name of the struct and the type of the `value` field):
+
+<table>
+<tr><th>TaffyIntResult</th><th>TaffyDimensionResult</th></tr>
+<tr>
+<td>
+
+```c
+typedef struct TaffyIntResult {
+  enum TaffyReturnCode return_code;
+  int32_t value;
+} TaffyIntResult;
+```
+
+</td>
+<td>
+
+```c
+typedef struct TaffyDimensionResult {
+  enum TaffyReturnCode return_code;
+  struct TaffyDimension value;
+} TaffyDimensionResult;
+```
+
+</td>
+</tr>
+</table>
+
+Functions that return Result structs will either return a `TAFFY_RETURN_CODE_OK` along with a meaningful value, or a error variant of `TaffyReturnCode` along with
+
+## API Usage
+
+### Tree Creation and Manipulation
+
+The `TaffyTree` struct is the entrypoint to the Taffy C API and represents an entire tree of UI nodes. Taffy uses arena allocation, so the `TaffyTree` owns the entire tree of nodes at all times.
+
+You only ever get access to a `TaffyNodeId` handle which can be used to manipulate the structure of the tree, or pointers to `TaffyStyle` object (which can be used to set styles on a Node, but are considered borrowed pointers and thus must only be held temporarily).
+
+#### Lifecycle
+
+- `TaffyTree_New` allocates a new `TaffyTree` and returns an owned pointer to it.
+- `TaffyTree_Free` can be used to free the tree once you are done with it.
+
+All other functions in the API which accept a pointer to a `TaffyTree` have borrowing semantics: they access the tree during the duration of the function (and if the pointer is not a `const` pointer, may modify the tree), but will not store the pointer or take ownership of the tree.
+
+#### Node creation and manipulation
+
+- `TaffyTree_NewNode` creates a new Node within the tree and returns a `TaffyNodeId` handle to it. The node will initially have the default styles
+
+### Setting styles on node

bindings/c/cbindgen.toml

@@ -0,0 +1,22 @@
+language = "c"
+cpp_compat = true
+documentation_style = "c99"
+line_length = 120
+
+[enum]
+rename_variants = "QualifiedScreamingSnakeCase"
+
+[export]
+include = ["TaffyNodeId"]
+
+[export.rename]
+TaffyResult_f32 = "TaffyFloatResult"
+TaffyResult_i32 = "TaffyIntResult"
+TaffyResult_TaffyNodeId = "TaffyNodeIdResult"
+TaffyResult_TaffyDimension = "TaffyDimensionResult"
+TaffyResult_TaffyGridPlacement = "TaffyGridPlacementResult"
+TaffyResult_TaffyStyleMutRef = "TaffyStyleMutRefResult"
+
+[parse.expand]
+crates = ["ctaffy"]
+

bindings/c/examples/basic.c

@@ -0,0 +1,41 @@
+#include <stdlib.h>
+#include <stdint.h>
+#include <math.h>
+#include <stdio.h>
+
+#include "taffy.h"
+
+int main() {
+    // Create tree
+    TaffyTree *tree = TaffyTree_New();
+
+    // Create child (+set styles)
+    TaffyNodeId child = TaffyTree_NewNode(tree).value;
+    TaffyStyle *child_style = TaffyTree_GetStyleMut(tree, child).value;
+    TaffyStyle_SetWidth(child_style, 0.5, TAFFY_UNIT_PERCENT);
+    TaffyStyle_SetHeight(child_style, 0, TAFFY_UNIT_AUTO);
+
+    // Create parent (+set styles)
+    TaffyNodeId parent = TaffyTree_NewNode(tree).value;
+    TaffyStyle *parent_style = TaffyTree_GetStyleMut(tree, parent).value;
+    TaffyStyle_SetWidth(parent_style, 100, TAFFY_UNIT_LENGTH);
+    TaffyStyle_SetHeight(parent_style, 100, TAFFY_UNIT_LENGTH);
+    TaffyStyle_SetJustifyContent(parent_style, TAFFY_ALIGN_CONTENT_CENTER);
+
+    // Setup parent-child relationship
+    TaffyTree_AppendChild(tree, parent, child);
+
+    // Compute layout (100x100 viewport)
+    printf("\nCompute layout with 100x100 viewport:\n");
+    TaffyTree_ComputeLayout(tree, parent, 100, 100);
+    TaffyTree_PrintTree(tree, parent);
+
+    // Compute layout (infinite viewport)
+    printf("\nCompute layout with infinite viewport:\n");
+    TaffyTree_ComputeLayout(tree, parent, INFINITY, INFINITY);
+    TaffyTree_PrintTree(tree, parent);
+
+    // Free tree
+    TaffyTree_Free(tree);
+    return 0;
+}

bindings/c/examples/compile_basic.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+set -ex
+
+cargo build --manifest-path ../Cargo.toml
+gcc -O3 -DDEBUG -o basic basic.c -std=c99 -Wall -I../include -L../../../target/debug -lctaffy

bindings/c/generate-bindings.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+cbindgen --crate ctaffy --output include/taffy.h