The UIKit backend for glimmer, the
reactive Clojure(-like) UI framework for jolt.
Where glimmer-appkit renders into
macOS windows, glimmer-uikit renders the same hiccup into real iPhone views —
UIStackView/UILabel/UIButton, driven through the Objective-C runtime by a
plain C FFI (no bridging headers, no Objective-C source).
The whole toolkit fits in three namespaces. glimmer owns the reactive core
(ratom, component model, reconciler) and knows nothing about UIKit; this project
supplies the views, the prop/event wiring and the app loop, and registers them
through glimmer.backend.
(ns myapp
(:require [glimmer.ratom :refer [atom]]
[glimmer.core :as ui]
[glimmer-uikit.core])) ; installs the UIKit backend
(defn counter []
(let [count (atom 0)]
(fn []
[:vbox {:spacing 12}
[:label {:label (str "Count: " @count)}]
[:hbox {:spacing 8}
[:button {:label "- 1" :on-click #(swap! count dec)}]
[:button {:label "+ 1" :on-click #(swap! count inc)}]
[:button {:label "reset" :on-click #(reset! count 0)}]]])))
(defn -main [& _]
(ui/run counter))Components, reactive state and reconciliation are documented in glimmer's README. What follows is the UIKit-specific part: what you can put in the hiccup.
macOS with Xcode, for the simulator, the iOS SDKs and clang. jolt 0.8.0 or
newer: jolt.ffi/write changed its argument order in 0.8.0, and an older runtime
writes to the wrong place rather than failing, so deps.edn declares the floor.
An iOS app is cross-compiled, so jolt also needs a target pack for each machine
type: tarm64ios for the simulator, and tpb64l (portable bytecode, foreign
calls through libffi, since iOS forbids generating code at run time) for a phone.
glimmer-ios-demo has the recipe
for both. scripts/bundle looks for them at ~/dev/pack-tarm64ios-sim and
~/dev/pack-tpb64l-ios, or wherever PACK_SIM and PACK_DEVICE point.
UIKit is loaded by glimmer-uikit.ffi/load-uikit! from inside the app loop, never
at require time. Nothing is declared under :jolt/native: jolt build loads
every namespace on the macOS host before it emits code, and the headless test
suite (jolt -M:test) runs on Linux CI, where no Objective-C runtime exists.
jolt test # unit tests (Pango markup, prop normalization, handler reuse — no device needed)
jolt lint # clj-kondo over src, test and examples
jolt bundle # cross-compile the counter into build/Counter.app (TARGET=sim, or TARGET=device)
jolt install # install it on the booted simulator
jolt launch # launch it; `jolt console` launches it with stdout attached
jolt smoke # the counter, tapped twice from a worker thread (needs a booted simulator)NS=<namespace> jolt bundle bundles another example. A phone build must be
signed before it installs; glimmer-ios-demo shows how.
Elements are [:tag props? & children]. props is an optional map; children may
be native elements, component invocations ([my-component arg]), strings, or
numbers (rendered as labels). nil children are skipped.
Containers: :box (:orientation :horizontal|:vertical), :hbox, :vbox,
:layers (children fill it edge to edge, back to front), :scroll (children
stack vertically and scroll; never sideways).
There is no :window tag to write. The root of the tree mounts into the root
view controller's view, pinned to the safe area. (ui/run root :background "#rrggbb") colours that view; without it, the view takes the system background
colour. ui/run's other options, such as :title, mean nothing on a phone.
Leaf widgets: :button, :checkbutton, :label, :image, :gradient.
Common props (apply to every widget):
:halign— one of:fill :start :end :center;:valign— one of:fill :top :bottom :center(translated to the parent stack's alignment across its axis; the last child that names one wins):hexpand/:vexpand— boolean (lowers the content-hugging priority so the stack stretches the widget along that axis, and restores it when the prop goes):width/:height— points:background—"#rrggbb";:alpha— 0.0–1.0:center-y—true, or an offset in points (see Layout):height-anchor/:height-like— a group name (see Layout)- On the root:
:vfill,:full-bleed; on a child of:layers::safe(see Layout)
Per-tag props:
- Box:
:orientation,:spacing,:homogeneous,:margin(all four sides), or:margin-start/:margin-end/:margin-top/:margin-bottom;:margin-left/:margin-rightwin over:margin-start/:margin-end - Button:
:label,:sensitive,:foreground,:font-size,:font-weight(:bold),:radius,:border([width "#rrggbb" alpha]),:padding(the title's left and right inset, in points),:xalign(0.0–1.0),:label-date(milliseconds, shown as a date before:label, formatted by:date-format). A title too long for its button loses its tail. - Checkbutton:
:active,:symbol(the checkmark's point size, default 24),:foreground(the checkmark's colour), and a button's props for the box - Label:
:label/:text,:markup(Pango markup),:xalign(0.0–1.0),:wrap(any value wraps),:lines(int),:ellipsize(:start/:middle/:end),:date(milliseconds, shown as a date in the phone's locale),:date-format,:date-markup(span attributes for:date) - Image:
:src— a file in the app bundle, aspect-filled and clipped - Gradient:
:stops—[["#rrggbb" alpha location] ...], top to bottom - Scroll:
:spacing
An unknown prop is ignored, and said out loud. A prop that is neither
common nor in its tag's list above — a typo like :forground, or a name that
changed between versions — does nothing to the view, and the backend prints one
line naming the tag and the prop. Each pair is named once, on the render that
first passes it, and jolt console shows it.
Dates: :date-format is {:date style :time style}, on a label with
:date or a button with :label-date. A style is :none, :short,
:medium, :long or :full, the names of Foundation's
DateFormatter.Style.
A missing key keeps its default, {:date :medium :time :none}. The phone's
locale decides how each style reads. A style that is not one of the five
throws.
UIKit has no checkbox control; AppKit's NSButton is one, which is why
glimmer-appkit's :checkbutton can wrap it. Here a :checkbutton is a button
with no title whose tile is the box: empty when inactive, and with an SF Symbol
checkmark centred in it when :active. The props and the event are
glimmer-appkit's, so the same hiccup works on both backends.
Events:
:on-click— button tapped. Handler takes no args.:on-toggled— checkbutton tapped. Handler takes no args.
Taps route through addTarget:action:forControlEvents: to a single dynamic ObjC
class (GlimmerTarget) whose IMP is a jolt foreign-callable. The target is
added once at mount, but the handler behind it is replaced on every render (see
View reuse). A handler owns the state: :on-toggled flips the
cell the component reads, and :active comes back down as a prop. UIKit does
not fire actions for programmatic property changes, so a re-render can't feed
back into its own handler.
A label's :markup prop takes a Pango markup string, or hiccup data that is
validated and serialized for you — the same vocabulary glimmer-gtk and
glimmer-appkit use, so the same tree works on all three:
[:label {:markup [:span {:foreground "#8e939d"} "Nothing to do yet"]}]
[:label {:markup [:b [:i "bold italic"]]}]Pango's markup is a small XML subset, not HTML, so the data is checked against
Pango's own vocabulary first: an HTML-only tag (:div, :br) or a typo'd
attribute throws at the call site instead of rendering silently wrong. Attribute
names use Pango's spelling with underscores (:font_family, :letter_spacing),
and text is escaped for you. The string comes from this project's own walk over
the data, which the test suite checks byte for byte against hiccup's output, so
an app does not carry hiccup at run time.
The validated string is parsed back into segments and applied as an
NSAttributedString. What survives: :b, :i, :s and :u; and on a
:span, :foreground, :size, :weight "bold", :strikethrough "true",
:underline "true", :variant "smallcaps", :font_family (a PostScript name;
one iOS lacks falls back to the system font), and :letter_spacing (Pango units,
1/1024 of a point, negative allowed).
A stack cannot express everything a phone screen needs, so a few props reach past it.
- The safe area. The root is pinned to the safe area's top, leading and
trailing edges, and hugs its content at the bottom.
:vfillpins its bottom too, so a:vexpandchild can push a footer down;:full-bleedpins it to the window's edges instead, under the status bar. A child of:layersfills its parent's edges, or its safe area with:safe. - The centre of the screen.
:center-ypins a widget's centre to its parent stack's centre, and the spacers around it take whatever heights make that true. - Two views, one height.
:height-anchor gnames a view, and a later:height-like gin the same render takes its height. Two spacers share the slack that way, which a stack's fill distribution cannot do alone.
glimmer reuses a view when the tag at the same position matches across renders, including across screens. Every piece of state this backend keeps follows the render, not the mount:
- A prop that a later render leaves out, or sets to
nil, is reset. The reused view then looks and behaves like a new view of that tag with the later render's props.:vfill,:full-bleed,:safe,:height-anchorand:height-likeare the exception: they act only when a view joins its parent. - The handler behind
:on-clickand:on-toggledis replaced on every render. Otherwise a reused button fires the handler of the screen it was built for. :width,:heightand:center-ykeep one constraint per view and kind: added when the prop appears, replaced when it changes, dropped when it goes.:hexpand/:vexpandput the hugging priority back to UIKit's default when the prop goes.- The registries are keyed by view address, and a new view can be allocated where a freed one was. Creating a view forgets everything known about its address.
glimmer-uikit.core/on-lifecycle! registers one zero-arg handler per event:
:resign-active, :background, :foreground, :active, :terminate. nil
removes it. Each event is also logged to stdout with a timestamp, which is what
jolt console shows.
A consumer can teach glimmer-uikit new hiccup tags at load time:
(require '[glimmer-uikit.widget :as w])
(w/register-widget! :my-thing
{:ctor (fn [props] (make-the-view props))
:apply (fn [widget props] (apply props at mount and on re-render))
:connect (fn [widget props] (wire its events)) ; optional
:props #{:my-prop} ; optional
:container :none}) ; or :box / :layers / :scroll
(w/register-signal! :on-input "value-changed") ; apply-props! now skips :on-input:props names the props the widget takes, beside the ones every widget takes;
a prop outside both is reported as unknown. A spec without :props says
nothing about what it takes, so nothing of that tag is ever reported.
register-signal! marks a key as an event, so a re-render does not try to set it
on the view. The new widget wires the event to UIKit in :connect. create!
calls it once, last, after it wires :on-click and :on-toggled. Do not wire
events in :ctor: create! forgets the view's address after :ctor returns.
:connect runs only at mount, as in glimmer-appkit. When glimmer reuses the
view for a later render, the handler that :connect wired stays. Only
:on-click and :on-toggled take the new handler on each render.
Three namespaces:
glimmer-uikit.ffi— the Objective-C runtime and UIKit, throughjolt.ffi:objc_getClass/sel_registerName,objc_msgSendbound at fixed arities (struct args flattened into doubles — aCGRectorUIEdgeInsetsis an HFA of four doubles, so a flattened call passes exactly the registers a real method expects; never:varargs, which shifts FP args onto the stack and corrupts them), the CFRunLoop pieces the scheduler needs, andUIApplicationMain. Beyond the views, it has what an app soon wants:load-framework!anddata-symbolfor Core Location or MapKit,make-blockfor a completion handler,nsvalue->doublesandvalue-for-keyfor a struct property,timer!,open-url!,bundle-versionandsystem-image.BOOLreturns are:uint8, because jolt's:charis a Scheme character. Nothing runs at load.glimmer-uikit.widget— hiccup to UIKit: tag to constructor, props to setters,:on-*to target/action (a dynamicGlimmerTargetObjC class whose IMP is a joltforeign-callable), Pango markup toNSAttributedString, and container child management. The tag and signal registries are open (register-widget!,register-signal!).glimmer-uikit.core— the backend map handed toglimmer.backend/register!, the app loop (aGlimmerAppDelegateclass registered at run time, handed by name toUIApplicationMain, which mounts the root inapplication:didFinishLaunchingWithOptions:), the lifecycle hooks, and the scheduler that marshals off-main-thread work onto the main loop via aCFRunLoopSource— the UIKit analogue of GTK'sg_idle_add, without libdispatch or blocks.
ui/run never returns on iOS: UIApplicationMain owns the main thread for the
life of the app. A ratom written from another thread (a future, an nREPL eval)
repaints through the scheduler, and (glimmer.core/reload!) re-mounts the root
in the same view after components are redefined.
This project does not start an nREPL server. glimmer-ios-demo's counter example runs one inside the app, and its "Live" section shows how to reach it on the simulator and, over USB, on a phone.
MIT (see LICENSE).