From 1ab8fd55a90d7926e732a6ef48fc63e94ca81740 Mon Sep 17 00:00:00 2001
From: Jasper Woudenberg <mail@jasperwoudenberg.com>
Date: Sun, 20 Oct 2024 20:31:11 +0200
Subject: [PATCH] Add extra documentation around glue

---
 crates/glue/README.md            | 33 ++++++++++++++++++++++++++++++++
 crates/glue/src/DescribeGlue.roc | 13 +++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 crates/glue/README.md
 create mode 100644 crates/glue/src/DescribeGlue.roc

diff --git a/crates/glue/README.md b/crates/glue/README.md
new file mode 100644
index 0000000000..358d20944c
--- /dev/null
+++ b/crates/glue/README.md
@@ -0,0 +1,33 @@
+# Glue
+
+Glue is a bit of tooling built into Roc to help with platform development. Roc platforms are written in a different language than Roc, and some it requires some finesse to let other languages to read and write Roc types like records and unions in a way compatible with how Roc uses those types.
+
+The `roc glue` command generates code in other languages for interacting with the Roc types used by your platform. It takes three arguments:
+
+1. A 'glue spec', this is a Roc file specifying how to output type helpers fora particular language. You can find some examples in the src/ subdirectory:
+
+    - **RustGlue.roc:** Generates Roc bindings for rust platforms.
+    - **ZigGlue.roc:** Generates Roc bindings for zig platforms (out of date).
+    - **DescribeGlue.roc:** Does not generate Roc bindings, but outputs some information about the types that assist writing compatible types in other languages by hand.
+
+2. A 'glue dir', specifying where glue should place generated files. Pass any directory you want here.
+
+3. A .roc file exposing some types that glue should generate code for. You can extend the template below.
+
+
+```roc
+platform "glue-types"
+    requires {} { main : _ }
+    exposes []
+    packages {}
+    imports []
+    provides [mainForHost]
+
+GlueTypes : {
+    a : SomeType,
+    b : AnotherType,
+}
+
+mainForHost : GlueTypes
+mainForHost = main
+```
diff --git a/crates/glue/src/DescribeGlue.roc b/crates/glue/src/DescribeGlue.roc
new file mode 100644
index 0000000000..ea57ddbfee
--- /dev/null
+++ b/crates/glue/src/DescribeGlue.roc
@@ -0,0 +1,13 @@
+app [makeGlue] { pf: platform "../platform/main.roc" }
+
+import pf.Types exposing [Types]
+import pf.File exposing [File]
+
+makeGlue : List Types -> Result (List File) Str
+makeGlue = \types ->
+    Ok [
+        {
+            name: "types.txt",
+            content: List.map types Inspect.toStr |> Str.joinWith "\n",
+        },
+    ]