cwtch.im
/
docs.cwtch.im
4
0
Fork 3
Code Issues 2 Pull Requests Projects Releases Wiki Activity

Erinn

This commit is contained in:
Sarah Jamie Lewis 2023-02-24 13:52:53 -08:00
parent 38a22c0825
commit 85dbbed4df
1 changed files with 8 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
blog/2023-02-24-autogenerating-cwtch-bindings.md
View File

@ -13,7 +13,7 @@ authors:
---
The C-bindings for Cwtch evolved as part of Cwtch UI development. After two years of prototyping, development, new features, and revisiting first-implementations we have reached the point where we have a good understanding of
what the bindings need to do, and how they should do it. To that end we have produced a first-cut of a workflow to **automatically generate** these bindings; [cwtch-autobindings](https://git.openprivacy.ca/cwtch.im/autobindings).
what the bindings need to do, and how they should do it. To that end we have produced a first-cut of a workflow to **automatically generate** these bindings: [cwtch-autobindings](https://git.openprivacy.ca/cwtch.im/autobindings).
This this development log we will introduced autobindings, the motivation behind them, and how we plan to use them on the [path to Cwtch Stable](https://docs.cwtch.im/blog/path-to-cwtch-stable).
@ -24,13 +24,13 @@ This this development log we will introduced autobindings, the motivation behind
## A Brief History of Cwtch Bindings
Prior to the modern Flutter-based UI application, the first Cwtch UI prototype was based on Qt, with the bindings automatically generated by [therecipe/qt](https://github.com/therecipe/qt). However, after encountering numerous
crash-bugs on the compiled arm version for Android, and a few weeks of prototyping different approaches, we settled on Flutter as a replacement UI framework.
crash-bugs on the compiled Arm version for Android, and a few weeks of prototyping different approaches, we settled on Flutter as a replacement UI framework.
As part of early prototyping efforts for Flutter we built out a first version of [libCwtch-go](https://git.openprivacy.ca/cwtch.im/libcwtch-go), and over the two years of beta development we have evolved that prototype into a functional set of Cwtch bindings.
This approach has not been without side effects. There is still code from those early prototypes floating around in libCwtch-go, inconsistencies in how functions - in particular [experimental features](https://docs.cwtch.im/blog/cwtch-stable-api-design#the-cwtch-experiment-landscape) - handle settings, [duplication of logic between Cwtch and libCwtch-go](https://docs.cwtch.im/blog/cwtch-stable-api-design#bindings), and [special behaviour in libCwtch-go that better belongs in the core Cwtch library](https://docs.cwtch.im/blog/cwtch-stable-api-design#appendix-a-special-behaviour-defined-by-libcwtch-go).
As part of a broader effort to [refine the Cwtch API in preparation for Cwtch Stable](https://docs.cwtch.im/blog/cwtch-stable-api-design#clarifying-terminology) we have taken the opportunity to fix many of these problems.
As part of a broader effort to [refine the Cwtch API in preparation for Cwtch Stable](https://docs.cwtch.im/blog/cwtch-stable-api-design) we have taken the opportunity to fix many of these problems.
## Cwtch Autobindings
@ -48,7 +48,7 @@ The current `lib.go` file that encapsulates the vast majority of libCwtch-go cur
}
}
All that code is doing is defining a c-compatible API, performing some basic checking of parameters, and passing the result into the core Cwtch library. The two functions themselves support the C-bindings and Java-bindings respectively.
All that code is doing is defining a C-compatible API, performing some basic checking of parameters, and passing the result into the core Cwtch library. The two functions themselves support the C-bindings and Java-bindings respectively.
In the new [cwtch-autobindings](https://git.openprivacy.ca/cwtch.im/autobindings) we reduce these multiple lines to [a single one](https://git.openprivacy.ca/cwtch.im/autobindings/src/branch/main/spec#L19):
@ -64,16 +64,16 @@ Using a similar boilerplate-reduction for the reset of `lib.go` yields [5-basic
* Experimental Profile-level feature functions e.g. `DownloadFile`
* Experimental Profile-level feature functions that return data e.g. `ShareFile`
Once aggregated and itemized the full set of bindings for Cwtch applications, profile interactions, and experiments can be [described in fewer than 50 lines, including comments](https://git.openprivacy.ca/cwtch.im/autobindings/src/branch/main/spec). Even including the code necessary to generate the bindings from this specification file (~400 lines), and the code needed to initialize the bindings themselves (~300 lines) This cuts the amount of coded needed by 60%, and eliminates many classes of error and inconsistencies associated with maintaining bindings (e.g. regularizing function calls / checking experiment status / handling error conditions etc.)
Once aggregated and itemized the full set of bindings for Cwtch applications, profile interactions, and experiments can be [described in fewer than 50 lines, including comments](https://git.openprivacy.ca/cwtch.im/autobindings/src/branch/main/spec). Even including the code necessary to generate the bindings from this specification file (~400 lines), and the code needed to initialize the bindings themselves (~300 lines). This cuts the amount of coded needed by 60%, and eliminates many classes of error and inconsistencies associated with maintaining bindings (e.g. regularizing function calls / checking experiment status / handling error conditions etc.).
## Next Steps
Cwtch autobindings work today, are API-compatible with the existing libCwtch-go implements, and can be fully integrated into an existing Cwtch application with minimal effort. However, there are a few areas which need to be addressed prior to a full rollout:
* **[Application-level experiments](https://docs.cwtch.im/blog/cwtch-stable-api-design#application-experiments)** (of which there is only one: Desktop Server Hosting) are not currently support. This functionality is only tangentially related to the rest of the Cwtch bindings, and necessarily introduces additional dependencies (e.g. on `cwtch-server`). In the coming weeks we will allow optional application experiments to be enabled at compile time, to allow us to produce smaller bindings for platforms that cannot them, and to allow us to build new kinds of platform-targeted experiments that can take advantage of platform specific features.
* **[Application-level experiments](https://docs.cwtch.im/blog/cwtch-stable-api-design#application-experiments)** (of which there is only one: Desktop Server Hosting) are not currently supported. This functionality is only tangentially related to the rest of the Cwtch bindings, and necessarily introduces additional dependencies (e.g. on `cwtch-server`). In the coming weeks we will allow optional application experiments to be enabled at compile time, to allow us to produce smaller bindings for platforms that don't support the experiment, and to allow us to build new kinds of platform-targeted experiments that can take advantage of platform specific features.
* **Dart Library generation**: since we now have a formal description of the bindings interface, we can move ahead with also autogenerating the [Dart-side](https://git.openprivacy.ca/cwtch.im/cwtch-ui/src/branch/trunk/lib/cwtch) of the bindings interface, giving a boost to UI integration of new features, and allowing us to generate tailored versions of the UI interface e.g. one compiled without experiment support. We can also extend the same logic to other downstream interfaces e.g. [libcwtch-rs](https://git.openprivacy.ca/cwtch.im/libcwtch-rs)
* **Documentation generation**: another benefit of a formal description of the bindings interface, we can easily generate documentation compatible with [docs.cwtch.im](https://cwtch.im). This is something that we would love to be able to do prior to a 1.0 release.
* **Cwtch API**: This first cut of autobindings is based on an unreleased version of the core cwtch library that implements much of the [Cwtch Stable API redesign](https://docs.cwtch.im/blog/cwtch-stable-api-design#clarifying-terminology). In a short while we will be merging these features into Cwtch, in preparation for Cwtch 1.11, and beyond.
* **Documentation generation**: another benefit of a formal description of the bindings interface, we can easily generate documentation compatible with [docs.cwtch.im](https://cwtch.im).
* **Cwtch API**: This first cut of autobindings is based on an unreleased version of the core Cwtch library that implements much of the [Cwtch Stable API redesign](https://docs.cwtch.im/blog/cwtch-stable-api-design). In a short while we will be merging these features into Cwtch, in preparation for Cwtch 1.11, and beyond.
## Help us go further!