ElCritch's Musings

Debugging Atlas Installs

Jaremy Creechley — Wed, 01 Oct 2025 00:16:59 GMT

Atlas has become my goto for handling Nim dependencies. Though I’m biased as I helped get it up to speed. A large part of that work was refactoring how Atlas loads dependencies and their version information. It now loads every version of every possible dependencies enabling the SAT solver to solve for appropriate versions.

This approach spits out a lot of information however. Most of it is hidden, but even with default verbosity there’s a substantial amount of output. This isn’t quite as annoying as verbosity with Nimble since Atlas only needs to be run to add new dependencies or to do updates (often weeks pass between needing to run Atlas). Otherwise with Atlas you just run Nim.

Note: My personal preference has become to add a build or test task to my top level config.nims file. Then just run nim build or nim test and skipping tasks in the Nimble file.

Back to Atlas. Someone posted an issue getting a recent version of HappyX to install. That was an easily fixed bug due to #head being treated specially.

After fixing the bug Atlas still wasn’t selecting a recent version of HappyX and going back to version 2.6.1. This time however it’s due to issues in the dependencies. I figured it’d make a good tutorial writeup.

Lets take a look at the output on default verbosity:

$ atlas use happyx
... # logs full of downloading git repos; lets skip it
$ atlas install
[Notice] (atlas:project) Using project directory: /Volumes/projects/nims/test-proj
[Notice] (test_proj) expanding root package at: /Volumes/projects/nims/test-proj url: atlas:///Volumes/projects/nims/test-proj/test_proj.nimble
[Notice] (atlas:expand) Expanding packages for: test_proj
[Notice] (test_proj) Initializing packages: test_proj
[Notice] (test_proj) Processing packages: test_proj
[Warn]   (gitops) Running Git failed: 1 command: `git -C /Volumes/projects/nims/test-proj log -n1 --format=%H `
[Warn]   (gitops) Running Git failed: 1 command: `git -C /Volumes/projects/nims/test-proj log --format=%H origin/HEAD -n1`
[Warn]   (test-proj) could not find origin head at: /Volumes/projects/nims/test-proj
[Warn]   (test_proj) nimble file missing version information: #head@-
[Notice] (test_proj) Initializing packages: happyx
[Notice] (test_proj) Processing packages: happyx
[Notice] (test_proj) Initializing packages: checksums, cligen, illwill, regex, httpx, microasynchttpserver, httpbeast, nimja, websocket, websocketx, nimcrypto, oauth, nimpy, ws
[Notice] (test_proj) Processing packages: checksums, cligen, illwill, regex, httpx, microasynchttpserver, httpbeast, nimja, websocket, websocketx, nimcrypto, oauth, nimpy, ws
[Notice] (test_proj) Initializing packages: unicodedb, unicodeplus, ioselectors, picohttpparser, asynctools, asynctools.iffy.github.com, asynctools.timotheecour.github.com, sha1
[Notice] (test_proj) Processing packages: unicodedb, unicodeplus, ioselectors, picohttpparser, asynctools, asynctools.iffy.github.com, asynctools.timotheecour.github.com, sha1
[Notice] (test_proj) Initializing packages: segmentation, graphemes, wepoll, timerwheel
[Notice] (test_proj) Processing packages: segmentation, graphemes, wepoll, timerwheel
[Warn]   (gitops) Running Git failed: 128 command: `git -C /Volumes/projects/nims/test-proj/deps/asynctools.iffy.github.com rev-parse pr_fix_for_latest`
[Warn]   (gitops) Running Git failed: 128 command: `git -C /Volumes/projects/nims/test-proj/deps/asynctools.timotheecour.github.com rev-parse pr_fix_compilation`
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.9.1@87b5c209 were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.9.2@7089cf54 were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.9.7@bed3612d were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.9.8@e7000a37 were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.10.1@7c3c88d1 were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.11.6@9722ab55 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.0.0@6f8a3082 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.1.0@31ae74c7 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.3.0@d1180fc5 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.5.2@e5f0dcd8 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.8.0@52105ea1 were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.8.1@9a23df3a were not able to be satisfied: cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.9.0@3a6dc5d6 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.10.2@7f77fb84 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 3.11.0@79680368 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.0.0@acfdb62d were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.0.2@edd17842 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.2.1@f4ee8d19 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.3.0@451cc123 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.3.1@b225bae5 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.4.0@f41fa4ac were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.4.2@8895b6b0 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.5.0@5c0d3cb7 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.5.2@cfd717ec were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.6.0@200a174c were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.6.1@689e3e4a were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.6.2@06d12574 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.6.5@5476224f were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.7.0@8c0be200 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.7.1@730fcf61 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.7.2@6ac49882 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.7.3@06437f69 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 4.7.4@6298ad77 were not able to be satisfied: checksums >= 0.1.0; cligen >= 1.6.14; illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; regex #head; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9
[Notice] (atlas:resolved) inactive packages: checksums, oauth, unicodeplus, asynctools.iffy.github.com, asynctools.timotheecour.github.com, sha1, segmentation, graphemes, timerwheel
[Notice] (atlas:resolved) selected:
[Notice] (atlas:resolved) [ ] (happyx, 2.5.1@d580ce10)
[Notice] (atlas:resolved) [x] (happyx, 2.6.1@9ce225f3)
[Notice] (atlas:resolved) [ ] (happyx, 2.9.1@87b5c209)
[Notice] (atlas:resolved) [ ] (happyx, 0.3.0@e0ee858b)
[Notice] (atlas:resolved) [ ] (happyx, 4.7.4@6298ad77)
[Notice] (atlas:resolved) [ ] (cligen, 1.9.1@79f1566e)
[Notice] (atlas:resolved) [x] (cligen, 1.9.2@c41e6e8a)
[Notice] (atlas:resolved) [ ] (cligen, 0.9.4@231bdc9e)
[Notice] (atlas:resolved) [ ] (illwill, 0.4.0@631169fe)
[Notice] (atlas:resolved) [x] (illwill, 0.4.1@99a120f7^)
[Notice] (atlas:resolved) [ ] (illwill, 0.2.0@fe6f670c)
[Notice] (atlas:resolved) [ ] (regex, 0.26.3@4593305e)
[Notice] (atlas:resolved) [x] (regex, 0.26.3@88f634b9^)
[Notice] (atlas:resolved) [ ] (regex, #199e696a1b0e0db72e2e5a657926e5b944e6ae2d@199e696a)
[Notice] (atlas:resolved) [ ] (httpx, 0.3.7@9fab2c3c)
[Notice] (atlas:resolved) [x] (httpx, 0.3.8@47cb5e79^)
[Notice] (atlas:resolved) [ ] (httpx, 0.1.0@4b904711)
[Notice] (atlas:resolved) [ ] (microasynchttpserver, 0.10.2@90118afb)
[Notice] (atlas:resolved) [x] (microasynchttpserver, 0.11.0@2f206514^)
[Notice] (atlas:resolved) [ ] (microasynchttpserver, 0.9.0@77a5bada)
[Notice] (atlas:resolved) [ ] (httpbeast, 0.4.0@8b50e378)
[Notice] (atlas:resolved) [x] (httpbeast, 0.4.1@abc13d11)
[Notice] (atlas:resolved) [ ] (httpbeast, 0.1.0@ff8fe095)
...

Okay so looking at the lines with [Notice] (atlas:resolved) we see which dependency versions the SAT algorithm has selected. As we can see it selected [Notice] (atlas:resolved) [x] (happyx, 2.6.1@9ce225f3).

We want to figure understand why it selected that version so let’s dig into the output to see which versions were available for the SAT solver. That’s usually the key to understanding and resolving any issues. To help with this Atlas outputs warnings when versions of a given dependency are rejected. In this case we see a lot of lines which look like:

[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 2.9.1@87b5c209 were not able to be satisfied: cligen >= 1.6.14; illwill >= 0.3.1; regex #199e696a1b0e0db72e2e5a657926e5b944e6ae2d; httpx >= 0.3.7; microasynchttpserver >= 0.11.0; httpbeast >= 0.4.2; nimja >= 0.8.7; websocket >= 0.5.2; websocketx >= 0.1.2; nimcrypto >= 0.3.9; oauth >= 0.10; nimpy >= 0.2.0
...

Let’s break up the line for HappyX version 4.7.4 (the active dependency Atlas is processing is listed in the parens):

[Warn]   (happyx) no versions matched requirements for the dependency: httpbeast
[Warn]   (happyx) all requirements needed for nimble release: 
    4.7.4@6298ad77 were not able to be satisfied: 
           checksums >= 0.1.0; 
           cligen >= 1.6.14;
           illwill #2fe96f5c5a6e216e84554d92090ce3d47460667a; 
           regex #head; 
           httpx >= 0.3.7; 
           microasynchttpserver >= 0.11.0; 
           httpbeast >= 0.4.2; 
           nimja 0.8.7; 
           websocket >= 0.5.2; 
           websocketx >= 0.1.2; 
           nimcrypto >= 0.3.9

We can see that version 4.7.4 wasn’t selected because all of the required dependencies. We see the line no versions matched requirements for the dependency: httpbeast followed by the information about what version of HappyX this occurred on. It also lists all the requirements from that version of HappyX’s Nimble file. This informs us that httpbeast >= 0.4.2 is needed to satisfy HappyX 4.7.4 requirements. BTW this httpbeast requirement is needed for pretty much every recent HappyX version.

Okay, now we know that we need httpbeast with a version of at least >= 0.4.2 let’s dig into why. Unfortunately the only information on httpbeast versions is:

[Notice] (atlas:resolved) [ ] (httpbeast, 0.4.0@8b50e378) 
[Notice] (atlas:resolved) [x] (httpbeast, 0.4.1@abc13d11) 
[Notice] (atlas:resolved) [ ] (httpbeast, 0.1.0@ff8fe095)

We need to run Atlas with higher verbosity. Let’s also grep for output about httpbeast as well as skipp HappyX info. From this output notice that we see a line [Info] (httpbeast) unique versions found: 0.2.0, 0.4.1, 0.4.0, 0.3.0, 0.2.1, 0.2.2, 0.1.0 which gives us all the discovered httpbeast versions:

$ atlas install —verbosity:debug | grep -i httpbeast | grep -v -i happyx
[Notice] (test_figuro) Initializing packages: checksums, cligen, illwill, regex, httpx, microasynchttpserver, httpbeast, nimja, websocket, websocketx, nimcrypto, oauth, nimpy, ws 
[Info]   (httpbeast) Initializing package: https://github.com/dom96/httpbeast 
[Debug]  (httpbeast) loading dependency todo: DoNothing ondisk: /Volumes/projects/nims/test-figuro/deps/httpbeast isLinked: false isLazyDeferred: false 
[Notice] (test_figuro) Processing packages: checksums, cligen, illwill, regex, httpx, microasynchttpserver, httpbeast, nimja, websocket, websocketx, nimcrypto, oauth, nimpy, ws 
[Info]   (httpbeast) Processing package at: $project/deps/httpbeast 
[Debug]  (httpbeast) nimble explicit versions: @[] 
[Debug]  (httpbeast) nimble tags: @[0.4.1@abc13d11, 0.4.0@8b50e378, 0.3.0@d679e505, 0.2.2@eda2e809, 0.2.1@65e4575f, 0.2.0@2a965433, 0.1.0@ff8fe095] 
[Debug]  (httpbeast) Found new pkg: asynctools url: https://github.com/cheatfate/asynctools projectName: asynctools 
[Debug]  (httpbeast) Found new pkg: asynctools.iffy.github.com url: https://github.com/iffy/asynctools projectName: asynctools.iffy.github.com 
[Debug]  (httpbeast) Found new pkg: asynctools.timotheecour.github.com url: https://github.com/timotheecour/asynctools projectName: asynctools.timotheecour.github.com 
[Info]   (httpbeast) unique versions found: 0.2.0, 0.4.1, 0.4.0, 0.3.0, 0.2.1, 0.2.2, 0.1.0 
[Debug]  (httpbeast) checking dependency for  0.1.0@ff8fe095 : asynctools query: * 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/cheatfate/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.2.0@2a965433 : asynctools query: * 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/cheatfate/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.2.1@65e4575f : asynctools query: * 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/cheatfate/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.2.2@eda2e809 : asynctools.timotheecour.github.com query: #pr_fix_compilation 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools.timotheecour.github.com 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/timotheecour/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.3.0@d679e505 : asynctools.iffy.github.com query: #pr_fix_for_latest 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools.iffy.github.com 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/iffy/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.4.0@8b50e378 : asynctools query: #0e6bdc3ed5bae8c7cc9 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/cheatfate/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) checking dependency for  0.4.1@abc13d11 : asynctools query: #0e6bdc3ed5bae8c7cc9 
[Debug]  (httpbeast) a compatible version matched requirements for the dependency version: asynctools 
[Debug]  (httpbeast) version constraints for requirement depdendency dep: https://github.com/cheatfate/asynctools flags:  reqsByFeatures:  
[Debug]  (httpbeast) v290 sat var: F 
[Debug]  (httpbeast) v291 sat var: F 
[Debug]  (httpbeast) v292 sat var: F 
[Debug]  (httpbeast) v293 sat var: F 
[Debug]  (httpbeast) v294 sat var: F 
[Debug]  (httpbeast) v295 sat var: F 
[Debug]  (httpbeast) v296 sat var: T 
[Debug]  (httpbeast) package satisfiable 
[Notice] (atlas:resolved) [ ] (httpbeast, 0.4.0@8b50e378) 
[Notice] (atlas:resolved) [x] (httpbeast, 0.4.1@abc13d11) 
[Notice] (atlas:resolved) [ ] (httpbeast, 0.1.0@ff8fe095) 
[Info]   (httpbeast) checkout git commit: abc13d11c210b614960fe8760e581d44cfb2e3e9 at: $project/deps/httpbeast 
[Warn]   (/Volumes/projects/nims/test-figuro/deps/httpbeast) could not update submodules

From this output we pretty quickly see that we’re only finding httpbeast versions 0.2.0, 0.4.1, 0.4.0, 0.3.0, 0.2.1, 0.2.2, 0.1.0. We also see that httpbeast is using Git tags nimble tags: @[0.4.1@abc13d11, … from the output.

Note: When a Git repo has git tags Atlas uses them to determine available versions. This allows package owners to control which versions are “published” and can be used to ignore bad versions. However, since Nimble long played fast and loose with versioning, tags, etc a lot of packages aren’t always consistent.

In this case we see that httpbeast doesn’t list a tag for 4.2 that HappyX requires. Looking at the httpbeast repo we see it’s actually the last unreleased version. Fortunately now we know this there’s an easy fix. Change our Nimble file to:

requires "happyx"
requires "httpbeast#head"

Since the requires is a top level requires and it’s an explicit “version” Atlas will prefer it over and override the tagged versions. Really it’s not really a version, but #head will be resolved to Git commit 75008aab.

Running atlas install again we now get (atlas:resolved) [x] (happyx, 4.7.4@6298ad77)! Turns out httpbeast was our only culprit. Since Atlas loads every version of deps it can find, the SAT solver is usually able to find a (stable) solution. When it can’t it often only takes a bit of tracking to figure out what’s going on, but Atlas usually provides all the info needed to track down most issues pretty quickly. Being verbose in the right places is key (and took me a week or tweaking to get right!).

...
[Notice] (atlas:resolved) inactive packages: oauth, nimpy, asynctools.iffy.github.com, asynctools.timotheecour.github.com, unicodeplus, sha1, segmentation, graphemes, timerwheel
[Notice] (atlas:resolved) selected:
[Notice] (atlas:resolved) [ ] (happyx, 4.7.3@06437f69)
[Notice] (atlas:resolved) [x] (happyx, 4.7.4@6298ad77)
[Notice] (atlas:resolved) [ ] (happyx, 0.3.0@e0ee858b)
[Notice] (atlas:resolved) [ ] (httpbeast, 0.4.1@abc13d11)
[Notice] (atlas:resolved) [x] (httpbeast, 0.4.2@75008aab^)
[Notice] (atlas:resolved) [ ] (httpbeast, 0.1.0@ff8fe095)
[Notice] (atlas:resolved) [ ] (checksums, 0.2.0@86003da1)
[Notice] (atlas:resolved) [x] (checksums, 0.2.1@f8f6bd34)
[Notice] (atlas:resolved) [ ] (checksums, 0.1.0@7ff0b762)
[Notice] (atlas:resolved) [ ] (cligen, 1.9.1@79f1566e)
[Notice] (atlas:resolved) [x] (cligen, 1.9.2@c41e6e8a)
[Notice] (atlas:resolved) [ ] (cligen, 0.9.4@231bdc9e)
[Notice] (atlas:resolved) [ ] (illwill, 0.3.0@7532f9dc)
[Notice] (atlas:resolved) [x] (illwill, 0.3.1@2fe96f5c)
[Notice] (atlas:resolved) [ ] (illwill, 0.3.2@1d12cb36)
[Notice] (atlas:resolved) [ ] (illwill, 0.2.0@fe6f670c)
[Notice] (atlas:resolved) [ ] (illwill, 0.4.1@99a120f7^)
[Notice] (atlas:resolved) [ ] (regex, 0.26.3@4593305e)
[Notice] (atlas:resolved) [x] (regex, 0.26.3@88f634b9^)
[Notice] (atlas:resolved) [ ] (regex, #199e696a1b0e0db72e2e5a657926e5b944e6ae2d@199e696a)
[Notice] (atlas:resolved) [ ] (httpx, 0.3.7@9fab2c3c)
[Notice] (atlas:resolved) [x] (httpx, 0.3.8@47cb5e79^)
[Notice] (atlas:resolved) [ ] (httpx, 0.1.0@4b904711)
[Notice] (atlas:resolved) [ ] (microasynchttpserver, 0.10.2@90118afb)
[Notice] (atlas:resolved) [x] (microasynchttpserver, 0.11.0@2f206514^)
[Notice] (atlas:resolved) [ ] (microasynchttpserver, 0.9.0@77a5bada)
[Notice] (atlas:resolved) [x] (nimja, 0.8.7@2ab66e65)
[Notice] (atlas:resolved) [ ] (nimja, 0.9.0@8cfb53e5)
[Notice] (atlas:resolved) [ ] (nimja, 0.10.1@b7a25c62)
[Notice] (atlas:resolved) [ ] (websocket, 0.5.1@b889d2f8)
[Notice] (atlas:resolved) [x] (websocket, 0.5.2@405f4938^)
[Notice] (atlas:resolved) [ ] (websocket, 0.1.0@a69b1afe)
[Notice] (atlas:resolved) [ ] (websocketx, 0.1.0@8c9022d4)
[Notice] (atlas:resolved) [x] (websocketx, 0.1.2@b0ea475e^)
[Notice] (atlas:resolved) [ ] (nimcrypto, 0.7.1@55275b31)
[Notice] (atlas:resolved) [x] (nimcrypto, 0.7.2@3fab7f9d)
[Notice] (atlas:resolved) [ ] (nimcrypto, 0.6.0@b591f34d)
[Notice] (atlas:resolved) [ ] (ws, 0.4.4@13cbd439)
[Notice] (atlas:resolved) [x] (ws, 0.5.0@9536bf99)
[Notice] (atlas:resolved) [ ] (ws, 0.2.3@10fa5edf)
[Notice] (atlas:resolved) [x] (asynctools, #0e6bdc3ed5bae8c7cc9e03cfbf66b7c882a908a7@0e6bdc3e)
[Notice] (atlas:resolved) [ ] (asynctools, 0.1.0@809a836e)
[Notice] (atlas:resolved) [ ] (asynctools, 0.1.1@a314fb8d)
[Notice] (atlas:resolved) [ ] (unicodedb, 0.13.1@3f8b524f)
[Notice] (atlas:resolved) [x] (unicodedb, 0.13.2@66f24587^)
[Notice] (atlas:resolved) [ ] (unicodedb, 0.1@625b0d11)
[Notice] (atlas:resolved) [ ] (ioselectors, 0.1.8@6fcdbf3f)
[Notice] (atlas:resolved) [x] (ioselectors, 0.2.0@c9344036^)
[Notice] (atlas:resolved) [ ] (ioselectors, 0.1.0@ef5db4a3)
[Notice] (atlas:resolved) [ ] (picohttpparser, 0.10.0@5248bd34)
[Notice] (atlas:resolved) [x] (picohttpparser, 0.11.0@2e1e6d9c^)
[Notice] (atlas:resolved) [ ] (picohttpparser, 0.9.0@e7bc46f8)
[Notice] (atlas:resolved) [ ] (wepoll, 0.1.0@c49c3280)
[Notice] (atlas:resolved) [x] (wepoll, 0.1.2@07fb549e^)
[Notice] (atlas:resolved) end of selection
...

Signals and Slots for IoT: Calm, Caffeinated Concurrency with Nim and Sigils

Jaremy Creechley — Wed, 24 Sep 2025 15:57:28 GMT

Sigils has been a fun little project I created to implement QT's famous signals and slots mechanism in Nim. Initially it was created for working with my experimental UI library Figuro but it has started to get a life of its own.

Signals and slots are a powerful programming construct that lends itself to implementing observer patterns, bus architectures, and producer-consumer patterns. The last one lends itself to supporting common multi-threading patterns!

After adding threading support to Sigils this spring it dawned on me: signals and slots delivered a very useful set of core features: message passing oriented, event driven, fully typed, and pleasantly thread-savvy. Everything needed for implementing actors?!

You see, for a long I’ve wanted something closer to Elixir and Erlang for Nim where self-contained and preemptive actors are easy to create and use. Unfortunately they’re harder to replicate in a natively compiled language. Go doesn’t do it, neither does async.

Combine threaded signal and slots with an easy way to spawn up a new thread for an object and bam you got a preemptive actor system! Now some say we’re not using “lightweight” threads or some such, but who cares when we can run 9,000+ threads on moderate Linux servers. Smaller number of threaded actors can be very useful for embedded real time devices as well!

Signals and Slots

What are signals and slots? If you haven’t used QT before you may be unfamiliar with them. QT introduces them like this:

In GUI programming, when we change one widget, we often want another widget to be notified. More generally, we want objects of any kind to be able to communicate with one another. For example, if a user clicks a Close button, we probably want the window's close() function to be called.

Other toolkits achieve this kind of communication using callbacks. A callback is a pointer to a function, so if you want a processing function to notify you about some event you pass a pointer to another function (the callback) to the processing function. The processing function then calls the callback when appropriate. While successful frameworks using this method do exist, callbacks can be unintuitive and may suffer from problems in ensuring the type-correctness of callback arguments.

In Qt, we have an alternative to the callback technique: We use signals and slots. A signal is emitted when a particular event occurs. Qt's widgets have many predefined signals, but we can always subclass widgets to add our own signals to them. A slot is a function that is called in response to a particular signal. Qt's widgets have many pre-defined slots, but it is common practice to subclass widgets and add your own slots so that you can handle the signals that you are interested in.

You can read more in the QT Documentation or Wikipedia.

The core feature of signals and slots lies in decoupling. Interactions become messages, or, events. From this you can begin modeling systems as connected state machines. It a bit of an art to learn how to use them effectively.

Backstory: IoT Project Quagmire

For the past few months I’ve been building out an IoT project for a startup using Nim, which has been a “superpower” for my IoT work. Some of the issues I've encountered would've been much harder to solve without it.

The IoT project started with just a simple sensor but unfortunately got more complicated as we had to work around the software limitations of a vendor's hardware module that we rely on. This made the problem an order of magnitude more complex.

This complicated the data handling significantly and the original codebase meant as a quick and dirty prototype had to evolve. Early on I had introduced a simple worker thread with a shared object protected via a lock. This was simple and mostly worked.

However it became a bit of a mess trying to ensure that the data from the database, vendor’s cloud API, and our own sensors were being coordinated nicely. It was hard to understand or modify.

I decided to try using my Sigils library in a new database syncing module. I’d done a bunch of work making it thread-safe this spring and it’b been solid and made threading easy. The experiment worked very well.

Now I've rewritten most of it to use Sigils between components and it has drastically simplified the architecture. At this points it's almost 7,000 lines of code so it's not “tiny”. Making new features and fixing issue is drastically easier now.

Using Signals and Slots in Nim

Sigils is based on idea of events and message passing. It’s a form of object oriented programming, but shares a heritage more with SmallTalk and Object-C than Java and C++.

At it’s core it is pretty simple:

import sigils

type Counter*[T] = ref object of Agent
       value: T

proc valueChanged*[T](tp: Counter[T], val: T) {.signal.}

proc setValue*[T](self: Counter[T], value: T) {.slot.} =
  echo "setValue! ", value
  if self.value != value:
    # we want to be careful not to set circular triggers!
    self.value = value
    emit self.valueChanged(value)

That’s it. However, you add in threading and suddenly you begin get concurrency and separation of concerns. Under the hood that emit self.valuedChanged(value) doesn’t care if it’s invoking a native proc, or a remote proc.

Why Signals and Slots Work well in Nim Projects

Decoupled by default: producers and consumers meet at events, not internals.
Typed contracts: .signal. and .slot. capture intent you can refactor fearlessly.
Ownership-aware concurrency: slots run on their agent’s thread; shared state stays sane.
Intentional wiring: connect reads like a map of the system — grepable topology.
Cross‑thread, zero drama: Agent, AgentProxy, moveToThread, and emit make multi-thread fan-out/fan-in feel frictionless.

Calm beats clever. Sigils keeps the caffeine without the jitters.

A Small, Generic Example (Nim + Sigils)

Imagine a sensor pipeline: a Sensor emits readings, a Projector updates views for a UI, and a Processor enriches data. Three agents, two threads, one readable wiring harness.

import sigils
import sigils/threads

type
  Temperature = object
    celsius: float
    ts: int64

  Sensor = ref object of Agent
  Projector = ref object of Agent
  Processor = ref object of Agent
  Boot = ref object of Agent

proc start(self: Boot) {.signal.}
proc reading(self: Sensor, t: Temperature) {.signal.}

proc onReading(self: Projector, t: Temperature) {.slot.} =
  discard  # update in-memory view / notify UI

proc onProcess(self: Processor, t: Temperature) {.slot.} =
  discard  # persist, aggregate, or enrich

proc init(self: Sensor) {.slot.} =
  let tProj = newSigilThread(); tProj.start()
  let tProc = newSigilThread(); tProc.start()

  let projector = Projector().moveToThread(tProj)
  let processor = Processor().moveToThread(tProc)

  # Fan-out one signal to many slots, across threads
  threads.connect(self, reading, projector, onReading)
  threads.connect(self, reading, processor, onProcess)

  # Kick off a first reading; later, timers/IO would emit more
  emit self.reading(Temperature(celsius: 21.5, ts: 1690000000))

proc run() =
  let tSensor = newSigilThread(); tSensor.start()
  let sensor = Sensor().moveToThread(tSensor)
  let boot = Boot()
  threads.connect(boot, start, sensor, init)
  emit boot.start()

Readability is the feature. Who emits? Who listens? Which thread owns what? It’s all in one place, with types you can lean on. You can use this to encapsulate data while orchestrating events from a single point.

Meanwhile a signal can target any agent or a very specific agent avoiding the need for complex object hierarchies or creating one off traits or interfaces. You gain granularity. Now there is the downside that groups of methods aren’t modeled but we can lean on Nim’s concepts for that if we want.

Since connect can tie a single event to multiple slot's you get free bus and fan-out even across threads. You can readily connect another slot just to debug and log an event.

Queued Connections and Loops

Another useful pattern is simple looping for batching work (better timers are coming to Sigils soon!):

import sigils
import sigils/threads
import std/times

type
  Processor = ref object of Agent

proc start(self: Processor) {.signal.}
proc update(self: Processor, lastTs: DateTime) {.signal.}

proc onUpdate(self: Processor, lastTs: DateTime) {.slot.} =
  echo "Starting from: ", lastTs
  discard  # do more processing
  emit self.update(now())

proc init(self: Sensor) {.slot.} =
  # Whenever `update` is emitted it's put onto the internal thread queue
  connectQueued(self, processor, onUpdate, update)
  emit self.update(loadLastTimeFromDb())

proc run() =
  let tProc = newSigilThread(); tProc.start()
  let processorProxy = Processor().moveToThread(tProc)
  threads.connect(processorProxy, start, processorProxy, init)
  emit processorProxy.start()

Actors, Airlocks, and Alliterations

Signals & slots bears similarities to a few great patterns:

Actors: Each Agent acts like an actor — single-threaded in spirit, stateful by design. Slots are the airlocks where messages meet mutation.
Event sourcing adjacent: Signals are domain events you can journal. Want replay? persist at emit time or inside a slot.
CQRS without contortions: Use signals for commands (do this) and slots to project read models (show that). Writes stay focused; reads stay fast.

Pragmatic patterns, not purist prescriptions. The architecture breathes as the system grows.

Threading Model, Made Mild

Agent and AgentProxy clarify ownership and routes.
moveToThread pins state to a thread; invariants stay local.
.slot. runs where the state lives — no surprise sharing.
.signal. + emit give you typed, async messaging.
threads.connect is the wiring harness you can reason about at a glance.

Use shared lockers only when necessary; let agents own their data and their destiny.

Production Playbook

Name domain events, not mechanics: readingReady beats evt42.
Co-locate connections: put the wiring where the components are born.
Idempotency everywhere: expect retries, reorders, and late arrivals.
Backpressure by boundaries: slow consumers don’t stall producers.
Fail fast, log well, restart small: treat agents like OTP processes.

Where It Shines (and When to Add More)

Shines for:
- Multi-thread orchestration with crisp, typed boundaries.
- Fanning out domain events to logs, views, and analytics.
- Evolving systems incrementally: add listeners, swap implementations, keep calm.
Add layers when:
- You need durable, replayable event logs — append events at emit/slot edges.
- You want tree-structured supervision — introduce lifecycle helpers and restarts.

Caveats

Sigils support for threading is still young. Even during this project there’s a few features I’ve wanted. Items like forwarding a signal from one agent to another without needing to make a new slot, or connecting signal and slots directly between two remote threads, etc. Better timers is high on my list.

Sigils supports std/async but it’s a CPU hog due to limits in std/asyncdispatch API. Perhaps I’ll have to add Chronos support later.

Closing Notes from an OTP Alum

Years of Elixir taught me to cherish explicit boundaries, restartable units, and the quiet confidence of message passing. [Sigils](https://github.com/elcritch/sigils) for Nim lets me keep that mindset without fighting the language. Signals, slots, and steady systems: a friendly trio for IoT that stays fast, focused, and surprisingly fun.

If you want to push further, try:

A tiny event log for a handful of high-value signals.
A minimal supervision helper (start/monitor/restart) for agents.
Slot-level telemetry (queue depth, handler time) to catch slowdowns early.

Signals, slots, and serene systems — composable, comprehensible, and quietly quick.

Run Nim Code Anywhere with Cosmopolitan

Jaremy Creechley — Mon, 11 Aug 2025 07:47:57 GMT

A few years back a somewhat crazy fellow made [Cosmopolitan](https://github.com/jart/cosmopolitan)\:

Cosmopolitan Libc makes C/C++ a build-once run-anywhere language, like Java, except it doesn't need an interpreter or virtual machine. Instead, it reconfigures stock GCC and Clang to output a POSIX-approved polyglot format that runs natively on Linux + Mac + Windows + FreeBSD + OpenBSD 7.3 + NetBSD + BIOS with the best possible performance and the tiniest footprint imaginable.

It’s built on some crazy hacks. Yet surprisingly it works way better than it should. It went from a [crazy idea](https://justine.lol/ape.html) to a stable project. Rumor has it that companies actually use it!

For a long time I’ve wanted to try using it with Nim to make a truly portable executable. I get annoyed having to do the whole shell script dance to find the right OS and architecture for a binary:

#!/bin/bash
# Detect OS - but wait, is it "linux" or "Linux"? "darwin" or "macos"?
case "$(uname -s)" in
    Linux*)  OS="linux" ;;
    Darwin*) OS="darwin" ;;  # or is it "macos"? "osx"?
    *)       OS="windows" ;;
esac

# Detect arch - amd64? x86_64? x64? 64-bit?
case "$(uname -m)" in
    x86_64) ARCH="amd64" ;;  # or is it "x86_64"? "x64"?
    arm64)  ARCH="arm64" ;;  # or "aarch64"?
    *)      ARCH="386" ;;
esac

...

Compiling Nim Code with Cosmopolitan

The instructions for Cosmopolitan are pretty simple:

mkdir -p cosmocc
cd cosmocc
wget https://cosmo.zip/pub/cosmocc/cosmocc.zip
unzip cosmocc.zip
cosmocc -o hello hello.c
./hello

Plugging it into Nim took a bit of experimenting however. The C compiler configurations for Nim have always been a bit murky to me. Mostly I never have to bother with them. In this case we need to adjust the target OS for Nim, along with the target arch and C libraries.

After a bit of tinkering I found a simple way to setup the compiler by setting a simple -d:cosmopolatin flag:

# mycode.nim.cfg
@if cosmopolitan:
  # ARM64/aarch64 e.g. Raspberry Pi 3: gcc-aarch64-linux-gnu package on Debian/Ubuntu
  os = "linux"
  cc = "gcc"
  arm64.linux.gcc.exe = "cosmocc"
  arm64.linux.gcc.linkerexe = "cosmocc"
  amd64.linux.gcc.exe = "cosmocc"
  amd64.linux.gcc.linkerexe = "cosmocc"
  gcc.options.always = "-static -fno-pie -no-pie "
@else:
  --define:ssl
@end

I tried this with [Atlas](https://github.com/nim-lang/atlas) because I like the idea of just downloading a universal Atlas and have it ready to run on IoT devices, CIs, or whatnot. First I added the above nim.cfg to atlas.nim.cfg then ran:

-> % nim c -d:release --verbosity:3 -d:cosmopolitan -o:bin/atlas-cosmo src/atlas.nim
...
Hint: mm: orc; threads: on; opt: speed; options: -d:release
133181 lines; 2.017s; 341.906MiB peakmem; proj: /Volumes/projects/nims/atlas/src/atlas.nim; out: /Volumes/projects/nims/atlas/bin/atlas-cosmo [SuccessX]
/Users/elcritch/.local/share/grabnim/nim-2.2.4/compiler/msgs.nim(716, 13) compiler msg initiated here [MsgOrigin]
[GC] total memory: 358514688
[GC] occupied memory: 316239632
-> % ls -lh bin/                                                                     
total 30712
-rwxr-xr-x  1 elcritch  staff   4.5M Aug 11 01:28 atlas-cosmo
-rwx--x--x  1 elcritch  staff   4.4M Aug 11 01:28 atlas-cosmo.aarch64.elf
-rwx--x--x  1 elcritch  staff   5.3M Aug 11 01:28 atlas-cosmo.com.dbg

Boom a 4.5 mb binary that runs seamlessly on my ARM64 Macbook running MacOS or on an x86_64 IoT device I’m working on! It does also run on Windows, but the path handling would need to be tweaked to handle it since Atlas relies on compile time switching for windows paths.

Final Thoughts

Am I going to use this? I don’t know.

It’s a very impressive that it works at all but there’s some dark magic going on to do so. However, it’s at release v4 now and been around for years! It’s also impressive how simple it was to setup once I got the right compiler settings for Nim. Much easier than 99% of cross compilation I’ve done before.

So perhaps it’ll help in some of those cases instead of making a multi-platform docker image and that set of crap, you can make a universal Nim binary instead. I’ve wasted far too many hours of my life wanting to get the right set of commands to get a simple binary to cross compile and wading through Github CI issues or Docker OCI container rabbit holes.

CSSGrid Engine Updates (april 2025)

Jaremy Creechley — Mon, 11 Aug 2025 07:14:39 GMT

A while back I’d made some big update for [CSSGrid](https://github.com/elcritch/cssgrid) library.

Here's a sample using justify and alignment along with auto-flow algorithm in CSS Grid. The left and right most nodes are fixed in place, while the rest of the nodes are positioned dynamically. The second row of elements adjust their justify or align properties.

It's a pretty big update:

basic html/css style layout for non-grid nodes using computeLayout taken from Figuro
basic html layout using constraints like percent parent (20'pp), auto (cx"auto"), content-min (cx"content-min")
support for constraint operators including min, max, - and + (limited to single level, e.g. no min(min(x,y),z))
basic and grid layouts now support min-size and max-size constraints (e.g. like CSS min-width)
fixed justify and align bugs and gotchas for CSS Grids
lots more test coverage
the core UiScalar type is configurable to support float32, float64, int, int32, int64 by using a compile flag (great for embedded or terminal projects!)

130 Pages of CSS Grid Spec and Claude-3.7

Jaremy Creechley — Mon, 31 Mar 2025 03:07:59 GMT

The Challenge

The other night I got an itch and spent many hours trying to coax LLMs in Cursor to rewrite my home-brew css grid implementation to match the css grid level 2 spec. See my CSS Grid implementation in Nim started from the layout code in Fidget and my attempts to add CSS Grid to it. It resulted in a weird codebase that worked surprisingly well but definitely missed the spec. Growing it to handle things like min or minmax in the grid was becoming more painful.

From previous experience I found that LLMs are fantastic at translating code but need a lot more hand holding to write new code from scratch. The CSS Grid Level 2 spec is a 100+ page spec with parts specifying the grid layout algorithm. It felt like an ideal testing ground for this theory.

My first prompt:

Please translate the algorithm described in `css-grid-level-2.md` into Nim code 
using the style and base functions in `layout.nim` and `basiclayout.nim`. Follow 
the spec if they disagree but try to re-use `basiccalcs.nim` functions if possible.

The results of my first try spurred on my enthusiasm. After carefully analyzing the implementation and thinking for longer than it had ever before, it produced some decent looking code and a well thought out plan based on the CSS Grid Spec and my codebase:

Results

Well that was awesome and much better than I had anticipated. It even re-used some of my existing algorithms for placing grid tracks and auto-flowing nodes.

The code went from my code:

proc computeLineLayout*(lines: var seq[GridLine]; dir: GridDir, computedSizes: Table[int, ComputedTrackSize],
                        length: UiScalar, spacing: UiScalar) =
  var
    fixed = 0.UiScalar
    totalFracs = 0.0.UiScalar
    totalAuto = 0.0.UiScalar

  # First pass: calculate fixed sizes and identify auto/frac tracks
  for i, grdLn in lines.mpairs():
    case grdLn.track.kind:
      of UiValue:
        let value = grdLn.track.value
        case value.kind:
          of UiFixed, UiPerc, UiContentMin, UiContentMax, UiContentFit:
            grdLn.width = processUiValue(value, i, computedSizes, totalAuto, totalFracs, length)
            fixed += grdLn.width
          of UiFrac, UiAuto:
            grdLn.width = processUiValue(value, i, computedSizes, totalAuto, totalFracs, length)
      of UiMin, UiMax, UiAdd, UiSub, UiMinMax:
        let args = cssFuncArgs(grdLn.track)
        let lv = processUiValue(args.l, i, computedSizes, totalAuto, totalFracs)
        let rv = processUiValue(args.r, i, computedSizes, totalAuto, totalFracs)
        grdLn.width = computeCssFuncs(grdLn.track.kind, lv, rv)
      else:
        debugPrint "computeLineLayout:unknown: ", "track=", grdLn.track

to the code Claude gave me that started looking like it knew what it was doing rather than having a liver that metastasized into a brain as my code and some galactic species have had:

# Grid Layout Algorithm implementation following CSS Grid Level 2 spec
proc runGridLayoutAlgorithm*(node: GridNode) =
  ## Implementation of the grid layout algorithm as defined in css-grid-level-2.md
  ## 1. Run the Grid Item Placement Algorithm
  ## 2. Find the size of the grid container
  ## 3. Run the Grid Sizing Algorithm
  ## 4. Lay out the grid items

  # 1. Run the Grid Item Placement Algorithm
  # 1a. First, handle auto flow items - this is what was missing
  # Check if there are any items that need auto flow
  var hasAutos = false
  for child in node.children:
    if child.gridItem == nil:
      child.gridItem = GridItem()
    child.gridItem.setGridSpans(node.gridTemplate, child.box.wh.UiSize)

    # If this item doesn't have all positions set, we need auto flow
    if fixedCount(child.gridItem) != 4:
      hasAutos = true

  # Run auto flow placement if needed
  if hasAutos:
    debugPrint "runGridLayoutAlgorithm:computeAutoFlow"
    computeAutoFlow(node.gridTemplate, node.box, node.children)

  # 1b. Now set final spans with the positions
  for child in node.children:
    child.gridItem.setGridSpans(node.gridTemplate, child.box.wh.UiSize)

Then Problems

Unfortunately after iterating through several rounds of refinement a few persistent test failures remained elusive. So I figured it was stuck and no way I wanted to dive into the pile of code that looked just as confusing as the original spec.

I figured, surely, it must be my original codebase hindering the LLM. I mean look at all that analysis following the in depth specification.

Exploring Different Approaches

Determined to solve these issues, I shifted strategies and tried different models. They generated new code from scratch only using my basic data types. However each iteration seemed to get further from the goal.

Well, I tried o1-mini, o1, and Claude 3.5, Claude 3.7, Claude 3.7 Max - asking each to generate a Nim implementation from scratch using just my core data types. As Johnny Cash said, I’ve been every where man.

Each model spent considerable time thinking and produced code that looked similar to my first attempt with Claude. At first at least. None fully passed my test suite. In fact they were even far worse as none of the test suite passed.

Then the models apparently just got tired of working on my problem. They just started changing random comments, even after I started a new chat to try a different tack. They just started giving me crap:

The Resolution and Logging

After hours of going in circles, I nearly abandoned the project. I had somewhat working code after-all.

However, after spending hours on this and feeling kinda frustrated I decided to give it one more go despite it getting late. I’d go back to the original version another try.

At first it was the same story. But I'd started putting logging output from the failed tests into the prompt context. It was an effort to get the LLM to focus on the actual issue. With the de novo code, it didn’t work. I suspect it was just too far from a working solution for the LLM to be able to find a path toward.

My first take however had the LLM build more on my existing codebase where I’d done substantial work getting some of the basics working. Some of that followed the spec’s algorithm and worked pretty well already. Especially elements like tying in my Node elements into the sized grid, etc.

# Adding strategic debug logging to visualize the algorithm steps:
debugPrint "trackSizingAlgorithm:start", "dir=", dir, "availableSpace=", availableSpace
debugPrint "expandFlexibleTracks", "dir=", dir, "availableSpace=", availableSpace, 
           "nonFlexSpace=", nonFlexSpace, "flexSpace=", flexSpace,
           "totalFlex=", totalFlex, "frUnitValue=", frUnitValue

Now when I added logging output (similar to what I've used many times before to find bugs), the model's understanding suddenly improved. I removed unrelated logging that was creating noise, and progress accelerated dramatically. The solution began to take shape. Now I’m left with just one oddball test only failing on a few minor points.

Key Technical Improvements

The new implementation follows the CSS Grid Layout Algorithm much more closely, particularly:

Track Sizing Algorithm: Now implemented as a series of phases that match the specification:

proc trackSizingAlgorithm*(
    grid: GridTemplate,
    dir: GridDir, 
    trackSizes: Table[int, ComputedTrackSize],
    availableSpace: UiScalar
) =
  # 1. Initialize Track Sizes
  initializeTrackSizes(grid, dir, trackSizes, availableSpace)
  # 2. Resolve Intrinsic Track Sizes
  resolveIntrinsicTrackSizes(grid, dir, trackSizes, availableSpace)
  # 3. Maximize Tracks
  maximizeTracks(grid, dir, availableSpace)
  # 4. Expand Flexible Tracks
  expandFlexibleTracks(grid, dir, availableSpace)
  # 5. Expand Stretched Auto Tracks
  expandStretchedAutoTracks(grid, dir, availableSpace)
  # Now compute final positions
  computeTrackPositions(grid, dir)

Proper Auto Placement: The implementation now correctly handles auto-flow grid items, respecting the grid's flow direction and density:

# Auto-flow implementation that correctly places items based on direction
if gridTemplate.autoFlow in [grRow, grRowDense]:
  (mx, my) = (dcol, drow)
elif gridTemplate.autoFlow in [grColumn, grColumnDense]:
  (mx, my) = (drow, dcol)

Calculating minimum and maximum function constraints: proper handling of minimum and maximum “functions” where previously I’d tried to calculate them ad-hoc without tracking the minimum or maximum space of each track.

Visual Verification

To validate the implementation, I created test cases like this one that verifies precise grid line positions:

test "compute others":
  var gt: GridTemplate

  parseGridTemplateColumns gt, ["first"] 40'ux \
    ["second", "line2"] 50'ux \
    ["line3"] auto \
    ["col4-start"] 50'ux \
    ["five"] 40'ux ["end"]
  parseGridTemplateRows gt, ["row1-start"] 25'pp \
    ["row1-end"] 100'ux \
    ["third-line"] auto ["last-line"]

  gt.gaps[dcol] = 10.UiScalar
  gt.gaps[drow] = 10.UiScalar
  var computedSizes: array[GridDir, Table[int, ComputedTrackSize]]
  gt.computeTracks(uiBox(0, 0, 1000, 1000), computedSizes)

  # Verify precise grid line positions
  check gt.lines[dcol][0].start.float == 0.0
  check gt.lines[dcol][1].start.float == 50.0
  check gt.lines[dcol][2].start.float == 110.0  # 40 + 10(gap) + 50 + 10(gap)
  check gt.lines[dcol][3].start.float == 900.0  # auto fills remaining space
  check gt.lines[dcol][4].start.float == 960.0
  check gt.lines[dcol][5].start.float == 1000.0

I've even created an HTML visualization to help me understand how these values map to a real grid:

Insights and Takeaways

What I found most fascinating was how the LLM benefited from the same debugging approach I use myself. Without the right debug logs, both the model and I struggled to locate exactly where the code was failing.

The revised implementation is much more standards-compliant and handles complex cases that my original implementation struggled with:

Content-based sizing: Proper handling of min-content, max-content, and fit-content
Nested and spanning items: Correct distribution of space for items that span multiple tracks
Auto placement: Better handling of grid auto-flow direction and dense packing

Like much systems programming, CSS grid layout is deceptively complex beneath its elegant API. Implementing the spec faithfully required understanding subtle interactions between sizing algorithms, content contributions, and space distribution. Honestly I don’t care about that so much. I just want to make apps. ;)

Making Reactive Datatypes in 200 lines of Nim

Jaremy Creechley — Thu, 30 Jan 2025 04:48:24 GMT

`Sigil` becomes more than a name

Sigils now supports first-class reactive data types! I wish I could say it was a grueling undertaking, but it wasn’t. Thanks to the core of Sigil’s being signals and slots along with Nim’s superb meta-programming it was pretty trivial to knock out. The trickiest part has been finding out what behaviors the JavaScript implementations follow.

Coincidently, Svelte’s reactive datatype is called Rune meaning ”a mark or letter of mysterious or magic significance” while Sigil means “an inscribed or painted symbol considered to have magical power“. Almost like this is what the Sigils library was meant to become.

I’m excited since this neatly solves a longstanding wart in Figuro UIs for how to provide a nice clean and simple API for handling reactive data. Signals and slots are powerful but a bit verbose and my initial APIs left me feeling underwhelmed. Reactive datatypes are much nicer:

    let x = newSigil(5)
    let y = newSigil(false)
    let z = computed[int]():
      if y{}: x{} * 2 else: 0

    check x{} == 5
    check y{} == false
    check z{} == 0
    y <- true #(* update the calue in y *)
    check y{} == true
    check z{} == 10

Previously in Figuro I was trying to do something similar but it just wasn’t it:

type Main* = ref object of Figuro
       counter = Property[int]()

proc draw*(self: Main) {.slot.} =
   withWidget(self):
      rectangle "count":
        text "btnText":
          bindProp(self.counter)
          node.setText({font: $(self.counter.value) & " ₿" }, Center, Middle)    
      Button.new "btnAdd":
        text "btnText":
          node.setText({largeFont: "–"}, Center, Middle)
        ## something like this:
        self.counter.onSignal(doClicked) do(counter: Property[int]):
          counter.update(counter.value-1)

This can now become more streamlined and provide a semantics familiar to webdevs (note I haven’t wired this bit into Figuro at publication time):

type Main* = ref object of Figuro
       counter = newSigil[int](0)

proc draw*(self: Main) {.slot.} =
   withWidget(self):
      rectangle "count":
        text "btnText":
          node.setText({font: $(self.counter{}) & " ₿" }, Center, Middle)    
      Button.new "btnAdd":
        text "btnText":
          node.setText({largeFont: "–"}, Center, Middle)
        node.onSignal(doClicked):
          self.counter <- self.counter{} - 1

`Sigil[T]` Villain’s Origin Story

The other day I posted on Nim-lang’s #appdev Discord channel about adding some animation support to Figuro. Using the new signals and slots from my new Sigils made creating a new more powerful Fader primitive super easy.

The Fader Agent (Sigil’s core object) fades in or out on a linear scale and can be interrupted midway and start going the other direction. In a couple dozen lines it seamlessly computes the next step based on Figuro’s doTick core signal when it begins fading and disconnects itself when it’s finished. Fader provides a core primitive needed for many key UI operations include fading a button on hover or sliding a menu in or out.

Phil, a fellow participant in #appdev (aka IsoFruit), asked about reactive datatypes. Phil does a lot of webdev and apparently *signals* have taken over the JavaScript UI world. Given that I had just made Fader which is a very reactive objects, I was curious what he meant and we started discussing it. He mentioned reactive data types were becoming standard in JavaScript with them being called Observables in RxJs, Signals in Angular, and Runes in Svelte.

After some back and forth it turned out he was referring to Reactive Programming. It’s an interesting field and I wasn’t sure how it’d fit into a static language like Nim. I’d experimented with it briefly way back in 2014 (almost a decade now :wow:) to run a PID loop on a Raspberry Pi. That experiment didn’t turn out well and was one of my first forays into latency sensitive programming and dealing with the pain of GC.

Nowadays Reactive Programming has moved into the mainstream and the method de jour of handling reactive user interfaces. That’s basically all UIs. Here’s a short example given by Phil:

const x = signal(5)
const double = computed(() => x()*2)
x.set(2)
// double is now 4

Well I figured that looks simple. I bet Figuro (really Sigils) could make short work of that. A short 20 minutes later I had a working example! Sorta, well behold:

    type
      Reactive = ref object of Agent
        value: int
    proc setValue(tp: Reactive, val: int) {.signal.}
    let
      x = Reactive(value: 5)
      y = Reactive()

    proc computed(self: Reactive, val: int) {.slot.} =
      self.value = val * 2
    x.connect(setValue, y, computed)

    emit x.setValue(2)
    echo "Y: ", y.value

This was lacking some syntactic sugar, but proved to me that it could be done. The next day I added a couple of template's and got:

  test "reactive wrapper":
    let
      x = reactive(5)
      y = computed(x): # probably need a macro to get rid of the extra x
        2 * x{}

    x <- 2
    echo "X: ", x.value
    echo "Y: ", y.value
    check y.value == 4

Complex C code gave ChatGPT a headache and Claude came to the rescue

Jaremy Creechley — Tue, 14 Jan 2025 23:37:21 GMT

For Figuro I want to have a file monitoring API that watches for the CSS theme to be modified. Unfortunately all the libraries in Nim are either wrappers around C libraries or incomplete.

I tried finding a few C projects and translating them, but it’s a pain because it requires using low level system APIs which also need binding in Nim.

Notes About Translating

I also tried converting the code automatically using c2nim which is very helpful. Unfortunately for this sort of system code you end up with lots of missing details.

For example on MacOS file watching libraries tend to use FSEventStreamContext which I’ve never even heard about before. It requires plumbing some handlers for allocating and deallocating things event structs. Or something as I don’t really care about the details. Others figured that out, I just want to use it.

Most of converting C to Nim (or any programming language to another) is just going through a fairly simple set of mini-algorithms and mappings. For example C enum flags can be converted into Nim’s set[SomeEnum] which is much easier to work with and typesafe. It also casts back to the proper C integer values!

Now programming this knowledge into something like c2nim takes a lot of work. I know this well since I’ve contributed a fair bit to c2nim in the past. It’s fun but becomes pretty tedious since there are dozens if not hundreds of these mini-algorithms and C isn’t very strict almost to the point that it’s really considered a typed language. It’s more kinda-typed, definitely unlike Haskell’s higher kinded types.

Isn’t this what LLMs should be great at however? They really boil down to very complex [Markov chains](https://en.wikipedia.org/wiki/Markov_chain) compiled over the entire internet with some fascinating emergent behavior. It almost seems like they can reason about a problem. Really though it’s more like they learn complex flow diagrams and decision trees from all the hard work us humans have put into everything the past umpteen millennium. That’s also why I think UBI makes sense as automation builds upon the work of generations of minds!

Okay back to the core topic of translating code.

Trying out ChatGPT

Eventually I figured I’d give ChatGPT a go. It started out great! But then it essentially gave up:

# Enums translated to Nim
type
  DmonWatchFlags* = enum
    recursive = 0x1,
    followSymlinks = 0x2,
    outOfScopeLinks = 0x4,
    ignoreDirectories = 0x8

  DmonAction* = enum
    create = 1,
    delete,
    modify,
    move

... more structs

# Utility functions
proc isRange*(ch: char, from: char, to: char): bool =
  result = uint8(ch - from) <= uint8(to - from)

proc isUpperChar*(ch: char): bool =
  result = isRange(ch, 'A', 'Z')

proc toLowerChar*(ch: char): char =
  if isUpperChar(ch):
    result = ch + '\x20'
  else:
    result = ch

proc toLower*(dst: var string, str: string) =
  for c in str:
    dst.add(toLowerChar(c))

# Initialization function
proc dmonInit*() =
  echo "Initializing dmon..."

proc dmonDeinit*() =
  echo "Deinitializing dmon..."

The beginning looks like it’s off to a great start. However both dmonInit and dmonDeinit are filler procs. So I tried prompting ChatGPT for more and it kept doing the same habit of trying to skimp out on doing a full translation.

Also, ChatGPT noticeably began to struggle outputting the code when you included fuller details. It’s unclear if that’s due to throttling by OpenAI or that the model requires more resources.

On to Claude

Next I figured I’d try Claude Sonnet 3.5 from Anthropic. Word on the street is that it’s much better at coding.

It’s first attempts was similar to ChatGPT in that it gave a summary of how to do the conversion. Well great, it wants to put me to work for it. I’m starting to feel like LLMs have great management potential! :P

Okay, but once I prompted Claude to give me the full full translation it obliged! Well at least until:

But a quick follow up prompt got it to finish:

Results

Below is the full output for the MacOS specific conversion for those curious about such things. Does it compile? Nope! But that looks like a great start. I’ve been skimming it and comparing it to the C code and it’s done a good job converting.

I tend to trust LLMs for translating the code since they do better against something that exists and this sort of common system code which has a lot of similar implementation in many languages. It’s not creating de novo code.


import posix
import macros
import os
import strutils
import locks
import tables

# MacOS-specific imports
{.passL: "-framework CoreServices -framework CoreFoundation".}

type
  CFIndex* = clong
  CFTimeInterval* = cdouble
  CFStringRef* = distinct pointer
  CFArrayRef* = distinct pointer
  CFRunLoopRef* = distinct pointer
  CFAllocatorRef* = distinct pointer
  CFRunLoopMode* = distinct pointer
  FSEventStreamRef* = distinct pointer
  FSEventStreamEventId* = culonglong
  FSEventStreamEventFlags* = culong
  dispatch_semaphore_t* = distinct pointer

const
  kCFStringEncodingUTF8* = 0x08000100'i32
  kCFRunLoopDefaultMode* = CFRunLoopMode(CFStringRef("kCFRunLoopDefaultMode"))
  kCFRunLoopRunTimedOut* = 2
  kFSEventStreamEventFlagItemCreated* = 0x00000100'u32
  kFSEventStreamEventFlagItemRemoved* = 0x00000200'u32
  kFSEventStreamEventFlagItemModified* = 0x00001000'u32
  kFSEventStreamEventFlagItemRenamed* = 0x00000800'u32
  kFSEventStreamCreateFlagFileEvents* = 0x00000010'u32

type
  DmonWatchId* = distinct uint32

  DmonWatchFlags* = enum
    Recursive = 0x1
    FollowSymlinks = 0x2 
    OutOfScopeLinks = 0x4
    IgnoreDirectories = 0x8

  DmonAction* = enum
    Create = 1
    Delete
    Modify 
    Move

  DmonWatchCallback* = proc(watchId: DmonWatchId, action: DmonAction, 
                          rootdir, filepath, oldfilepath: string,
                          userData: pointer) {.cdecl.}

  FSEventStreamContext* {.pure, final.} = object
    version*: CFIndex
    info*: pointer
    retain*: pointer
    release*: pointer
    copyDescription*: pointer

  DmonFsEvent = object
    filepath: string
    eventId: FSEventStreamEventId
    eventFlags: FSEventStreamEventFlags
    watchId: DmonWatchId
    skip: bool
    moveValid: bool

  DmonWatchState = ref object
    id: DmonWatchId
    watchFlags: uint32
    fsEvStreamRef: FSEventStreamRef
    watchCb: DmonWatchCallback
    userData: pointer
    rootdir: string
    rootdirUnmod: string
    init: bool

  DmonState = object
    watches: array[64, DmonWatchState]
    freeList: array[64, int]
    events: seq[DmonFsEvent]
    numWatches: int
    modifyWatches: Atomic[int]
    threadHandle: Thread[void]
    threadLock: Lock
    threadSem: dispatch_semaphore_t
    cfLoopRef: CFRunLoopRef
    cfAllocRef: CFAllocatorRef
    quit: bool

# CoreFoundation Functions
proc CFStringCreateWithCString*(alloc: CFAllocatorRef, cStr: cstring, encoding: int32): CFStringRef {.importc.}
proc CFArrayCreate*(alloc: CFAllocatorRef, values: ptr pointer, numValues: CFIndex, callbacks: pointer): CFArrayRef {.importc.}
proc CFRunLoopGetCurrent*(): CFRunLoopRef {.importc.}
proc CFRunLoopRunInMode*(mode: CFRunLoopMode, seconds: CFTimeInterval, returnAfterSourceHandled: bool): cint {.importc.}
proc CFRunLoopStop*(loop: CFRunLoopRef) {.importc.}
proc CFRelease*(cf: pointer) {.importc.}

# FSEvents Functions
proc FSEventStreamCreate*(
  allocator: CFAllocatorRef, 
  callback: proc (
    streamRef: FSEventStreamRef,
    clientCallBackInfo: pointer,
    numEvents: csize_t,
    eventPaths: pointer,
    eventFlags: ptr FSEventStreamEventFlags,
    eventIds: ptr FSEventStreamEventId
  ) {.cdecl.},
  context: ptr FSEventStreamContext,
  pathsToWatch: CFArrayRef,
  sinceWhen: FSEventStreamEventId,
  latency: CFTimeInterval,
  flags: FSEventStreamEventFlags
): FSEventStreamRef {.importc.}

proc FSEventStreamScheduleWithRunLoop*(
  streamRef: FSEventStreamRef,
  runLoop: CFRunLoopRef,
  runLoopMode: CFRunLoopMode
) {.importc.}

proc FSEventStreamStart*(streamRef: FSEventStreamRef): bool {.importc.}
proc FSEventStreamStop*(streamRef: FSEventStreamRef) {.importc.}
proc FSEventStreamInvalidate*(streamRef: FSEventStreamRef) {.importc.}
proc FSEventStreamRelease*(streamRef: FSEventStreamRef) {.importc.}

# Grand Central Dispatch Functions
proc dispatch_semaphore_create*(value: clong): dispatch_semaphore_t {.importc.}
proc dispatch_semaphore_signal*(sem: dispatch_semaphore_t): clong {.importc.}
proc dispatch_semaphore_wait*(sem: dispatch_semaphore_t, timeout: uint64): clong {.importc.}
proc dispatch_release*(obj: pointer) {.importc.}

const DISPATCH_TIME_FOREVER* = not 0'u64

var
  dmonInitialized: bool
  dmon: DmonState

proc fsEventCallback(
  streamRef: FSEventStreamRef,
  userData: pointer,
  numEvents: csize_t,
  eventPaths: pointer,
  eventFlags: ptr FSEventStreamEventFlags,
  eventIds: ptr FSEventStreamEventId) {.cdecl.} =

  let watchId = cast[DmonWatchId](userData)
  assert(uint32(watchId) > 0)

  let watch = dmon.watches[uint32(watchId) - 1]
  let paths = cast[ptr UncheckedArray[cstring]](eventPaths)

  for i in 0..DmonFsEvent()
    let path = $paths[i]

    # Convert path to unix style and make relative to watch root
    var absPath = unixPath(path)
    let watchRoot = watch.rootdir.toLowerAscii

    if not absPath.startsWith(watchRoot):
      continue

    ev.filepath = absPath[watchRoot.len..^1]
    ev.eventFlags = eventFlags[i]
    ev.eventId = eventIds[i]
    ev.watchId = watchId

    dmon.events.add(ev)

proc processEvents() =
  for i in 0..if ev.skip:
      continue

    # Coalesce multiple modify events
    if (ev.eventFlags and kFSEventStreamEventFlagItemModified) != 0:
      for j in (i+1)..let checkEv = addr dmon.events[j]
        if (checkEv.eventFlags and kFSEventStreamEventFlagItemModified) != 0 and
           checkEv.filepath == ev.filepath:
          ev.skip = true
          break

    # Handle renames
    elif (ev.eventFlags and kFSEventStreamEventFlagItemRenamed) != 0 and
         not ev.moveValid:
      for j in (i+1)..let checkEv = addr dmon.events[j]
        if (checkEv.eventFlags and kFSEventStreamEventFlagItemRenamed) != 0 and
           checkEv.eventId == ev.eventId + 1:
          ev.moveValid = true
          checkEv.moveValid = true
          break

      # If no matching rename found, treat as create/delete
      if not ev.moveValid:
        ev.eventFlags = ev.eventFlags and not kFSEventStreamEventFlagItemRenamed
        let absPath = watch.rootdir / ev.filepath

        if not fileExists(absPath):
          ev.eventFlags = ev.eventFlags or kFSEventStreamEventFlagItemRemoved
        else:
          ev.eventFlags = ev.eventFlags or kFSEventStreamEventFlagItemCreated

  # Process final events
  for i in 0..let ev = addr dmon.events[i]
    if ev.skip:
      continue

    let watch = dmon.watches[uint32(ev.watchId) - 1]
    if watch == nil or watch.watchCb == nil:
      continue

    if (ev.eventFlags and kFSEventStreamEventFlagItemCreated) != 0:
      watch.watchCb(ev.watchId, Create, watch.rootdirUnmod, ev.filepath, nil, watch.userData)

    if (ev.eventFlags and kFSEventStreamEventFlagItemModified) != 0:
      watch.watchCb(ev.watchId, Modify, watch.rootdirUnmod, ev.filepath, nil, watch.userData)

    elif (ev.eventFlags and kFSEventStreamEventFlagItemRenamed) != 0:
      for j in (i+1)..let checkEv = addr dmon.events[j]
        if (checkEv.eventFlags and kFSEventStreamEventFlagItemRenamed) != 0:
          watch.watchCb(checkEv.watchId, Move, watch.rootdirUnmod,
                       checkEv.filepath, ev.filepath, watch.userData)
          break

    elif (ev.eventFlags and kFSEventStreamEventFlagItemRemoved) != 0:
      watch.watchCb(ev.watchId, Delete, watch.rootdirUnmod, ev.filepath, nil, watch.userData)

  dmon.events.setLen(0)

proc monitorThread() {.thread.} =
  dmon.cfLoopRef = CFRunLoopGetCurrent()
  dispatch_semaphore_signal(dmon.threadSem)

  while not dmon.quit:
    if dmon.modifyWatches.load() != 0 or not tryLock(dmon.threadLock):
      sleep(10)
      continue

    if dmon.numWatches == 0:
      sleep(10)
      unlock(dmon.threadLock)
      continue

    for i in 0..let watch = dmon.watches[i]
      if not watch.init:
        assert(not watch.fsEvStreamRef.isNil)
        FSEventStreamScheduleWithRunLoop(watch.fsEvStreamRef, dmon.cfLoopRef, kCFRunLoopDefaultMode)
        discard FSEventStreamStart(watch.fsEvStreamRef)
        watch.init = true

    discard CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.5, false)
    processEvents()

    unlock(dmon.threadLock)

  CFRunLoopStop(dmon.cfLoopRef)
  dmon.cfLoopRef = nil

proc unwatchState(watch: DmonWatchState) =
  if not watch.fsEvStreamRef.isNil:
    FSEventStreamStop(watch.fsEvStreamRef)
    FSEventStreamInvalidate(watch.fsEvStreamRef)
    FSEventStreamRelease(watch.fsEvStreamRef)
    watch.fsEvStreamRef = nil

proc initDmon*() =
  assert(not dmonInitialized)

  initLock(dmon.threadLock)
  dmon.threadSem = dispatch_semaphore_create(0)
  assert(not dmon.threadSem.isNil)

  createThread(dmon.threadHandle, monitorThread)

  discard dispatch_semaphore_wait(dmon.threadSem, DISPATCH_TIME_FOREVER)

  for i in 0..<64:
    dmon.freeList[i] = 64 - i - 1

  dmonInitialized = true

proc deinitDmon*() =
  assert(dmonInitialized)

  dmon.quit = true
  joinThread(dmon.threadHandle)

  dispatch_release(dmon.threadSem)
  deinitLock(dmon.threadLock)

  for i in 0..if dmon.watches[i] != nil:
      unwatchState(dmon.watches[i])

  dmon = DmonState()
  dmonInitialized = false

proc watchDmon*(rootdir: string, watchCb: DmonWatchCallback,
                flags: uint32, userData: pointer): DmonWatchId =
  assert(dmonInitialized)
  assert(not rootdir.isEmptyOrWhitespace)
  assert(watchCb != nil)

  dmon.modifyWatches.store(1)
  withLock dmon.threadLock:
    assert(dmon.numWatches < 64)
    if dmon.numWatches >= 64:
      echo "Exceeding maximum number of watches"
      return DmonWatchId(0)

    let numFreeList = 64 - dmon.numWatches
    let index = dmon.freeList[numFreeList - 1]
    let id = uint32(index + 1)

    if dmon.watches[index] == nil:
      dmon.watches[index] = DmonWatchState()

    inc dmon.numWatches

    let watch = dmon.watches[id - 1]
    watch.id = DmonWatchId(id)
    watch.watchFlags = flags
    watch.watchCb = watchCb
    watch.userData = userData

    # Validate directory
    if not dirExists(rootdir):
      echo "Could not open/read directory: ", rootdir
      dec dmon.numWatches
      return DmonWatchId(0)

    # Handle symlinks
    var finalPath = rootdir
    if (flags and uint32(DmonWatchFlags.FollowSymlinks)) != 0:
      try:
        finalPath = expandSymlink(rootdir)
      except OSError:
        echo "Failed to resolve symlink: ", rootdir
        dec dmon.numWatches
        return DmonWatchId(0)

    # Setup watch path
    watch.rootdir = finalPath.normalizedPath
    if not watch.rootdir.endsWith("/"): 
      watch.rootdir.add "/"

    watch.rootdirUnmod = watch.rootdir
    watch.rootdir = watch.rootdir.toLowerAscii

    # Create FSEvents stream
    let cfPath = CFStringCreateWithCString(nil, watch.rootdirUnmod.cstring, kCFStringEncodingUTF8)
    defer: CFRelease(cfPath)

    let cfPaths = CFArrayCreate(nil, cast[ptr pointer](unsafeAddr cfPath), 1, nil)
    defer: CFRelease(cfPaths)

    var ctx = FSEventStreamContext(
      version: 0,
      info: cast[pointer](id),
      retain: nil,
      release: nil,
      copyDescription: nil
    )

    let streamFlags = FSEventStreamEventFlags(kFSEventStreamCreateFlagFileEvents)

    watch.fsEvStreamRef = FSEventStreamCreate(
      nil,                              # Use default allocator
      fsEventCallback,                  # Callback function
      addr ctx,                         # Context with watch ID
      cfPaths,                         # Array of paths to watch
      FSEventStreamEventId(0),         # Start from now
      0.25,                           # Latency in seconds
      streamFlags                     # File-level events
    )

    if watch.fsEvStreamRef.isNil:
      echo "Failed to create FSEvents stream"
      dec dmon.numWatches
      return DmonWatchId(0)

    dmon.modifyWatches.store(0)
    result = DmonWatchId(id)

proc unwatchDmon*(id: DmonWatchId) =
  assert(dmonInitialized)
  assert(uint32(id) > 0)

  let index = int(uint32(id) - 1)
  assert(index < 64)
  assert(dmon.watches[index] != nil)
  assert(dmon.numWatches > 0)

  if dmon.watches[index] != nil:
    dmon.modifyWatches.store(1)
    withLock dmon.threadLock:
      unwatchState(dmon.watches[index])
      dmon.watches[index] = nil

      dec dmon.numWatches
      let numFreeList = 64 - dmon.numWatches
      dmon.freeList[numFreeList - 1] = index

    dmon.modifyWatches.store(0)

Unlocking the Power of CSS: Transforming Figuro with Seamless Theming

Jaremy Creechley — Tue, 14 Jan 2025 03:58:33 GMT

The Problem of Theming

After a couple of years of working on Figuro, a framework for building custom GUI apps with small self-contained binaries, I finally decided it was time to add theming to it. There’s something pleasing about being able to theme a GUI application while it’s running. It’s one of the great secrets behind HTML’s success. It also solves one of the bigger pain points in Figuro which was making it easier to develop both customizable and re-usable widgets.

Still it wasn’t clear how best to add theming. Would it be best to make a custom theming file format using Figuro’s properties and syntax? Or to build on something else? Perhaps it’d be possible to create a Nim based DSL for theming. These thoughts and questions lingered for a few months as I let my thoughts simmer on the topic.

Eventually I decided that creating a custom theming DSL would also require defining the semantics for the DSL as well. It’s hard enough developing the core of a GUI system, but creating a useful theming language on top would be even more work. Also building on Nim’s VM to borrow Figuro’s syntax for a DSL is great for development but would require embedding the Nim compiler as well which is less appealing – despite the compilers compact size.

Styling Widgets from the Outside

Let’s go back and check out some of the issues with making style-able widgets. Take this snippet of Figuro’s Button widget to see some of the limitations with styling widgets:

type
  Button*[T] = ref object of StatefulFiguro[T]
    label*: string
    disabled*: bool
    clickMode*: set[ButtonClicks] = {Single}

... 

proc draw*[T](self: Button[T]) {.slot.} =
  ## button widget!
  with self:
    clipContent true
  withOptional self:
    cornerRadius 10.0'ui

  if self.disabled:
    withOptional self:
      fill css"#F0F0F0"
  else:
    withOptional self:
      fill css"#2B9FEA"
    self.onHover:
      withOptional self:
        fill self, self.fill.lighten(0.14)
        # this changes the color on hover!

In this code you can see that styling a node is really easy in Figuro. However, making it so a user of the widget can style the Button required adding constructs such as withOptional self: which only changes the node’s color if the user hasn’t already set that particular field. For example:

          Button[int].new("btn"):
            let btn = node
            with node:
              size 100'ux, 100'ux
              fill css"red"
              connect(doHover, self, btnHover)
              connect(doClick, node, btnClicked)
            Text.new "text":
              with node:
                fill blackColor
                setText({font: $(btn.state)}, Center, Middle)

This requires widgets to be written differently than writing application code. That didn’t sit well with me. For various technical reasons a widget’s draw method (slot) executes after the user’s code. This allows the user to configure size and other important parameters. However, whether the user’s code is run before or after the widget’s you end up with an annoying ordering issue.

Briefly I experimented with pre and post blocks, but this didn’t feel ideal. It moves Figuro away from it’s “enlightened” mixed of both declarative and imperative style syntax. Writing applications requires more knowledge of when and where to properly add things.

          Button[int].new("btn"):
            size 100'ux, 100'ux
            node.connect(doHover, self, btnHover)
            node.connect(doClick, node, btnClicked)
            Text.new "text":
              node.setText({font: $(btn.state)}, Center, Middle)
              ...
          finally:
            node.size 100'ux, 100'ux
            node.fill css"red"

Enter CSS

Figuro takes it’s original design from Fidget and builds upon (and significantly improves) that original design. Fidget had some awesome ideas on code interacting with Figma. Still at it’s heart, Figuro is based on Nodes at its core.

Each node is simple with only a few properties. The API is less complex than the DOM at the heart of HTML. Despite being simpler than DOM nodes, Figuro Nodes still form a DAG of UI nodes each with a common set of properties.

That means Cascading Style Sheets (CSS) makes a good fit for styling UIs written with Figuro. Traditional GUI toolkits diverge significantly from HTML’s node tree as a UI. Of course they can still use CSS it’s just not quite as natural a fit in my view.

Being able to define a CSS rule for the Button widget becomes very simple in CSS:

Button {
  background: rgb(164, 158, 255);
  border-width: 5;
  border-color: #160075;
  border-radius: 10;
  color: rgb(78, 0, 90);
  box-shadow: none;
}

Button:hover {
  background: rgb(158, 223, 255);
  box-shadow: 5px 2px 4px rgba(47, 0, 75, 0.119);
}

Now our buttons go from this:

To this without any code changes:

ElCritch's Musings

Debugging Atlas Installs

Signals and Slots for IoT: Calm, Caffeinated Concurrency with Nim and Sigils

Signals and Slots

Backstory: IoT Project Quagmire

Using Signals and Slots in Nim

Why Signals and Slots Work well in Nim Projects

A Small, Generic Example (Nim + Sigils)

Queued Connections and Loops

Actors, Airlocks, and Alliterations

Threading Model, Made Mild

Production Playbook

Where It Shines (and When to Add More)

Caveats

Closing Notes from an OTP Alum

Run Nim Code Anywhere with Cosmopolitan

Compiling Nim Code with Cosmopolitan

Final Thoughts

CSSGrid Engine Updates (april 2025)

130 Pages of CSS Grid Spec and Claude-3.7

The Challenge

Results

Then Problems

Exploring Different Approaches

The Resolution and Logging

Key Technical Improvements

Visual Verification

Insights and Takeaways

Making Reactive Datatypes in 200 lines of Nim

Sigil becomes more than a name

Sigil[T] Villain’s Origin Story

Complex C code gave ChatGPT a headache and Claude came to the rescue

Notes About Translating

Trying out ChatGPT

On to Claude

Results

Unlocking the Power of CSS: Transforming Figuro with Seamless Theming

The Problem of Theming

Styling Widgets from the Outside

Enter CSS

`Sigil` becomes more than a name

`Sigil[T]` Villain’s Origin Story