| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 1 | # Working in this repo |
| 2 | |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 3 | ## The toolchain, and where builds happen |
| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 4 | |
| The last of the Clojure 284b59c nandi 23h ago | 5 | There is no nix in the build. `tools/toolchain.sh` fetches Flutter (which |
| 6 | carries Dart) and Nim as sha256-pinned tarballs into `.toolchain/`, and every |
| 7 | `just` recipe runs inside the environment that script prints. The host brings |
| 8 | a C compiler, OpenSSL, git, curl, unzip and python3 — and GTK with the usual |
| 9 | CMake/Ninja/pkg-config for the Linux target. |
| 10 | |
| 11 | It used to carry a JDK, the Clojure CLI, a maven repo and an Android SDK as |
| 12 | well. Those were ClojureDart's and the APK's, and both are gone. |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 13 | |
| 14 | **Prefer Modal for a long build.** A cold Flutter toolchain plus a full |
| 15 | compile is a lot of laptop, and the containers in `.modal/` do it on a real |
| 16 | machine: |
| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 17 | |
| 18 | ```bash |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 19 | just modal dev # the incremental Flutter loop |
| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 20 | ``` |
| 21 | |
| One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday | 22 | The containers in `.modal/` are not a third source tree: they are CI config |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 23 | that happens to live here, the way `.github/` would be. They run the very same |
| 24 | `tools/toolchain.sh`, which is why a plain Debian image is enough. |
| Build the window somewhere with room for it 1451151 nandi 6d ago | 25 | |
| 26 | `modal app logs` is no substitute for watching that command: it resolves |
| 27 | deployed apps by name, not the ephemeral one a `modal run` creates, and carries |
| 28 | nothing until the Sandbox starts — the image build streams to the client and |
| 29 | nowhere else. |
| 30 | |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 31 | The containers run as Modal **Sandboxes on a real VM** rather than under |
| 32 | gVisor: a real kernel, a working pty, and memory that is exactly what |
| 33 | `[resources] memory` asks for. |
| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 34 | |
| Follow the xorg renames, and stop wrapping nix in distrobox a400a00 nandi 17d ago | 35 | One thing this container is *not* representative of: `/etc/localtime` is a |
| 36 | regular file here rather than a symlink, so anything that reads the zone out |
| Read the clock in the reader's zone when /etc/localtime is a file bffe879 nandi 19d ago | 37 | of its path sees nothing. That is a real deployment shape, not an artefact — |
| 38 | frq.clock handles it. |
| Split the tree three ways, and let the phone be Flutter's 7070931 nandi 8d ago | 39 | |
| Build the window somewhere with room for it 1451151 nandi 6d ago | 40 | ## Never pipe a long task through `tail` |
| 41 | |
| 42 | `tail` and `head` do not emit anything until their input ends, so a build, a |
| 43 | test run or a deploy piped through one shows nothing at all until it is over — |
| 44 | and if it is killed or times out first, its output is lost with it. That is the |
| 45 | opposite of what you want from the commands that take longest. |
| 46 | |
| 47 | Let them write to the terminal, or `tee` them if you want a copy to grep |
| 48 | afterwards: |
| 49 | |
| 50 | ```bash |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 51 | modal run .modal/web/container.py 2>&1 | tee /tmp/frq-build.log |
| Build the window somewhere with room for it 1451151 nandi 6d ago | 52 | ``` |
| 53 | |
| 54 | Trim afterwards, on the file, where the whole run is still there to re-read. |
| 55 | The same goes for `grep` and `awk` in a live pipeline: they buffer when their |
| 56 | output is not a terminal, so pass `--line-buffered` / `fflush()` or watch the |
| 57 | file instead. |
| 58 | |
| One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday | 59 | ## The Nim core |
| 60 | |
| The last of the Clojure 284b59c nandi 23h ago | 61 | `nim/` is the program. It owns the state, the screens, the IRC connection and |
| 62 | the signing; Flutter is a renderer over the widget tree it emits. Read |
| 63 | `nim/README.md` before touching it. |
| One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday | 64 | |
| 65 | Two rules the ABI has, both of which cost a segfault to rediscover: |
| 66 | |
| 67 | * Every string the core returns is the **caller's** to free, with `frq_free`. |
| 68 | Nim's allocator is not Dart's. |
| 69 | * `frq_init` runs once before anything else. |
| 70 | |
| The last of the Clojure 284b59c nandi 23h ago | 71 | `dart/frq_core` is the other half of that seam. It is a plain Dart package and |
| 72 | not a Flutter one, deliberately: `flutter/pubspec.yaml` depends on the Flutter |
| 73 | SDK, so anything living there needs a Flutter toolchain to check one assertion |
| 74 | about a string, where this resolves and tests on its own. |
| 75 | |
| 76 | The rule that used to be here said new Dart-side code is written in Dart |
| 77 | rather than ClojureDart. There is no ClojureDart left for it to rule against, |
| 78 | but the reasoning it rested on still holds for the next thing: logic goes in |
| 79 | Nim, the platform goes in Dart, and neither is written in a third language |
| 80 | because it is already open. |
| The binding is Dart, and it works f7aea3b nandi yesterday | 81 | |
| Six verbs, and the last of the nix 2e24e64 nandi yesterday | 82 | `just test nim` and `just test dart` need no Flutter, which is most of the |
| The binding is Dart, and it works f7aea3b nandi yesterday | 83 | point: the whole boundary is checkable in about a second. |
| One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday | 84 | |
| The last of the Clojure 284b59c nandi 23h ago | 85 | There is no `common/` any more, and that rule went with it. It said a module |
| 86 | stays until there is a wasm build of the core, because a browser has no |
| A web version, from the same core 23846db nandi 9h ago | 87 | dart:ffi. The premise was right and the conclusion was wrong: the answer was |
| 88 | not wasm but `nim js`, which compiles the same core — state, reducer, every |
| 89 | screen — to JavaScript that a page loads with a `<script>` tag. |
| 90 | |
| 91 | So there is a web target again, `just build web`. What differs from the |
| 92 | desktop is only the host: `nim/web/frq/*.nim` shadows `nim/src/frq/*.nim` by |
| 93 | search path (`--path:src --path:web`, later wins), so `frq/conn` is a queue a |
| 94 | WebSocket fills rather than two socket threads, `frq/store` is localStorage, |
| 95 | and `frq/crypto` says plainly that it cannot sign. The shared code above them |
| 96 | imports the same names either way and never learns which host it is on. Dart |
| 97 | does the same thing one layer up, in `dart/frq_core/lib/src/host.dart`. |
| One frontend where there were three, and a core that is not Clojure 438b247 nandi yesterday | 98 | |
| The last of the Clojure 284b59c nandi 23h ago | 99 | ## The source trees |
| Split the tree three ways, and let the phone be Flutter's 7070931 nandi 8d ago | 100 | |
| 101 | ``` |
| A web version, from the same core 23846db nandi 9h ago | 102 | nim/src the program: state, screens, IRC, signing |
| 103 | nim/web the same program's host half, for a browser |
| 104 | dart/frq_core the binding — plain Dart, not a Flutter package |
| The last of the Clojure 284b59c nandi 23h ago | 105 | flutter/lib the renderer, and the app's entry point |
| A web version, from the same core 23846db nandi 9h ago | 106 | flutter/web the page, and the JavaScript that owns the socket |
| Split the tree three ways, and let the phone be Flutter's 7070931 nandi 8d ago | 107 | ``` |
| 108 | |
| The last of the Clojure 284b59c nandi 23h ago | 109 | `nim/src/frq/ui.nim` builds a widget tree; `frq_core` carries it across the |
| 110 | FFI as JSON; `flutter/lib/nim_renderer.dart` walks it into Flutter widgets. |
| 111 | The renderer knows the tag vocabulary and nothing else — no screens, no state, |
| 112 | no idea what "connect" means. If a feature ever needs a change on both sides, |
| 113 | the boundary is in the wrong place. |
| 114 | |
| 115 | There used to be two more trees. `src/` was jolt and libcosmic; `common/` and |
| 116 | `flutter/src/` were ClojureDart, compiled for Android, Linux and the web. Both |
| A web version, from the same core 23846db nandi 9h ago | 117 | are gone. The APK went with them and has not come back — it wants |
| 118 | `libfrqcore.so` cross-compiled for Android's ABIs — but the web target has, |
| 119 | by a different road than the one that was expected: `just build web`. |
| 120 | |
| 121 | Three things the web build does not do, all of them written down where they |
| 122 | are done rather than only here. It cannot sign a message, because Ed25519 in |
| 123 | a browser is asynchronous and every signature here is wanted inline, so a |
| 124 | reader is in a guest's position for reactions and edits. It has no |
| 125 | app-password tab, because that wants a blocking call to the reader's own PDS. |
| 126 | And it does not keep a broker token, because `localStorage` is readable by |
| 127 | every script the origin runs. |
| The last of the Clojure 284b59c nandi 23h ago | 128 | |
| 129 | Two modules were never ported and are gone rather than moved: `frq.profile` |
| 130 | (the Bluesky profile behind a nick) and `frq.replies` (asking freeq what a |
| 131 | collapsed msgid was). Neither had a screen in the Nim app to appear on. |
| 132 | |