trop.in

Pay for Software That Respects You

2026-07-20T12:00:00Z

I consider myself a pretty chill and calm person, I can endure and tolerate quite a lot, but I become furious when a program spits in my face with what I didn't ask for, take me for a dumbass or exploit legacy vulnurabilities of my brain. Annoying notification, algorithmic feeds and recommendations, unasked advices and tutorials, stolen out of my pocket data and attention. If I observe such behaviors from a person, I will politely ask them to fuck off at very least. I wouldn't tolerate it from a human, and I definitely won't let it slide from a program.

The computer (laptop/phone/ereader) is mine. Programs I run on them are my tools. They are here to ultimately serve me, not the enterpreneurs, goverments, corporations or whoever what. There is no room for discussion here, there is no "an alternative good opinion". Keep your hands and noses out of my stuff.

You might reasonably ask: "Andrew, if the program is ethical, respectful and doesn't fuck around with you, how people behind it will get a profit?". That's a good question, and I have some thoughts on it.

First of all, there is a hidden assumption that all things should always grow and bring profits. It's not true, a lot of cool things will become much better if they stay at the certain size and just become sustainable (bring enough money, joy and other resources) for their authors and maintainers and keep serving their users. Moreover, in many cases, things built around profit or endless growth simply exploit the planet's resources and vulnerable people under the hood and never become actually sustainable.

Nevertheless, I don't deny that getting money for creating and maintaining software is important. One can of course go quite far on a pure enthusiasm and joy from a positive feedback, but it won't bring food to the table. And even when you make software living in the forest you still need some funds.

Respectful software is almost always also a Free and Open Source Software. The free as in a freedom of course, but also free as in a free beer. The irony here is that monetizing free programs in ethical way is exceptionally hard. Two primary options are grants and donations. There a few more, but they work only for a particular types of software. Donations can be a quite sustainable source of income for the project. So, don't understimate the impact of a small (preferably recurring) donations. It makes a night-and-day difference for developers.

The bottom line is: we have to normalize paying for a respectful software that we obtain for free. Not because we have to, but because it respects us and we want express the respect and appreciation to its authors and maintainers.

My list

There are a few projects that I rely on daily, they are respectful AF to me, but I hadn't had a chance to express my gratitude with a cold hard cash to some of their creators yet, so today I fixed it. I don't recommend you to follow my list, I just want to give you a bit of inspiration and food for thought.

Operating systems

The fundamental part of any non-trivial electronic devices, the place where computing starts.

GNU Guix (donate) :: my primary and only OS on the laptop is based on guix functional package manager. I spend most of the day with it, I do most of the work with it. No question it's a crucial part of my life. No question the package manager is one of the most important pieces of any computing, the foundation for reliable and trustworthy supply chain. The primary repo contains only FOSS, it's not a guarantee on its own, but together with the work of the community it gives a reasonable amount of confidence and piece of mind. And I didn't even started to talk about all the goodies like declarative OS configuration, transactional updates/rollbacks, lisp all over the places and much more.
GrapheneOS (donate) :: it's my phone's OS based on AOSP. Hardened, minimalistic, zero crapware OOB, good sandboxing, granular capabilities/scopes/permissions to restrict untrusted applications. I don't like phones, I don't like to use them, I hate most of the mobile apps, but graphene makes the experience at least manageable and provides some security and privacy to the crappy mobile phone world.
F-droid (donate, sign) :: my go to Android App Repository. Free and Open Source Mobile Software Distribution Ecosystem. We already talked about supply chain for desktop/server OS, now let's cover a mobile devices counterpart. F-droid is an app itself, the app for obtaining and distributing other apps. It's also an app repository. It's a set of tools for creating own packages and repositories. It's user's freedom and privacy first project. It's hard to underestimate how important program distribution is, right? So, this was an obvious pick.
CrossInk (sponsor) :: a fork of CrossPoint, a simple and efficient OS for esp32-based E-ink readers. I have a luxury and luck to spend more time on my ultralight E-reader rather than on my phone, and I enjoy every minute using it thanks to CrossPoint. KOreader sync, calibre integration, WebUI for uploading books over the air. CrossInk adds some missing features like control remapping, good OOB fonts, reading stats and IMHO improves the UX significantly.
KOreader (support) :: it's not exactly OS, it's more of a reading application, but it works as a graphical shell, file browser, bookmark manager, dictionary and much more. Basically it's only user facing program on my ereader, almost pid 1.

Content and Social Networks

The programs are usually fun and useful, but some (or many of them) can't go far without a content and a way to exchange it (being it audio, video, text or whatever).

Anna's Archive (donate) :: The Biggest Library in the world, the project for preserving human knowledge and culture and making it accessible to everyone. Everytime I need a book or scientific paper, I reach for it. The code and datasets are open source. Books can be fun and entertaining, but books also a foundation of our civilization. If book brought you a joy or was helpful, donate to author of the book and write them a letter of appreciation.
LibreWolf (no donations) :: the browser based on ff, a window to the web. Full-fledged, No BS, freedom and privacy-respecting. Rare, but luckily existing. The project doesn't accept donations, but you can contribute your time to it or just share a word about the project.
Migadu (pay) :: my primary email provider and email is my primary communication tool. While most of the infrastructure is based on FOSS, it's not a FOSS project on its own. This is one of the rare examples of commercial projects making a respectful software. Also, a good example of the project that don't try to grow indefinitely, and operates on its own comfortable scale. "Not so much for profit company". The web interface is clean and on point, the protocols are standard and complaint. No ads, no vendorlock, no attention robbery. People in support are professional, they are technical specialists, who can actually answer the questions or help to troubleshoot a problem. Commercial software, web sites and services can be respectful too, this is a clear example.
Fosstodon (support) :: a short message oriented fediverse (mastodon) instance. Mastodon is similiar to twitter/bluesky, but federated. Interoperable with other fedi services, including peertube, lemmy, pixelfed and much more. There are a few options: to pay to mastodon devs and to people who maintain, operate and moderate a particular instance.
SourceHut (pay) :: No AI, No JS, No BS, No ADS. My primary git hosting at the moment. Not the easiest, not the prettiest, but very capable and do the shit you need from a git hosting. One can contribute and use most of the functionality without even creating an account. It has a kernel-org vibe. It's another example of a managed FOSS service, mid-sized and sustainable. If you look for more github-like alternative with Pull Requests and stuff, take a look at codeberg.org.
Voice (support) :: a simple audiobook player. It doesn't have to be a huge, mission critical application, we can pay for a thing, when it just makes our life a bit easier and nicer. This one will be that one.

Conclusion

I could go further for hours. Video editing with ffmpeg, actually useful feeds with fresshrss, books library management with calibre, etc, etc. It's not the point to list all of the cool stuff here, the point is to share the idea, to give the inspiration, to normalize paying for the good craft and respectful things. Just try it. It will make the day for the author of the program. It will make the day for you.

Context Makes Tests Reusable

2026-06-17T12:00:00Z

Context Makes Tests Reusable

I've been designing and implementing a testing framework for around a year. The API was simple and stable for a long time, but a couple of things were bothering me: setting up and tearing down testing environments is cumbersome, reusing tests is inconvinient.

I found out that a minor adjustment to API can make a huge difference and significantly improve UX, so I share my observations and findings with you.

This is a testing library design note and a list of cool consequences of one design decision that made a whole class of tasks easier.

The first two sections provide necessary context for understanding of the syntax and semantics of code examples. The third section introduces "The Problem". The next sections immediately uncover deceptively simple design decision, and gradually show how it addresses the issues mentioned in the previous section and radically improves the overall situations.

Original Design and Syntax

After dozens of iterations, weeks of research and multiple workarounds of imlicit and explicit constraits I ended up with a quite clean syntax and three primary entities: assertion, test and suite. This is how test definition syntax looks like:

(suite "outer"
 (suite "nested"
  (test "the test" ; test can be re-executed multiple times
   (define val (prepare-value somehow))
   (is (good? val)) ; asserting
   (is (really-good? val))) ; asserting again
  (test "small"
   (is (= 4 (+ 2 2))))))

The way it works is (maybe) not intuitive, but simple: the test macro captures its body, creates a thunk (zero-arguments procedure) out of it and sends this procedure with some extra data to test-runner. This process is called test loading: test runner registers a test (test/body-procedure + test/description + test/metadata) and later can execute and re-execute test/body-procedure whenever it is needed.

The test being a first-class runtime entity is a must-have property for interactive development workflows (REPL-driven or similiar). Moreover, having a test + information from previous runs, we can schedule next executions in a very effective way and integrate the run with other development tooling, e.g. we can schedule the quickest previously failed tests to be executed first, and in case of failure, halt/pause the further execution and immediately bring up a debugger.

A test can exist on its own, but for big projects it's better to keep things organized. The suite entity helps with it, it serves two purposes: grouping related entities and building hierarchies. After outer suite is loaded the test runner's will be aware of the test hierarchy:

📂 outer
└─ 📂 nested
   ├─ 📄 the test
   └─ 📄 small

This is cool on its own, but becomes even cooler, when we add metadata feature into the equation. The concept of metadata is simple, you can add arbitrary data to the test or suite. Like this:

(test "my test"
 'metadata '((tags . (slow integration)))
 (is (good? val)))

This way we can provide more info for the test runner, which can be later used to simplify our lives, e.g. we can mark some tests with slow tag and ask test runner to temporary skip them during [re-]executions. It will keep our feedback loop tighter, but still allow to easily run all the tests once in a while. Of course, it's only one of use cases, I bet you already have a bunch of cool ideas of what we can do with access to test-runner internals and this mechanism, but let's explore metadata for suites first.

Syntax-wise it looks exactly the same, but internally it works a bit different. Test runner loads the whole hierarchy and for each test computes a test/compound-metadata value by merging metadata of all enclosing suites and test itself. So tests basically "inherit" the metadata of their ancestors (suites). This way we can mark the whole suite of tests with a particular tag or provide a fixture for setting up a db connection for all db-related tests at once.

Dynamically Scoped Variables

A small almost offtopic, but important section, explaining parameters (dynamically scoped variables) by a short example. We will need understanding of it in the next section.

(define s-s-v 6)

(define (fn)
  (display s-s-v))

(let ((s-s-v 7))
  ;; let doesn't affect staticallyh/lexically scoped s-s-v captured by fn
  (fn) ; prints 6
  (display s-s-v) ; prints 7
  )

(define d-s-v (make-parameter 6))

(define (fn2)
  (display (d-s-v)))

(parameterize ((d-s-v 7))
  ;; parameterize directly affects the value of dynamically scoped d-s-v
  (fn2) ; prints 7
  (display (d-s-v)) ; prints 7
  )

AFAIK, In modern PLT, lexical scoping is preferred over dynamic for general-purpose languages. Code with lexically scoped variables is easier to reason about and maintain.

Sometimes dynamically scoped variables can be useful, e.g. when you want to add a new parameter to a function, but don't want to propagate extra argument to all the callers. In this case dynamically scoped variables can be a compromise: they are still better than global mutable variables, it less refactoring work then updating all the callers signatures and adding extra argument to them.

Still, they introduce unecessary coupling and make flow control much more cumbersome and opaque, so it's better to avoid them when possible.

The Inconvinience of Original Design

All the prerequisits are discussed and set, time to get back to the testing library. Suites gave us grouping, hierarchies, metadata inheritance and while all that is cool, there is a fundamental issue: only test runner has access to it. Tests have no clue about the surrounding and it's limiting. Let's sketch a hypothetical test suite and dissect it next.

(define db* (make-parameter #f))

(define create-admin-fixture
  (lambda (f)
    (init-db-with-admin-user! (db*) ...)
    (f)))

(define create-user-fixture
  (lambda (f)
    (init-db-with-basic-user! (db*) ...)
    (f)))

(define db-connection-fixture
  ;; In real-world code it's better to use dynamic-wind to make sure
  ;; teardown is executed on exception or other non-local control
  ;; transfer.
  (lambda (f)
    (parameterize ((db* (open-db-connection ...)))
      (f)
      (close-db-connection! (db*)))))

(define-suite (user-tests)
  'metadata
  `((fixtures ,create-user-fixture))

  (test "user is present"
    (is (user-exists? (db*) "user")))

  (test "user id is set"
    (is (number? (user-id (db*) "user"))))

  (test "user is not admin"
    (is (not (member "admins" (get-user-groups (db*) "user")))))

(define-suite (admin-tests)
  'metadata
  `((fixtures ,create-admin-fixture))

  (test "user is present"
    (is (user-exists? (db*) "admin")))

  (test "user id is set"
    (is (number? (user-id (db*) "admin"))))

  (test "user is admin"
    (is (member "admins" (get-user-groups (db*) "admin")))))

(define-suite (multiple-users-tests)
  'metadata
  `((fixtures ,create-admin-fixture ,create-user-fixture))

  ;; TODO: [Andrew Tropin, 2026-06-15] Make tests unaware of database,
  ;; by introducing users to context for db-csv-export-test

  (test "there are two users"
    (define users (get-users (db*)))
    (is (= 2 (length users))))

  (test "admin and user are present"
    (define users (get-users (db*)))
    (define user-names (map user-name users))

    (is (member "admin" user-names))
    (is (member "user" user-names))))


(define-suite (db-tests)
  'metadata
  `((fixtures ,db-connection-fixture))

  (user-tests)
  (admin-tests)
  (multiple-users-tests))

The code is relatively straightforward and due to its size still looks quite elegant, but when we start scaling up the amount of tests in our project, we will see some issue emerging and biting us. Let's focus on two primary that are already visible on this suite.

From library design introduction section we remember that tests are independent executable units, they can be run and re-run in arbitrary order, multiple times. They must work despite the order and number of re-runs. That means, we have to setup a proper clean environment everytime we run a test and that's totally fine and expected.

Simple option could be to repeat setup and teardown in each test manually, but it lead to significant repetitions when the setup is the same for multiple tests, and the extra setup code visually obscures the test's logic.

Luckily, in the example above we do it with fixtures. Fixtures are reusable and composable. The issue here is that test-runner has no direct communication channel with tests. Which means there is no way to explicitly share the execution context with a test.

For the fixtures it means we forced to provide execution environment via dynamically scoped variables. It couples tests, fixtures via db* parameter. It has all the cons of parameters. Excessive coupling is no good too.
Not having access to execution context from inside the test means we can't adjust its behavior and reuse same in multiple different contexts. In real life it often handy, e.g. to test API-compatible implementations with the same test suite or when we want to run same checks, but with sligtly different settings or data sources.

Let's call those issues Excessive Coupling and Context Unawareness. This way it will be easier to reference them and discuss how the solution addresses them.

The Solution

Syntax-wise the solution is exceptionally simple, we just add an argument to the test that can be referenced in its body. We wrap it in parenthesis to make it look clearer. That's it:

;; The old syntax
(test "description"
  (is (ok? (some-external-dependency*)))
  (is (good? value)))

;; becomes =>

(test ("description" ctx)
  (is (ok? (assoc-ref ctx 'value)))
  (is (good? value)))

;; ctx, _, context you name it

In addition to syntax changes, our test's test/body-procedure changes from a zero-argument to single-argument procedure. We also need to update test-runner implementation to properly construct the context and pass it to test/body-procedure, but it's trivial.

Now, we all set, so let's see the effect.

Contextual Awareness

Contextual Awareness provides multiple benifits, but we will start from deduplication. You probably noticied a repetitive pattern in user-tests and admin-tests. The existing checks are almost identical with a minor difference of user name to be checked. The original code was:

(define-suite (user-tests)
  'metadata
  `((fixtures ,create-user-fixture))

  (test "user is present"
    (is (user-exists? (db*) "user")))

  (test "user id is set"
    (is (number? (user-id (db*) "user"))))

  (test "user is not admin"
    (is (not (member "admins" (get-user-groups (db*) "user")))))

(define-suite (admin-tests)
  'metadata
  `((fixtures ,create-admin-fixture))

  (test "user is present"
    (is (user-exists? (db*) "admin")))

  (test "user id is set"
    (is (number? (user-id (db*) "admin"))))

  (test "user is admin"
    (is (member "admins" (get-user-groups (db*) "admin")))))

Let's extract the common part into a separate suite, refactor it to new syntax and generalize it.

(define-suite (user-set-correctly-tests)
  (test ("user is present" ctx)
    (is (user-exists? (db*) (assoc-ref ctx 'sut/user))))

  (test ("user id is set" ctx)
    (is (number? (user-id (db*) (assoc-ref ctx 'sut/user))))))

Instead of hardcoded user name, now we obtain it from ctx. To add the name to the context, we will just modify a metadata for enclosing suites. sut stands for subject under the test.

(define-suite (user-set-correctly-tests)
  (test ("user is present" ctx)
    (is (user-exists? (db*) (assoc-ref ctx 'sut/user))))

  (test ("user id is set" ctx)
    (is (number? (user-id (db*) (assoc-ref ctx 'sut/user))))))

(define-suite (user-tests)
  'metadata
  `((fixtures ,create-user-fixture)
    (sut/user . "user"))

  (user-set-correctly-tests)

  (test ("user is not admin" _)
    (is (not (member "admins" (get-user-groups (db*) "user"))))))

(define-suite (admin-tests)
  'metadata
  `((fixtures ,create-admin-fixture)
    (sut/user . "admin"))

  (user-set-correctly-tests)

  (test ("user is admin" _)
    (is (member "admins" (get-user-groups (db*) "admin")))))

In some scenarios duplication can be completely justified, but for the cases where you do a lot of re-use, something like api-compatible library reimplementation, copy-pasting and monkeypatching tests is a guaranteed way to hell.

Of course, code reuse is not the only benifit of contextual awarness. By having an execution context accessible, test can control its behavior. For example if test sees fast-run? set to #t it can skip expensive computations and related assertions. Or in our user-set-correctly-tests suite we can add an extra assertion that checks for user named "admin" that corresponding permission field in the database is initialized with a correct value. The imagination is the limit now, not a testing library :)

Excessive Uncoupling

Let's explore the situtation with dynamic vars, fixtures and unnecesseray coupling and how much it is improved or worsen, hehe.

Decoupling tests from dynamic vars is easy, we just obtain db or any other part of execution environment from the context:

(test ("db access example" ctx)
  (define db (assoc-ref ctx 'db))
  (is (db-connection? db)))

With this small change, test became self-contained, decoupled from fixture implementation, dynamic vars and whatever else. The dependency is now explicit, test connects directly to the test-runner through context argument.

After this update test-runner needs to contruct a proper execution context and call test/body-procedure with context as an argument. The implementation is trivial, but this will also affect how fixtures work. Instead of relying on some shared dynamically scoped variable and implicit prameterization of it, now they just enrich context with values necessary for other fixtures and tests, and pass it to the next fixtures/test in the stack.

(define (db-connection-fixture f)
  (lambda (ctx)
    (let ((db (open-db-connection ...)))
      ;; Add `(db . ,db) pair to context, so the further fixtures and
      ;; tests have access to db
      (f (acons 'db db ctx))

      (cleanup-db! db)
      (close-db-connection! db))))

(define (create-admin-fixture f)
  (lambda (ctx)
    (init-db-with-admin-user! (assoc-ref ctx 'db))
    (f ctx)))

(define (create-user-fixture f)
  (lambda (ctx)
    (init-db-with-basic-user! (assoc-ref ctx 'db))
    (f ctx)))

You probably already saw this pattern, where a number of composable functions wrap each other in some particular order to build a context and possibly process the return value and enrich it on the way back. Such functions usually called middlewares. This composition is very sensitive to order, but the implementation is deadly trivial.

The Synergetic Power Of Friendship

Cool, context awareness added, excessive coupling removed, but can we do now what was impossible before? I got an example, where the both improvements combines, synergize and provide a quite nice developer experience.

We have multiple-users-tests, but didn't touch it yet. How about making this suite generic enough, so it can be used both for testing db connection and csv backup?

;; The original code
(define-suite (multiple-users-tests)
  'metadata
  `((fixtures ,create-admin-fixture ,create-user-fixture))

  (test "there are two users"
    (define users (get-users (db*)))
    (is (= 2 (length users))))

  (test "admin and user are present"
    (define users (get-users (db*)))
    (define user-names (map user-name users))

    (is (member "admin" user-names))
    (is (member "user" user-names))))

First, we will make tests unaware of the source from which users are comming. They will only know that somebody provides a list of users via context. After rewriting tests to the new syntax and removing dependency on db* we get following:

(define-suite (multiple-users-tests)
  (test ("there are two users" ctx)
    (define users (assoc-ref ctx 'users))
    (is (= 2 (length users))))

  (test ("admin and user are present" ctx)
    (define users (assoc-ref ctx 'users))
    (define user-names (map user-name users))

    (is (member "admin" user-names))
    (is (member "user" user-names))))

After that we return back the db-based functionality. We need an extra fixture, which extracts users from database and put them into the context.

(define (db->users-fixture f)
  (lambda (ctx)
    (chain
     (assoc-ref ctx 'db) ; obtain db connection from context
     (get-users _) ; pass it as an argument to get-users
     (acons 'users _ ctx) ; add a list of users to the context
     (f _) ; call fixture/test further down the stack
     )))

(define-suite (db-multiple-users-tests)
  'metadata
  `((fixtures ,create-admin-fixture ,create-user-fixture ,db->users-fixture))

  (multiple-users-tests))

Refactoring is kinda complete and we can add new functionality: running multiple-users-tests on csv backup source instead of db connection. One more fixture and we ready to go.

(define (csv-backup->users-fixture f)
  (lambda (ctx)
    (chain
     ;; (assoc-ref ctx 'users-csv-file-name)
     "resources/users-table-backup.csv" ; hardcode filename for now
     (get-users-from-csv _) ; obtain list of users from csv
     (acons 'users _ ctx) ; add a list of users to the context
     (f _) ; call fixture/test further down the stack
     )))

(define-suite (csv-backup-tests)
  'metadata
  `((fixtures ,csv-backup->users-fixture))

  (multiple-users-tests))

Simple, neat and concise. Now imagine we are going further and try to implement a full test suite for backup validation. We already have fixtures for connecting to db, and initializing necessary values, so all we need is to add a fixture which serializes a db table to the file and we are ready to go: just take already existing db test, make them independent from data source and run them on both original db suites and backup verification suites.

We won't demonstrate the implementation here, but I hope the idea sparks the joy and curiosity in your head.

Conclusion

With one small change, we were able to achive quite a lot. Let's quickly recap what we've got:

A slightly more verbose syntax :'(
A direct communication channel between test-runner and tests
A subjectively clearer test syntax which reads as a re-runnable entity
Tests are reusable now
Tests are context-aware and smart now! :)

Computation-wise, it didn't add something that was impossible before. The both variants still turing-equivalent, but it's definitely changed the UX/DX quite a lot and I hope to the better.

The new syntax is reflected in the second draft of SRFI-269. The fixtures and test-runner modifications for suitbl testing library are still work-in-progress at the moment of writing.

Support

The work on suitbl testing library and SRFI-269 is proudly funded by NLnet.

If you enjoyed the reading, consider to support me, my work and projects. Any help, being it a coin or a word makes a difference.

Future work

The one thing that still bothers me is that metadata attached to the suite-loader, which means to adjust metadata you have to wrap one suite into another. Seems reasonable, but there is the other option: we could make it possible to call suite-loader with optional metadata argument, which will enchance original metadata, so instead of:

(define-suite (my-suite)
  'metadata
  '((original-metadata . #t))
  (test ...)
  (test ...))

(define-suite (proxy-1-suite)
  'metadata
  '((extra-metadata . 1))
  (my-suite))

(define-suite (proxy-2-suite)
  'metadata
  '((extra-metadata . 2))
  (my-suite))

(define-suite (main-suite)
  (proxy-1-suite)
  (proxy-2-suite)
  (other-important-suite))

we can do something like:

(define-suite (my-suite)
  'metadata
  '((original-metadata . #t))
  (test ...)
  (test ...))

(define-suite (main-suite)
  (my-suite '((extra-metadata . 1)))
  (my-suite '((extra-metadata . 2)))
  (other-important-suite))

Definitely looks more elegant, but it's a very recent design idea, so other implications are not clear yet. Need a bit of time to process and think about it.

BTW, SRFI-269 will be finalized in a couple of weeks, so there is a chance to share feedback, uncovered use cases, propose changes before the spec set in stone.

Appendix

Complete example

All the snippets put together in one place:

(define (db-connection-fixture f)
  (lambda (ctx)
    (let ((db (open-db-connection ...)))
      ;; Add `(db . ,db) pair to context, so the further fixtures and
      ;; tests have access to db
      (f (acons 'db db ctx))

      (cleanup-db! db)
      (close-db-connection! db))))

(define (create-admin-fixture f)
  (lambda (ctx)
    (init-db-with-admin-user! (assoc-ref ctx 'db))
    (f ctx)))

(define (create-user-fixture f)
  (lambda (ctx)
    (init-db-with-basic-user! (assoc-ref ctx 'db))
    (f ctx)))

;;; User tests

(define-suite (user-set-correctly-tests)
  (test ("user is present" ctx)
    (is (user-exists? (assoc-ref ctx 'db) (assoc-ref ctx 'sut/user))))

  (test ("user id is set" ctx)
    (is (number? (user-id (assoc-ref ctx 'db) (assoc-ref ctx 'sut/user))))))

(define-suite (user-tests)
  'metadata
  `((fixtures ,create-user-fixture)
    (sut/user . "user"))

  (user-set-correctly-tests)

  (test ("user is not admin" ctx)
    (is (not (member "admins" (get-user-groups (assoc-ref ctx 'db) "user"))))))

(define-suite (admin-tests)
  'metadata
  `((fixtures ,create-admin-fixture)
    (sut/user . "admin"))

  (user-set-correctly-tests)

  (test ("user is admin" ctx)
    (is (member "admins" (get-user-groups (assoc-ref ctx 'db) "admin")))))

(define-suite (multiple-users-tests)
  (test ("there are two users" ctx)
    (define users (assoc-ref ctx 'users))
    (is (= 2 (length users))))

  (test ("admin and user are present" ctx)
    (define users (assoc-ref ctx 'users))
    (define user-names (map user-name users))

    (is (member "admin" user-names))
    (is (member "user" user-names))))

;;; Database suites

(define (db->users-fixture f)
  (lambda (ctx)
    (chain
     (assoc-ref ctx 'db) ; obtain db connection from context
     (get-users _) ; pass it as an argument to get-users
     (acons 'users _ ctx) ; add a list of users to the context
     (f _) ; call fixture/test further down the stack
     )))

(define-suite (db-multiple-users-tests)
  'metadata
  `((fixtures ,create-admin-fixture ,create-user-fixture ,db->users-fixture))

  (multiple-users-tests))

(define-suite (db-tests)
  'metadata
  `((fixtures ,db-connection-fixture))

  (user-tests)
  (admin-tests)
  (db-multiple-users-tests))

;;; CSV backup suite

(define (csv-backup->users-fixture f)
  (lambda (ctx)
    (chain
     ;; (assoc-ref ctx 'users-csv-file-name)
     "resources/users-table-backup.csv" ; hardcode filename for now
     (get-users-from-csv _) ; obtain list of users from csv
     (acons 'users _ ctx) ; add a list of users to the context
     (f _) ; call fixture/test further down the stack
     )))

(define-suite (csv-backup-tests)
  'metadata
  `((fixtures ,csv-backup->users-fixture))

  (multiple-users-tests))


;;; All tests suite

(define-suite (all-tests)
  (db-tests)
  (csv-backup-tests))

Quick Review of "Nix Flakes and their Guix Equivalents"

2026-06-13T12:00:00Z

There is a recent blog post about Nix Flakes vs Guix: https://coopi.neocities.org/posts/nix-flakes-vs-guix

After briefly skimming it, I realized it definitely not fact checked. After re-reading it again I started to suspect that the text of the post was highly LLM assisted*.

I wanted to ignore it at first, but later I saw Ludovic endorsing it and a few other peers keep sharing the post with me, so I decided to write a review.

Despite the way that post is written (with LLMs or not), it still touches the important topics. And I've spent quite some time working and thinking on them, so here I'm to share my thoughts.

I'll replicate the sections structure and will be writing my notes and quote original text when necessary.

P.S. When I was writing this text, I found my old notes on the related topic: Guix Channels are not Flakes.

P.P.S. I'm sad to see feelings of the author got hurt by my suspections. In fact, I didn't even care much if their post was hand-crafted or not:

> Despite the way that post is written (with LLMs or not)

And definitely didn't care enough about a potential human on the other end of the cable. I appreciate style, art and craft, but it was compeletely out of my focus at the moment of writing (my eyes still can barely focus on close up objects yet, heh).

It's very likely I can understand the feelings and moreover can probably relate. I had a similiar expreience with my very own writing about times of my life in the forest. Somebody shared it on hn and in a few hours it was accused of being AI-generated and drug induced and then flagged. I know how unpleasant and upsetting it can be. I also know how discouraging it is to get a paper review with devaluing comment in the first sentence.

I'm always unhappy, when my actions unfairly hurt people's feelings and discourage them. I'm always happy to be wrong about my pessimistic assumptions.

Stay strong and happy my friends.

Table of Content

There is a TOC of a blog post under review:

> 1. Who is this for?
> 2. What even is a flake, anyway?
> 3. Declaring dependencies: inputs vs. channels
>
>     3.1. Flakes: inputs
>     3.2. Guix: channels
>     3.3. The comparison
>
> 4. Pinning dependencies: flake.lock vs. guix describe
>
>     4.1. Flakes: flake.lock
>     4.2. Guix: guix describe and guix time-machine
>     4.3. The comparison
>
> 5. Purity: enforced isolation
>
>     5.1. Flakes: pure evaluation mode
>     5.2. Guix: purity by design
>     5.3. The comparison
>
> 6. The output schema: what your project produces
>
>     6.1. Flakes: structured outputs
>     6.2. Guix: first-class records and modules
>     6.3. The comparison
>
> 7. Development environments: devShells vs. manifests
>
>     7.1. Flakes: devShells
>     7.2. Guix: guix shell and manifests
>     7.3. The comparison
>
> 8. System configuration: nixosConfigurations vs. operating-system
>
>     8.1. Flakes: nixosConfigurations
>     8.2. Guix: operating-system
>     8.3. The comparison
>
> 9. So what does Guix NOT have?
>
>     9.1. A standard project entry point
>     9.2. A registry and quick-install syntax
>     9.3. nix flake show
>
> 10. And what does Guix have that flakes don't?
>
>     10.1. guix time-machine
>     10.2. Grafting
>     10.3. First-class package records
>     10.4. Full-source bootstrapping
>     10.5. Channel authentication
>
> 11. Summary table
> 12. So… who wins?
> 13. Yes I actually cited my sources :3

"2. What even is a flake, anyway?"

This is the longest note, feel free to skip if you familiar with overall nix and flakes history.

There was an original Nix with it not-a-perfect bunch of CLI tools: nix-channel, nix-shell, nix-build, nixos-rebuild, etc, etc.

They did the job, but were far from perfect. For example they used NIX_PATH for finding files with nix expressions. Nix lang itself allows to access environment variables and local fs (which is obviously bad for reproducibility, as well for maintainability and other properties of the code). AFAIR, CLI tools themselves were not very consistent.

Even on top of those tools people started to make their projects. To make those projects reproducible (so other person can clone and run/build it) they needed some way to pin the dependencies (as you can't be sure that nix channels in your system are exactly the same as of yours colleague). And number of tools appeared: from simple fetchTarball of the exact nixpkgs revision, to more advanced nix-pin, niv, npins and probably a dozen more of alternatives and ad-hoc solutions.

Each of them had it own downsides, and most of them were incompatible and noninteroperable with each other and often not even composable with themselves.

So, what is Nix flakes? Nix flakes is an attempt to provide a standardized format for writing nix expressions, with explicit inputs and outputs. + a set of tools for managing/pinning all of that.

Nix flakes can be composed (reference another flake and reuse it outputs and/or override their inputs). They can be hermetically evaluated (in pure enironment, without accessing env vars, local fs, etc). Pay attention that nix evaluation and package build is two different phases: packages themselves are already built in isolated environment by build daemon, but to get "build recipes" you need to evaluate a nix expression and its better to be hermetic as well.

To sum up flakes supposed to provide:

Unified Project/Repo/Nix expression Structure
Explorability
Composability
Dependency resolution, overriding and pinning
Hermetic evaluation
Convenience

> Now here's the key insight: Guix already had solutions for most of
> these before flakes were introduced in Nix 2.4 on November 1, 2021
> (Project, 2021). The channels mechanism landed in Guix around
> 2018–2019 (Contributors, 2025a). And the solutions are orthogonal —
> you can use each one independently, without buying into a single
> monolithic abstraction.

Almost none of the items above are covered by Guix yet. And some of them are technically impossible without fundamental architecture changes. Let's go through other sections and explore each point in more details.

"3 Declaring dependencies: inputs vs. channels"

> Running guix pull fetches all channels, compiles them, and makes
> their modules available to every guix command. This is your
> dependency resolution step.
>
> Channels can declare dependencies on other channels using a
> .guix-channel file in the repo root (Contributors, 2025b):
>
> ;; .guix-channel — lives at the root of a channel repository.  This tells Guix
> ;; that this channel depends on another channel called 'nonguix', so guix pull
> ;; will fetch both together.
> (channel
>   (version 0)
>   (dependencies
>     (channel
>       (name 'nonguix)
>       (url "https://gitlab.com/nonguix/nonguix"))))
>
> This is roughly analogous to inputs in a flake — one channel can
> pull in another. When you guix pull, all transitive channel
> dependencies are fetched together.

There is a huge difference in dependency resolution algorithm.

Imagine in your flake you have flakes A and B as inputs. A depends on flake C@rev1, B depends on flake C@rev2. (Revisions are always pinned, when flake.lock is present).

You will have 4 items resolved A@some-rev1, B@some-other-rev, C@rev1 and C@rev2. The nix expressions from flake A will use code from C@rev1 and B from C@rev2.

If you want to override inputs for flake A, to use the same version of C as in flake B, you can do it. If you want build A against C@rev3 you can do it as well. Just specify input override for the inputs.A.

Now to the Guix channels. Imagine similiar situation. Channel A depends on channel C@rev1, channel B on C@rev2 and your channel depends on both A and B.

During the resolution you will end up with only 3 channels (A@latest-revA, B@latest-revB, and C@rev1). And B will be built against C@rev1 and very likely will fail in general case.

If for some reason A specified C as a dependency, but did not specified the revision, you will end up with (A@latest-revA, B@latest-revB, and C@rev2).

There is a reason for it. As channels use guile modules, you will get name clash if you have two revisions of the same channel. In fact you can get module clashes anyway (same module name comming from different channels) and then the first loaded will win (you will never know which one, haha).

P.S. There are inferiors to be able to have multiple revisions of the same channel, but they are hacky, unreliable and not used in practice.

To sum up:

(minor) You can git unpinned transitive dependency and it will be your work to pin and manage them.
In guix you can't have channels with the same name, but different revisions. So you forced to build all the channels against one version of the dependency. Very ironic for a functional package manager.

>  Both systems let you declare external dependencies and pull them in
>  automatically. The main differences:
>
>     - Flakes are per-project — each repo has its own flake.nix with
>       its own inputs. Channels are system-wide or per-user — your
>       channels.scm applies to all guix invocations. This means flakes
>       naturally support different projects with different dependency
>       sets, while with Guix, you'd typically use guix time-machine or
>       separate profiles to achieve the same effect.
>
>     - Flakes use a URL-like syntax for references
>       (github:NixOS/nixpkgs, git+https://...) while channels use
>       plain Git URLs. The flake syntax is more ergonomic for quick
>       references, but channels are simpler and more explicit.
>
>     - Flakes support non-flake inputs (flake = false;) for repos
>       that don't contain a flake.nix. In Guix, a channel is just a
>       Git repo with Scheme files — there's no special opt-in
>       required. Any repo with Guile modules can be a channel.
>

There is no need to compare guix pull and flakes. nix-channel is what the closest to guix pull in this context. They are quite similiar. There is no per-user/per-project distinction. Both guix pull and nix-channel are "per-user" tools.

If we talk about ad-hoc guix time-machine + channels-lock.scm + .guix-channel. Then it's far from flakes, it's somewhere one step behind "nix-pin and friends times". One step behind because their is no widespread guix-pin tools yet, everyone is doing what they think is better. And if it careful enough it usually quite monstrous: 2024-02-10 Reproducible Dev Environment Workflow with Guix.

"4. Pinning dependencies: flake.lock vs. guix describe"

I don't want to nit-pick the whole section. So I'll go straight to important points and will ignore the rest.

> This is your lock file, essentially. It lives in
> ~/.config/guix/current (as a Guile profile), not as a file in your
> project directory.

It's a profile's provenance. Lock file should be created and available straight after dependency resolution, not after everything is already built. I would prefer to see a lock file immediately to know what I will be working with, not 3 hours after, when everything is already built.

> The guix time-machine command is genuinely unique and has no direct
> flake equivalent. It lets you travel to any point in Guix's history
> — not just to pinned dependency versions, but to a completely
> different state of the package collection (Contributors,
> 2025d). This is incredibly powerful for reproducibility. Like, you
> can run code from three years ago and it JUST WORKS?? That's wild!!

There is an equivalent of guix time-machine -C channel-lock.scm -- build ...

nix build --reference-lock-file alternative-flake.lock ...

If for some reason one need an exact version of nix cli, they can achieve it with the example above and run nix whatever .

> flake.lock is per-project and automatic. guix describe is per-user
> and automatic, while channels.scm with pinned commits is per-project
> but manual.

Yeah, there is no good alternative to flake-like mechanism in Guix and significantly affect UX/DX. And to mimic a fraction of flakes you need to write a hundred lines of code: 2024-02-10 Reproducible Dev Environment Workflow with Guix.

"5. Purity: enforced isolation"

> Guix doesn't need a "pure evaluation mode" because its evaluation is
> already pure by convention (LWN.net, 2024).

It's not clear what this link references to, there is no mention of pure evaluation mode and it's not clear what "pure by convention" means. I didn't find any related text or comments on LWN.

> Guile modules don't have access to environment variables unless you
> explicitly pass them in. There's no equivalent of $NIX_PATH — Guix
> resolves packages through its module system, not through a search
> path. builtins.currentSystem doesn't exist because there's no
> equivalent concept; you specify systems explicitly via package
> metadata and the --system flag.
>
> Guix achieves purity through architecture — Scheme modules are
> inherently more contained than Nix's channel/path system. Flakes
> achieve it through enforcement — a restricted evaluation mode
> layered on top of an otherwise impure system. Both get you to the
> same place. Guix's approach is arguably more elegant because it
> doesn't need to layer restrictions on top of something that was
> originally designed without them. (Though honestly, the fact that
> Nix managed to retrofit purity at all is kind of impressive — it's
> just a different philosophy of getting there.)

Guix uses GUILE_LOAD_PATH for module resolution and loading.
Guix CLI also respects GUIX_PACKAGE_PATH.
Guile code has access to env variables, local fs, and all kind of side effects one can imagine. One can easly do (getenv "PHASE_OF_THE_MOON") from inside a package or operating-system definition.

All the claims about evaluation purity in this context are factually incorrect.

"6-8"

I skip those sections as less significant or because the points were already covered earlier. Many of the statements seems not fact-checked, but still they are too minor to spend time on them.

"9. So what does Guix NOT have?"

> 9.1. A standard project entry point
>
> Flakes have flake.nix — one file that declares dependencies, defines
> outputs, and provides a discoverable schema. There's nothing stopping
> you from finding flake.nix and understanding the project's structure
> at a glance.
>
> Guix projects are more convention-based. You might find manifest.scm,
> channels.scm, guix.scm, package.scm, or something else
> entirely. There's been some movement toward standardizing guix.scm as
> a project file that guix shell picks up automatically (Contributors,
> 2025h), but it's not as established as flake.nix.

Overall, it's true, but at this point I hope you already understand how far guix.scm from flake.nix is.

> 9.2. A registry and quick-install syntax
>
> nix build github:NixOS/nixpkgs#firefox
>
> Guix uses package specifications for similar ergonomics:
>
> guix shell hello
> guix install firefox
>
> But there's no equivalent of the registry for pointing at arbitrary
> Git repos by short name. You just use the URL. Honestly I think this
> is fine — the registry has been a source of confusion in the Nix
> world, since it's not always clear whether nixpkgs refers to the
> registry entry, a local path, or something else.

Recently guix introduced url for channels specification, so it's possible to do something like this:

guix time-machine -C https://my.org/prj/channel.scm -- shell my-package

guix time-machine -C 'swh:1:cnt:<content-hash-of-channels.scm>' -- shell my-package

There is are no registry for associating urls with short names in Guix, but I don't think it's any significant.

> 9.3. nix flake show
>
> The nix flake show command is genuinely nice — it gives you a tree
> view of everything a flake provides (Contributors, 2026). Guix has
> guix search for packages and guix system search for services, but
> there's no equivalent of "show me everything this project/repo
> provides." You just look at the Scheme files.

No flakes - no flake show, heh. There is no standardization, there is no expectations you can make. Composing, reusing? Nah.

10. And what does Guix have that flakes don't?

> I mentioned this earlier, but it deserves emphasis. The ability to
> say "run this command as if it were any arbitrary date in Guix's
> history" is incredibly powerful for reproducibility (Contributors,
> 2025d). Flakes can pin dependencies, but you can't easily say "run
> this with the version of nixpkgs from six months ago" without
> manually finding and specifying the commit. With Guix, guix
> time-machine --commit=... -- does exactly this. I love this feature
> SO MUCH!!

Already mentioned before, it's trivially achieveable on nix. With flakes and without.

> 10.2. Grafting
>
> Guix has a feature called grafting that lets it apply security
> updates to the dependency tree without rebuilding every dependent
> package (Contributors, 2025j). When a low-level library like glibc
> has a vulnerability, Guix can swap in the fixed version by rewriting
> store paths. Nix rebuilds everything. For a large dependency tree,
> the difference can be hours of build time. This is a HUGE advantage.

This is completely unrelated to flakes, it's about nix in general.

The lack of grafting in nix is true.

> 10.3. First-class package records
>
> In Nix, packages are functions — you call stdenv.mkDerivation {
> ... } and it returns a derivation, which is an opaque attribute
> set. In Guix, packages are <package> records — transparent data
> structures with named fields that you can inspect, transform, and
> compose with standard Scheme procedures (Contributors, 2025f).
>
> This means you can do things like:
>
> ;; package-input-rewriting walks the entire dependency graph and replaces every
> ;; occurrence of 'perl' with 'perl-minimal'.  Try doing that in one line with
> ;; Nix!!
> (package-input-rewriting `((,perl . ,perl-minimal)))
>
> ;; The 'inherit' keyword works like inheriting from a parent class — you get all
> ;; the fields of 'coreutils' but override just the ones you specify.
> (package
>   (inherit coreutils)
>   (arguments
>    (substitute-keyword-arguments (package-arguments coreutils)
>      ((#:tests? _ #f) #f))))
>
> Graph rewriting is trivial in Guix because packages are data, not
> functions ((rekado), 2019). Nix has overlays for a similar purpose,
> but they're less ergonomic because the opaque function interface
> makes inspection and transformation harder.
>

In Nix packages are values, and can be expected the same way as Scheme values. Package definition files are functions, which accept an attrset of everything (tools, pcakages, APIs), extract all necessary dependencies, construct and return a attrset value representing a derivation.

The cool thing here, Nix is lazily-evaluated and one can provide a different set of tools/packages to the same package definition to get a new package. That means if I update one package, all the dependent packages will be updated during evaluation.

There is a mechanism called overlays. Basically, it's just a function, which accepts takes argument a self-reference to new attrset and an old attrset. After that you express transformation as a simple function operating on recursive data structure.

Requires a bit of understanding to use it, but it is:

convenient
powerful
first-class supported

In terms of simple vs easy. It's simple.

In Guix, you rewriting a graph is easy, you can get a transformer function, which will go and update all the affected packages. It's not lazy-evaluated, so it will update all the things right now, even if you will never use them.

The worst part, is that you need to get a set of packages to apply the input-rewrite transformer and when you define operating-system or home-environment you will have hard time injecting this rewrite into the right place. If you are not guix developer, it's almost impossible to do. Most likely, you will end up just duplicating part of the dependency graph and having multiple version of the same libs or will just get a conflicting version of the same binary in the profile and build failure.

Dependency rewriting in Guix is easy, but not simple.

In both nix and guix packages are first-class citizens, but package rewrite are first-class only in Nix. :'(

> 10.4. Full-source bootstrapping
>
> Guix is obsessive about bootstrapping from source (Contributors,
> 2025k). The entire system can be built from a tiny trusted computing
> base — a ~500-byte hex assembler, then the mes C compiler written in
> Scheme, then tcc, then the full GNU toolchain, and up from there
> ((janneke) Nieuwenhuizen, 2023). The bootstrappable builds project
> has the details and it is WILD. Nix relies on more binary
> seeds. This matters for trust and verifiability — if you can't audit
> the bootstrap chain, you can't truly verify that your system was
> built from the sources you think it was.

Nix is full source bootstrapped. However, multiple packages are not properly "packaged" and vendors dependencies and binary seeds.

> 10.5. Channel authentication
>
> Guix channels support cryptographic authentication out of the box
> (Contributors, 2025l). Each channel specifies an "introduction" — a
> specific commit and its Ed25519 signature — and Guix verifies the
> full chain of signatures from that introduction to the current
> commit. Flakes use HTTPS and GitHub's infrastructure for trust,
> which is a different and arguably less rigorous security model.

Yes, guix has commit authentication, nix doesn't. It's not necessary Ed25519, but arbitrary GPG keys, probably also SSH keys support will appear in the future.

Conclusion

Flakes are not perfect, they are stuck in "alpha" and unlikely to leave it, there is a further work and alternatives to flakes like Nixtamal. Still, Flakes showcased what is possible. They did a dependency pinning, input rewriting, hermetic evaluation and standardization. They made Nix UX/DX much saner.

Guix is not here, it's around "nix-pin times" at the moment. It requires a lot of fundamental work to get overlays and multiple revisions of the same channel. The good thing, that we don't need to repeat all the steps of the Nix and can learn from their experience and do better. But we have to be clear about current state and acknowledge our weaknesses.

Support

I've spent a half of my post-surgery vacation/recovery day on this write up. So if you find it useful, interesting or entertaining, don't hesitate to support me or my projects.

A Sane Directory Structure for Software Projects

2026-03-15T07:46:00Z

Introduction

I always spend too much time setting up a new project and thinking how to structure it. I decided to summuraize my experience, to enhance it with a small research and to write down my thoughts on the topic. So I can come back to it myself or reference in the discussion.

Also, it can help me to unify my and maybe neighbouring projects structure, so it's easier to navigate and work on them. In the rest of the post I use plural pronounce, because I think this post can end up as a documentation or a wiki page.

You probably already experienced incoviniences related "naturally grown" project structure (especially in someone's repo you need to work on for some reason). When there is no clear separation between different types of source code: auxiliary, dev, build, primary, tests, environment setup, all mixed up. Randomly firing side effects, warnings, etc, just because the wrong file ended up on the load path. Mental model and reasoning are also suffering.

In this article we discuss a one particular directory structure that scales with project complexity and the rationale behind. The ideas apply whether you are setting up a fresh project or refactoring an existing one.

We expect that a code base may contain multiple programming languages. For the demonstration and examples the primary language is Guile Scheme, but most of the ideas are similar and translate easily to other languages.

We also assume that the source code is stored in text files. Yeah, there are languages, where the code stored on other medias (e.g. IPLD/IPFS, databases) and it is a really cool thing, but in here we focus on old plain files :'( BTW, Scheme standard doesn't specify, where and how Scheme code must be stored, it's implementation specific detail, so it's a cool promising area for RnD.

The approach we propose should work in the most cases. If it doesn't work, we would be curious to hear about your use case.

By the end of the reading you should understand why paths like these are so long and how that length pays for itself and make the life easier:

src/scheme-common/markdown/parser/nodes.scm
tests/guile/markdown/parser/core-test.scm

We explain it in three steps: first, how we organize and name modules, then why an intermediate "language" directory is useful, and finally why grouping everything under src/, tests/, and friends makes so much sense.

Modules

This whole section prepares a foundation for implementing a good directory structure. It's more about coding practices, naming files, modules and recapping the concepts like load paths.

Module-Path Correspondence

In many languages (Java, Clojure, Guile Scheme, etc), there is a mechanism called load paths or search paths. In such cases, module name should correspond to file path or vice versa. This allows the language to find and load modules by name whenever they are required, without knowing the absolute path to the file in advance.

The idea is simple: if you have module (my-project markdown parser) it should be located in parser.scm file, in ./my-project/markdown/ directory relative to the root of a load path. When this module is imported in the program code, the language look through all the load path directories and when it finds ./my-project/markdown/parser.scm, it will try to load a module from it.

We will talk about how to set up load paths in more detail in the section about grouping directories, for now just keep in mind that load paths are a list of directories where the compiler or interpreter looks for code.

The reason this convention matters so much is predictability. Compiler knows where to find a module. An IDE, a new contributor, or a person passing by randomly can easily guess where to look for a particular module.

Namespace (Module) Naming Rules

In the first subsection we mentioned that file path SHOULD correspond to module name, but not MUST. It was intentional. In Guile Scheme you can have a module defined in any file, moreover you can have a module defined in multiple files or have a file without module definition at all.

While all this possible, we recommend not to do so, unless it's really needed for some reason and keep module-path correspondence from previous section.

Now, the question, where (json) module comes from? You own sources, guile-json library, or somewhere else? Quite unclear. For (my-project ffi json) it's much clearer that it very likely a json bindings for C library implemented by my-project. Naming module with at least 3 elements, is a good idea for multiple reasons: clarity, minimal chance of name clashes and not too long at the same time.

First element is usually a project or domain name. In java world they use reverse domain name notation (org.apache.kafka, org.apache.spark), it easy to sort it, but we find it hard to read for humans. So we suggest to use either project name (spark ...) or a domain (kafka-apache-org ffi json) or (kafka.apache.org ffi json) if your language supports dots in module elements.

Second element is usually up to you, group it whatever way it make sense for the project. We won't give any recommendations here.

Third one is usually straightforward. The question you can probably face is: has it to be singular or plural? The short answer is: singular. Usually module represents some concept/domain, not the entities of the domain themselves. In rare case module is a collection or registry of items (like package definitions), in such cases it may make sense. If you in doubt: use singular.

We figured out the naming, now one more things to address left, a small anti-pattern in the source code inside modules.

Never Top-level Sidefectful Expressions

Back in the days, it was usual to use files as shell scripts, you probably saw shebangs like #!/usr/bin/python or #!/bin/env guile at the beginning of the file or even a direct invocation of the file like guile code.scm. While it makes it easy to run code from CLI and could be a handy trick for one shot throw away utility, it has a few serious downsides.

Imagine, your colleague writes serializer-test.scm and executes it like guile serializer-test.scm. It creates some stub markdown files, prints progress to stdout, and saves the test results to tests.log file. Now, they put this file somewhere along the rest of the project's source code. So now anybody can benifit from project having tests. Sounds good, right?

Now imagine, how surprised you will be, when after pulling fresh sources, you compile the project and get a lot of .md and .log files thrown around source code tree out of nowhere (or something even worse than that). It happens, because of two reasons:

serializer-test.scm file contain top-level expressions with side effects.
The file is located on the load paths of the compiler and thus gets loaded automatically, when compiler is invoked.

Auto-firing side effects is why we don't put side-effectful forms in top-level in our source files (and we recommend you to do the same). Moreover, the files in the load path can be loaded in arbitrary order and potentially multiple times, so it's a good idea to expose only constants and function definitions in them. In case somebody wants to fire a particular side effect or call a function, they can do explicitly:

guile -L ./our/load/path -c '((@ (my-project markdown parser) dirty-parse) "./path/to/test.md")'

Also, you probably noticed that the second point we mentioned that the code for testing got mixed into the load paths of the library itself, which can cause other potential problems. For example library source code can accidentially import some helper functions defined in tests modules and those functions can be potentially unsafe (as they supposed to be executed only during development/testing phases and wasn't audited for security carefully). We will explain how to solve it in Top-Level Directory Structure Section, and now let's talk about multiple languages and subprojects.

Language Subdirectories (Not Really)

Don't skip this section even for mono-language projects.

In modern world, it's very likely that you can't stay in the boundaries of one language. Let's imagine we are implementing markdown parser using tree-sitter C bindings, and we use Guile Hoot (Scheme on WebAssembly) for a web frontend renderer and pre-viewer.

It's already 3 languages with different compilers, module machinery (or lack of it), and other things. It would be good to store the source code for them in different subdirectories to reduce the mess and to make it clear which tool uses which source code directories and where to look for the sources of a particular part of the system. So we can split the primary source code of the project into a few units:

guile :: for guile scheme source code, (e.g. parsers, web server).
hoot :: for hoot, a scheme dialect compiled to wasm (e.g. web frontend).
scheme-common :: records, data models used by both frontend and backend.
c :: native binding, high-performance implementation, etc.
python :: legacy python markdown parser for benchmarking against.

We can already see that scheme-common is not exactly tied to a particular language, it's more of a logical grouping. Language can be a grouping criteria, but not necessary. It just happened to be the first one comming to our minds.

We could have backend, frontend and shared or c-parser, scm-parser, scm-veiwer and scm-common. Name it the way it make sense for the project, but please keep this intermediate level of directories even if it's only one at the moment. You never know when you will need to introduce a new language or split the existing system in a few subsystems.

Now, if we followed this convention, the navigation becomes easy. For native bindings we look for tree-sitter-helpers.c in c/ directory. If we look for a frontend code, it's in hoot and some shared between frontend and backend is in scheme-common. Also, constructing load paths or pointing compiler to the sources becomes simplier:

GUILE_LOAD_PATH="./guile:./scheme-common" guile -c '((@ (my-project web) server))'
HOOT_LOAD_PATH="./hoot:./scheme-common" guile -c '((@ (my-project hoot) generate-wasm-binary))'

We know that there is no unintended backend code leaked into frontend build. Also, we know that our primary source doesn't rely on any shady util function from a test module, but we know it due to the idea from the next section :)

Top-level Project Directories

How we ensure that no test or dev code end up in the release? We put them in separate directories(!), so it's hard to unintentionally mix them up. There are 4 top-level source code directories we propose.

env/ :: code for setting up dependencies and development enviroments.
src/ :: the primary source code.
tests/ :: tests, I guess.
dev/ :: drafts and snippets useful for development, but not going to the final build.

Even in a small personal project you will very likely need all of them. You need to setup the dev environment (libraries, compilers, etc) and it's better to persist in, at least as env/setup.sh, but better something like:

env/guix/my-project/channels.scm :: guix channels for exact guix revision and repositories of packages.
env/dev/my-project/packages.scm :: package definitions and collections used for development/testing.
env/release/my-project/packages.scm :: packages need for release, to make sure no dev/test/debugging functions leak into final build.

You can see that we follow a grouping pattern similiar to the one described in the previous section. It's a good balance between verbosness and clarity.

For src/ we do the same: apply the intermediate grouping level from the previous section. The primary source splits into subsystems or languages, and each subsystem lives in its own subdirectory:

src/guile/ :: Guile Scheme backend code.
src/hoot/ :: Hoot frontend compiled to WebAssembly.
src/scheme-common/ :: shared data models and records.
src/c/ :: native bindings.

Constructing release load paths is now simple and explicit:

GUILE_LOAD_PATH="./src/guile:./src/scheme-common"

Apply the same grouping to tests/, mirroring the structure of src/. A test for src/guile/my-project/markdown/parser.scm lives at tests/guile/my-project/markdown/parser-test.scm. The mapping is mechanical: swap the top-level directory and append -test to the filename. Finding the test for any module takes zero thinking and is easy to implement on IDE side.

The dev/ directory is for anything useful during development that has no place in the final build: REPL session snippets, profiling scripts, one-off data migration helpers, experimental ideas. It follows the same grouping convention:

dev/guile/my-project/drafts/bench.scm :: benchmarks.
dev/guile/my-project/drafts/scratch.scm :: throwaway experiments.

The final dev load paths will look like:

GUILE_LOAD_PATH="./dev/guile:./tests/guile:./src/guile:./src/scheme-common"

Beyond the four source code directories, there are three more, you will likely need:

doc/ :: architecture notes, design decisions, onboarding guides. Not inline code comments, but the higher-level texts that explain why the system is the way it is.
target/ :: build artifacts and generated output. Never committed, always in .gitignore (or similiar). Having a dedicated name avoids the build/, out/, dist/, _build/ lottery.
tmp/ :: throwaway files that don't deserve a place even in dev/. Also gitignored. Better to have an explicit place than to let the junk and temporary files accumulate in the primary part of the repo.

Putting it all together, the full project tree looks like this:

my-project/
├── dev/
│   └── guile/
│       └── my-project/
│           └── markdown/
│               └── bench.scm
├── doc/
│   └── architecture.md
├── env/
│   ├── dev/
│   │   └── my-project/
│   │       └── packages.scm
│   ├── guix/
│   │   └── my-project/
│   │       └── channels.scm
│   └── release/
│       └── my-project/
│           └── packages.scm
├── src/
│   ├── c/
│   │   └── tree-sitter-helpers.c
│   ├── guile/
│   │   └── my-project/
│   │       └── markdown/
│   │           └── parser.scm
│   ├── hoot/
│   │   └── my-project/
│   │       └── markdown/
│   │           └── viewer.scm
│   └── scheme-common/
│       └── my-project/
│           └── markdown/
│               └── node.scm
├── target/
├── tests/
│   └── guile/
│       └── my-project/
│           └── markdown/
│               └── parser-test.scm
└── tmp/

Slightly verbose, but clear, predictable and scales well. We are pretty happy with it, so we hope you will be happy as well. Or maybe not, anyway, do NOT contact Andrew, he works on fileless and directoryless, content-addressable future for our civilization.

How to Set Up Guile Load Path

2025-10-30T12:00:00Z

Introduction

Guile Load Path is a place (or more precisely places), where Guile looks for the source code. This is the first thing one needs to set correctly to work on a Guile Scheme project. It makes Guile aware both of your own modules and external dependencies. For more details refer to Load Paths page in Guile Reference Manual. This guide will focus on getting and setting the right values for it and discussing different approaches to do so.

Getting the Load Paths

The current value of all load paths for the current guile process is stored in %load-path variable, so it's easy to obtain it in runtime using CLI, REPL or your IDE. To see what value it has you can just pretty print the variable.

> guile -c '((@ (ice-9 pretty-print) pretty-print) %load-path)'

("/home/bob/.guix-home/profile/share/guile/site/3.0"
 "/run/current-system/profile/share/guile/site/3.0"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

By default with a clean Guile installation you should see only the directory which contains Guile's own source code. In more real-world scenarios, for example, in Guix System, I see two combined directories containing my system's and home's guile packages respectively, the directory with guile's sources and a few bogus entries, which I have truncated with ellipsis (…).

> echo $GUILE_LOAD_PATH
/home/bob/.guix-home/profile/share/guile/site/3.0:/run/current-system/profile/share/guile/site/3.0

The first two directories comes from the environment variable $GUILE_LOAD_PATH. The rest are baked into guile distribution.

Getting a Clean Environment

To get a clean environment you can unset $GUILE_LOAD_PATH variable (to ensure there are no dependencies added to the project accidentally). You can also construct a pure environment with guix shell --pure guile, which has similiar effect, but for the sake of clarity we will unset the variable manually.

> unset GUILE_LOAD_PATH
> guile -c '((@ (ice-9 format) format) #t "~y" %load-path)'
("/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

The guile's libraries directory is still present in load paths. It is hardcoded in the guile binary and not affected by GUILE_LOAD_PATH.

Setting `GUILE_LOAD_PATH`

Now, let's assume there is a project module (myproj core) in ./tmp/guile/myproj/core.scm' (usually it is src instead of tmp, but we provide examples, which are easy to clean up by invoking rm ./tmp -r).

> mkdir -p tmp/guile/myproj \
echo "(define-module (myproj core))" > tmp/guile/myproj/core.scm \
echo "(define-public (main) (display 'hi))" >> tmp/guile/myproj/core.scm

Trying to run guile -c '(begin (use-modules (myproj core)) (main))' leads to no code for module (myproj core) because this module is not on the load path yet. To fix this, you have to add tmp/guile to the load path. Pay attention that we add tmp/guile and not tmp or tmp/guile/proj. The module (myproj core) have to be in myproj/core.scm file, which must be located in the root of a load path, if this convention violated the module won't be found. Let's temporary set GUILE_LOAD_PATH for the next invocation of guile.

> GUILE_LOAD_PATH="./tmp/guile" \
guile -c '(begin (use-modules (myproj core)) (main))'
hi

Voila, we got a message printed by the main function.

The Order Matters

It's possible to have a few directories by separating them with colon.

> GUILE_LOAD_PATH="./test/guile:./tmp/guile" \
guile -c '((@ (ice-9 pretty-print) pretty-print) %load-path)'
("./test/guile"
 "./tmp/guile"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

The order matters: if there are two modules with the same name on the load paths, the first one encountered will be used.

Also, there is a special three dots value (...) you can use when setting GUILE_LOAD_PATH. It will get expanded to the path of guile's own libraries. This is useful if you want to make sure your library doesn't override any built-ins. Keep in mind that this three dots is distinct from the ellipsis I have added when truncating the output of the guile command for this blog post.

> GUILE_LOAD_PATH="./tmp/guile:...:./my-srfis" \
guile -c '((@ (ice-9 pretty-print) pretty-print) %load-path)'
("./tmp/guile"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …
 "./my-srfis")

Adding to `GUILE_LOAD_PATH`

Sometimes the GUILE_LOAD_PATH is already provided and set and you want to extend its value. It doesn't really matter if it comes from guix shell, set by the script of your colleague or whatever. For demonstration purposes, we will set it manually in our shell.

> export GUILE_LOAD_PATH="./path/set/by/someone-else"

Almost always, you want to prepend the directories you need to the existing value.

> GUILE_LOAD_PATH="./dev/guile:./test/guile:${GUILE_LOAD_PATH}" \
guile -c '((@ (ice-9 pretty-print) pretty-print) %load-path)'
("./dev/guile"
 "./test/guile"
 "./path/set/by/someone-else"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

Pay attention that we set a variable only for the next invocation of guile. We do not mutate the variable value, and if we run this code a few times we won't see the duplicated values in the load paths.

To append to the existing GUILE_LOAD_PATH or order the directories anyhow else, just move ${GUILE_LOAD_PATH} accordingly.

In addition to GUILE_LOAD_PATH, there are at least two more ways to adjust load paths: via CLI and API. It's good to be aware of where else load path values can come from, especially when you work on someone else's project.

Modifying via CLI

For most cases GUILE_LOAD_PATH is enough and should be used, but sometimes it may be tricky or inconvenient to set environment variables. The guile command line program has the -L flag, which allows for prepending a directory to the load paths.

> guile -L ./dev/guile -L ./test/guile -c '((@ (ice-9 pretty-print) pretty-print) %load-path)'
("./dev/guile"
 "./test/guile"
 "./path/set/by/someone-else"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

This is a complete equivalent to the example from the previous section. The order of added directories still matters.

`-L` Has Priority Over `GUILE_LOAD_PATH`

An important thing to know is that -L directories have higher priority than GUILE_LOAD_PATH directories. GUILE_LOAD_PATH is processed before command-line arguments, and then -L prepends its directories to the front of %load-path. This means -L entries always come first.

> GUILE_LOAD_PATH=./env1:./env2 \
guile -L ./flag1 -L ./flag2 \
-c '((@ (ice-9 pretty-print) pretty-print) %load-path)'
("./flag1"
 "./flag2"
 "./env1"
 "./env2"
 "/gnu/store/37m0a0ydy74wl2qrf2w1jdgqhxwbaxac-guile-3.0.9/share/guile/3.0"
 …)

The effective order in %load-path is following:

Directories added via -L (leftmost -L argument has highest priority).
Directories from GUILE_LOAD_PATH.
Guile's built-in default paths.

This is useful when you need to override a module provided by the environment for a specific invocation without changing GUILE_LOAD_PATH.

Modifying via API

So far, we have used %load-path to get the value of load paths, but we can also use it to set load paths with set!.

We do not recommend setting load paths dynamically (in runtime) via API. All load paths should be known before the guile process is started and thus they should be set via GUILE_LOAD_PATH, but if you are really sure you want to, there are a couple of things to know.

%load-path must be modified before the expression is evaluated. That means if you need to set load paths in the same expression you want to use the new value it should be wrapped into (eval-when (expand)). See Eval-when for more details.

> guile -c '(begin (eval-when (expand) (set! %load-path (list "tmp/guile")))
(use-modules (myproj core)) (main))'

Don't forget to preserve the necessary values of the %load-path, otherwise things can break, such as goto definition, loading modules, etc.

(set! %load-path (cons "new/dir" %load-path))

There is a convenience wrapper macro, which does both of those things: add-to-load-path, but we hope you will never need any info from this section.

Clean Up

To wrap up all the things:

Do rm -r ./tmp to clean up all the tails.
Thank authors of this guide.

Acknowledgments

Edited by Joseph Turner.

I Have to Live in a Forest to Work on Open Source

2025-10-19T10:00:00Z

This fictional story begins more than 10 years ago. I was a student at technical university and was confused by how outdated some of the programming-related courses are. I was checking out a few first lections and usually skipping the rest of them (except a couple courses that were fun and uptodate). In my spare time I was tinkering on gentoo linux, cybersecurity and competitive programming (codeforces, ACM ICPC, etc). I wanted to start working ASAP, so that I could finally get to the most interesting part, but man, how wrong I was...

This write up is inspired by my university friend, who made a film about my time living in a tent in a turkish forest and working on my FOSS projects.

The Corporate Work

To impress one girl, in third year of University, I passed an interview and got a job offer in the hugest internet corporation in the country. I did a bit of Python/webdev and in a few months and a couple of internal interviews I switched to SRE role for search engine and services around. This was my first disenchantment in technologies and processes around. Everything was a mess and barely maintainable. Three implementations of string type with different memory allocation approaches, monorepo of hundred gigabytes, tons of services glued together and only the god knows how they keep working.

But the worst part is not a mess or lack of well-defined processes, the worst part is a feeling of helplessnes, a feeling that your have a 0 impact, you just spend months of your life to keep this stuff floating. 1 year into corporate work and I have a clear understanding that health insurance, extremely comfy office with massage, yoga, language clubs, cookies or watever you can imagine, a salary times higher than the average in your country doesn't matter if you feel miserable. Moreover, I was afraid to get into the trap of comfort and to start stagnating together with the corporation and its messy codebase :) P.S. The girl wasn't particularly impressed by those achievements as well.

New University and Startups

Luckily, around this time I got a chance to switch the university. This time it was fun. It was a completely new city built for this particular Uni, professors were from all over the world, program was made in collaboration with CMU, almost all communication was in English. It was tons of fun. I had a good background and amount of hard skills to keep up with studies relatively easy and I took the opportunity to acquire soft skills and business skills as much as I could.

In addition to techncical communication, enterpreneurship and other courses, we were building students community and organizations, creating sport clubs, changing the university itstelf, participating in hackathons, and spinning up startups. The amount of energy and effort was impressive. We've built a streaming app, before periscope became a thing, created a delivery service for our city before taxi apps appeared. And this is only a couple of projects I personally was in a charge of. A lot more things were happening around. It was exciting time.

I didn't forget about Computer Science and cool technologies and was learning Lisp, FP and Clojure in parallel. So mindblowing, so interesting. I desired to apply it in a real world. Maybe rewrite the delivery platform? A few days after the meeting, where we discussed a potential refactoring, my uni friend came to me and asked: Would you like to help my two friends from UK and France to build a platform for managing commercial buildings? We can use watever tech stack you want.

Despite being a cool experience, the delivery wasn't a profitable project, it was more like a fun pet project made by students for city citizens. It was already at the end of its lifecycle, so getting into a more scalable international adventure was tempting. We had a calls with the guys and started to build the platform from scratch in a completely new and unusual tech stack.

The Dark Times

Everything started bright and fun, we were building and delivering relatively fast, techonologies were awesome and all that, but there were a few catches. 1. I wasn't a founder of the project and didn't have a enough "business vote power". 2. My soft and leading skills were much better than a few years ago, but still very suboptimal. 3. I already had enough fun with business parts in delivery project and was focused almost solely on technologies and software development in this one.

I was designing architecture, CI pipelines, containirized infrastructure (before kubernetes was a thing), workflows, I was doing docs, refactorings, scrums-agiles, onboardings, task tracker configurations, etc. It was a lot of new and important experience, but at the same time it was a lot of load. Of course, I couldn't do everything well. There are a few conflicts and tension points appeared in the team and I didn't resolve them properly and completely. Moreover, I didn't have enough energy to do so. I was tired. I was exhausted.

I cared too much about tech and processes, but let the other aspects of the project slip, including communication, top-level decision making power and meaningfulness. At the point, where I overworked, stressed and lacking power and leverage, it was extremely hard to change anything. I couldn't just keep working, because I was almost physically vomiting when open the project in the text editor. I decided to leave.

Cause of my random contribution to some open source Clojure project, just a couple weeks after I left the project, I got an invite for an interview. Did I mention that for my whole life I had a desire to make a free and open source software? It looked right to me, it felt important and impactful. Some of it were inspired by hacker culture of 2000s and my youth idealism, but some of it became a part of me and became a kind of an internal belief.

However, it was never enough time for it. Everyone around were telling you can do it next sprint/month/whatever, let's finish this feature first, or we can't do so, otherwise our competitors would be able to steal our tech, so I was only casually contributing to FOSS, when I could, but it was usually minor. Even with those minors contributions, somehow I got this invite.

The Alps

The interview was by the one of the best Clojure teams in my country and I passed it relatively easy and also got x5 salary without any negotiation. Yes, I cared only about technologies on my previous project and it wasn't too hard to make an x5, but it was still quite high salary for the market at the moment. This time I didn't have any expectations. I just wanted to save money and buy a free time to recover from my previous overworking experience.

Plan was simple: Work for a year, save some money, get at least a couple years to travel, work with psychologist, play the games, ride the bicycle and feel happy.

I moved to the cultural capital (most beatiful and historically rich cities), spend a few cool, fulfiling and interesting days at my ex-coworker's place (fellow hacker and researcher, one of the important figures in tor project), while looking for an appartement for rent. When I found the apparts near the office I moved in and started my new job.

The work was relatively boring, I myself was tired, but I was following the plan: I was saving around 90% of the salary and did my dids and duties. I also had some activities outside of the work: riding the snowboard, learning acrobatics, visiting mountains from Siberia to Alps, hanging out with friends, visiting some iconic historical places, traveling for hackathons and conferences around the Europe.

Despite the fun I got from sports and social life, I still felt exhausted, I didn't want to wake up, it was hard to get up from the bed, it was not much reason to do so, it was a deep apathy. Luckily, around this time I got allocated to lead a new project, a EMR for hospices in US. This turned out to be an incredible experience.

It started, when we with my friend were hanging out in Austria, in cozy chalet on the side of the mountain. We got tickets for airplane for 80$ (the price for both ways, we got it half a year in advance on a random sale), and rented a room for 10EUR/night(?) We had to share the bed and we were cooking ourselves to keep expenses low, but it was incredibly amazing place. Not usual "amazing", but really-really amazing. The weather, the snow, the views. We were snowboarding the powder, glashiers and forests. We were comming back home in the evening and eating meals we made near a crackling fireplace.

In one of such beautiful evenings of my vacations I got a work call, the call about this potential new project for hospices. I met two stackeholders and we get to know each other a bit. It was pleasant, they were nice and seemed smart, their expectations were unrealistic, but they were very cooperative and understanding, so I got a feeling that it can be a fun project.

Grown-Up Start-Up

After I came back from vacations I started to work with those two guys from US and building a PoC of the system. We were discussing requirements, did remote user testings and assesments. I onboarded a couple more devs in the team and we started to build stuff even faster. It was very pleasant to work with those men, I was genuinely happy to interact with them, but I wasn't too much excited about the project, I wasn't too much excited about life in general at the moment. It was just another commercial EMR. I didn't feel any meaning in it, I only felt that I'm underemployed, I make some CRUDs and web pages, when I spent years learning quite involved Computer Science and Math.

It was already almost a half a year into the project, but we still didn't have any real users. Moreover, I was afraid that the system we've built was based on our discussion and extrapolations mostly, rather than on real use-cases. I suggested that I come to US, go around the hospice and we interview doctors and nurses, visit their planning meeting and all that things.

It turned out to be a great experience, together with my lovely stackholders we collected a lot of data and insights and adjusted the current implementation quite radically to fit the real needs. Besides the work I had a lot of new experiences (video log 1, vlog 2): visiting a lot of places, shooting guns, dating a wonderful girl, spending a time on the farm, going to hot springs, learning Spanish from Mexican workers, watching american football games IRL, doing beautiful hikes.

What is more important I've built a long-term friendship with Troy and Robb. After I spent time in hospice, the project became more meaningful, I started to feel the real need for it, I also had a lot of impact on the project. It didn't feel completely right because of proprietary nature, but other than that I was very happy about it. The humans involved in it were top-notch, interactions with them were a pure pleasure.

Burning and Saving

We were getting closer to one year point mark, still not yet deployed on our first hospice (owned by one of the four stackeholders). I work as hard as possible and we get all base functionality ready, but it has the price: I got even more exhausted. Guys are very happy with what we achieved and asking me if I want to become a stackeholder. Rationally speaking, it's a great opportunity: wonderful humans, very reliable and scalable business, fancy tech stack, but personally I don't feel like it's the right way.

It's a proprietary software and it bothers me. It's a CRUD web app and feels much less than I'm capable of. And last, but not least, I still exhausted, maybe even a bit more in the last a few months, so I'm afraid that I would unintentionally start sabotaging the work we do if I keep working on the project.

At this point, I had enough money for 10 years of a quite minimalistic life. I have an apartment at home town, my expenses are low, I spend around 100$ for food and 100$ for sports a month and do occasional budget-friendly trips around the world. We made the first production release, onboarded a few people (nurses and doctors) and got our first billing done IIRC. And... I deciding to leave the project, follow my original plan and finally get some rest.

Vacations and the Start of Open Source Journey

I allocated two month to do nothing. I spent a couple of weeks laying on the bed and walking around. After that I started to play some video games, wandering around the town and going for casual street workouts with my friend. It was intentional, I was learning how not to blame myself for not being productive, I was learning how to care of myself, my physical and emotional health. I started to feel, I stopped to hurry. After those two month I built a bit of useful boredom, which made me continue to tinker on Nix, reproducible dev environments and all those things.

I couldn't work much at the beginning. Maybe 15 or 30 minutes a day before I got exhausted again, some days I couldn't work at all, sometimes I couldn't even speak. Slowly but steadily, I got my curiousity and courage back. I started to make videos and streams on the topics I learn and explore, I started to build my small FOSS pet projects. Not immediately, bu I got back some of my ability to work and to live. I found power to get a few sessions with psychologist and it also helped to feel better or at least something (:

In half a year I got to the level, where I could work a few hours straight (not every day, but quite often). I already had a few minor FOSS projects and I switched from Nix to Guix (because I wanted a general purpose language instead of DSL and liked lisps ATM). It turned out that there is no Home Manager for Guix, however, it wasn't a big deal, I had a confidence that I can make it myself and I did it. I built it in a few months and later upsteamed it to Guix as a Guix Home subsystem.

This was a year into my Open Source journey, but I already gained a lot of my productivity, curiosity and fullfilment back. I made a few FOSS project like RDE, Guix Home. I got a lot of positive emails and feedback. I became much more lively and happy. I wouldn't say I was completely happy at this moment, but I was a half a way into it.

The War

I definitely was on a right track and everything were getting together and I was getting better with every day. I was tinkering, having fun, getting the meaning, happinnes and liveness. I felt like taking a few years off and working full time on Open Source was a great decision. The year went quickly, I did a lot of contributions to mine and others FOSS projects, I broke my leg on a wakeboard, got into climbing and kayking and planned two trips for the winter.

I've spent New Year week in Turkey in the mountains climbing with folks I met a couple of months before in a climbing gym. Two months later I had a snowboarding trip with my university friends in Siberia. One morning I woke up 5 am and saw my half-sleeping friend watching some crappy message by president on TV in the other room. I was like: what the heck are you doing, bro? He replied: it seems like the we (goverment of our country) started a war. I was: No way, you are messing with me.

We couldn't accept this fact for a few days, we couldn't belive that it can happen in the 21th century, but it actually happened. We continued to ride the powder and tried to enjoy our time, but were constantly scrolling the news in disbelief.

A few month forward, I got a new pasport for travels instead of expiring one, got some other documents ready, packed a backpack, took my mom's car and went to the Georgia for unknown amount of time. I had only a couple thousands of dollars in cash and a couple more I transfered to my friend three months before. My savings on the bank and investment accounts were frozen, so instead of peacful 10 years of minimalistic life I just got into unknowns without a job, a home and running out of budget quickly.

The awfulness of war, opressive regimes and all that are important topics, but we won't talk about them today, let's focus on how I ended up in the forest writing an open source software.

Running Out of Money

I've been to Georgia (Sakartvelo) in 2019 and was a bit familiar with this beatiful hospitable country. This time it was even more enjoyable experience. So much new and interesting things, a lot of infrastructure improvements since the last time. The weather is so wondeful, that it was hard to be stereotypically grumpy as I was the whole life. Almost every day is sunny and nice. I was enjoying every moment here.

The bureauchracy is very manageable, I got a sim card, bank account and legal entity in a couple of weeks. After the most of the paperwork was settled, I came back to my FOSS projects, spending tons of time with them. The only issue at the moment was money, they were evaporating fast. With two my good friends we were renting a room at guesthouse. It costed around 200$/month/person, but it was too tight for 3 people. A little bit later we found an apartment with 3 bedrooms and it became 500$/month/person (yeah, this is quite expensive for Georgia, but a lot of people came here cause of the war and the demand was too high at the moment). It was sparse and comfy, I finally could function properly and work efficiently.

A half of the time I was coding, half of the time I was researching and trying to build a sustainable financial model for the projects and a half of the time doing side projects to replenish the treasury. It turned out to be quite a hard task to raise funding for FOSS work, without getting into VC money. And VC money will likely screw up your project. At least from what I see from other open source projects nearby.

Donations and Trip to Turkey

Other option was donations, I made an opencollective page and it is quite successful for the size of the project, we get around 2-3k EUR/year. However, it's not enough to pay the bills (at least at the moment) even for one person, not talking about other contributors. So, I decided not to rely on them and keep it as a backup for the harsh time or some project-related activities (later we organaized an internship for RDE from this funds).

I started to look for consulting contracts, so I can apply the stuff I develop to real world projects and also get paid for it. I knew from the beginning that at some point of time I'll need to get money for my work somehow. That's why when I started my Open Source Journey a couple years ago I also started to make videos and streams.

Thanks to those videos I landed my first guix-related contract. I went to the Turkey for one month, built a custom Guix-based operating system for PinePhone, teached a small dev team about Guix and Emacs and had a very pleasant time with very hospitable guys. It also gave me enough money to cover the next few months of my life.

By the end of the spring our rent finished and we with my friends moved apart. I found a room in a coliving for 300$/month and was keep looking on how to stay afloat.

UAE to Save Money

I was invited to teach a lisp course in Lalambda 2023, a summer school on advanced programming and contemporary art. It's a not for profit activity, but I like teaching, so I committed to it and spent a few weeks preparing materials and exercises for students. At the same time we were chatting with my mid-school-times friend and he invited me to stay at his place in Emirates and to hang out. It was a nice opportunity to spend time with my friend and also save some money. I took tickets to Abu-Dhabi for the next day after summer school finishes.

Lalambda was a fantastic experience, the classes went great, I got a lot of positive feedback, I met many cool people and a very nice girl with PhD. And on this positive note I left Georgia.

Next three month I spent in UAE. It was hot, 46-48 degrees celsius outside, so most of the time I spent either at home working or at climbing gym training, and of course sometimes hanging out with my school friend and his friends.

Very cool and productive times, I implemented a lot of features in my current projects, made a few releases, started a new FOSS project (an IDE for Guile Scheme) and started preparation for upcoming conferences.

However, my UAE visa was expiring and I had to find another country to stay. Finances didn't get better, so it had to be very inexpensive country. I decided to go head first into the Turkey as most cost efficient and familiar option I knew at the moment. I've been here a couple of times already: wakeboarding in 2020, rockclimbing in winter 2021-2022 and consulting in 2023. But this time was different, I had a backpack, 900$ and 200EUR in cash and no foreseable source of funding.

Hiding in the Forest

Fast forward a few intermediate stops, I landed in Antalya and was looking for the bus to Geyikbairi (a pine forest valley surrounded by mountains, a disneyland for rock climbers). I've been here in 2021, but last time my friend picked up me from airport and delivered straight to the bungalow, this time I was on my own. I missed the bus, but somehow managed to get to the valley. I had a tent booked in one of the campings for 8EUR/night, it included access to shower, kitchen and common indoor space.

There was a cat (a few of them) in the kitchen and common space, causing a severe allergy. So I was walking around the valley and looking for another place to stay for a few days and found another camping, namely camp Geyik. In the meantime I recorded my talk about Scheme IDE for EmacsConf 2023, so people can see what cool stuff I'm working on.

After I finished with conference talk, I went by bus to the city and found a two person (actually 1.5 person) poked and fixed tent in Decathlon for ~100EUR and a blanket for 5 EUR. Came back and negotiated a price (around 800EUR for 4 month) for access to common area, kitchen and shower. Found a cozy spot in the woods, pitched a tent and started to work even harder on my FOSS projects.

Surviving

I had around 100$ left, the visa allowed to stay for 3 month in a half a year (with mandatory visa run after first 2 months), the winter was comming, the rains and the winds were getting stronger. That was only the beginning.

I Crashed on the Road Bike at 50km/h, and I ...

2025-08-31T06:00:00Z

I liked the feeling afterwards. Don't get me wrong, I don't like to be hurt or being in pain and luckily I didn't get any serious injuries. There is just a thought that stroke me after a fall: I'm finally safe and healthy. A very long-awaited and desired thought, and it's not even related to the cycling. You probably have a WTF moment reading this, but let me explain.

Struggles, Ilness, Anexiety

It was two extremely tough months for me. Everything started with the wrong appartment pick: we rented one that looked new, pretty and comfy. At first everything was ok, we moved in, bought some houshold bits and pieces, and everything seemed nice and settled.

Somewhere around this time I started to work on my first scientific paper. I didn't have supervisor, I didn't have much time before submission deadline and much previous experience either, so I was not expecting it to be easy for sure. Also, I was very motivated to write and submit the paper as it were a few coincidences that made this conf a very good match for me:

I had a couple of projects, which are very much ontopic for this conf.
I got an email from one of conference organaizers inviting me to send a paper to it. This is a funny one, I thought I didn't know him, but later I realized that a couple of weeks before I downloaded one of his talks to watch later.
The conference was in accessible location (Singapore): it's nearby and most importantly getting a visa to it for me is easy. You probably can't imagine what bureaucracy acrobatics I had to pull off to be able to recieve payments for my FOSS work after I left my country 3 years ago. Getting a shengen visa is even more challenging. Toxic passport is not a joke.
Recently, I started to learn about Japan, there culture and language and with every day I enjoy and willing to visit this country more and more. There were at least two professors from Japan, so I could easily make connections and potentially get an invite to teach Computer Science in Japan.

Obviously, I started to work hard to get it done. It was like a 10-16 hours a day, and in addition to that I cut almost all social and physical activities (they took too much time and attention). I was going out to see people maybe once in a week, had about 2-5 hours of yoga and a bit of walking from cafe to cafe, the rest was the paper. I kept my sleeping schedule as usual, from ~22 to sunrise, and added day naps to reset and be more productive in the second part of the day.

It's not a surprise that by sitting so much in front of a laptop, I developed a wrist and back pain quite quickly. But what surprised me that I got ill. I haven't been any seriously ill for 2 years and here I got the whole set: fever, cough, phlegm, foggy mind, extreme tiredness. I thought it could be the result of overwork and I stepped back a bit: relaxed my working schedule, got a lot of additional sleep, drank a lot of water and did more walks and ... It didn't help.

My condition was varying from manageable to bad. A week and a half later I went to the hospital, got X-ray, blood test, bronchitis diagnosis and antibiotics prescription. Started to take pills and an hour later got an extreme abdominal pain, so bad that I couldn't sit or stand. I had so sever pain in the stomach area only once in my life, in the childhood, from allergy to wild strawberry. A few days later I noticed a rash on legs and arms. Turned out I'm allergic to this antibiotic.

I still finished the prescribed course and it seems I got better. Meantime, my friend Shilin (athletic and healthy guy, who I rent apartment with) got exactly the same respiratory sympthoms (maybe just a little bit less intense). Ok, maybe it's a local vietnamese virus or bacteria we don't have immune response against? The hypothesis is sound.

A few days later, I had an early morning date, but around 4am I had to write that I won't come cause... I'm ill. Again. The same way as before. It's already became very annoying and stressful. It's hard to work, it's hard to see people, it's hard to exist. At this point of time, I assumed that it can be environment/air quality problem.

It turned out that apartment has a horrible (non-existing) ventilation and also I started to suspect that it can have mold, but I didn't have any way to quantify the problem. I tried to find an agency, who can do air quality tests and measure, but found only one organization, which unfortunatelly operates only in the other city. The research brough air quality monitors to my attention and I order one of them from Japan (it still on the way). In the meantime I also ordered hygrometer, air purifier, pulseoximeter and N95 masks.

A few weeks fast forward. I tried to temporary move to hotel and it made me feel a bit better, but the sleep quality was far from perfect and it was hard to tell if it really helps or I just got better overall at the moment. I came back to the apartment. Sleeping in the mask and using air purifier subjectively eased the sympthoms a bit, but hard to tell how much.

I finally finished my work on the paper, submitted it, and was very keen to troubleshoot this extremely annoying and dangerous problem. I went to the hospital for the third time (this time the other hospital, the fanciest in Da Nang). The X-ray didn't show nor positive dynamics, neither negative. Still bronchitis. I got corticosteroids and a third type of antibiotics prescribed in the span of less than two month! Shillin was also ill for almost the whole time of the story and also took prescribed to him antibiotic without much improvement.

A day later, I noticed that we have a round patch of the mold appeared in the shower. I asked an apartment manager to help us with mold issues and... they just painted the mold with white paint 🤦. We didn't get any other collaboration on this problem. My good and caring friend noticed my post on fediverse about air quality, and dropped an email advising to move out ASAP.

I also noticed a few dark spots appeared on the wall in my room. And it stroke me: they probably painted the black mold in my room and it just grows trough the paint! I wanted to deconstruct the wall to check my guess, but at first I started to explore every possible corner of the room and found white and green mold in the toppest and almost inaccessible shelves of the wardrobe. There were signs that it was swept into the corner (probably by cleaner), but it continued to grow of course.

This was the last bit. It was not only a hypothesis, it was a fact that there are huge mold problems in addition to ventilation and humidity issues. At this moment, I was already very anxious and stressed. I couldn't properly sleep, I couldn't work. In addition to that I got a reject for my conference paper. I tried to comfort myself with food and cozy kind movies. I tried to distract myself with intense workouts: boxing, kettlebells, yoga, swimming, cycling. As you can guess, it didn't help much: I still was anxious, but also extremely tired at the same time 😄

I realized that I'm to anxious, I can't fall asleep, I can't do a thing for my current projects. I spent two days going through all possible apartments for rent nearby, found a manageable one, gave up on deposit and moved out the same day. The next day I found an apartment for my friend and helped him to move out as well.

Even after the move I felt extreme anexiety, every small inconvinience triggered me, I was worried about any tiny failure or interaction I had. I was afraid that I could be wrong about the cause of my health problems and it won't get better, I was afraid that my bus for visarun will be cancelled, I was worried that I annoyed and gave troubles to a bartender by asking to redo matcha without sugar.

Before visarun I got only 2 hours of sleep and woke up at 2:20am to get to the car at 3. The visarun itself went smoothly, I came back around afternoon. Had a walk and dinner with my vietnamese friend and fall asleep around 20:00, and got 10+ hours of uninterrupted sleep! The next day I was feeling good and rested, confirmed the next morning ride with local cycling shop owner, and had a relatively calm and good day and manageable amount of good sleep. This is where the story about the crash starts! :)

The Crash

I woke at 5:15, brushed my teeth and at 5:50 was at the bike shop. It was my 3rd ride in the last years, and it was intermediate-advanced level ride with average tempo about 20km/h and quite steep climbing. I was invited to it as I showed enough level of fitness on the previous casual ride. I got a very basic rental road bike and we went for a run.

The run was not easy, on the flat surface it was hard to keep up with the group, on climbes I was getting around 190 pulse, but still could clearly talk and even oversustain some of the fellows. The athmosphere was very friendly and nice. Everyone was smiling, chill and having fun and good gigs. Somewhere around 20km mark we turned back, and on the way back we started to decend the steepest climb. We were notified by the lead of the group to be careful.

The first few guys with fancy carbon bikes went 80km/h or maybe more and quickly dissapeared from the sight. As for myself I went fast (for me), but controlled, around 50km/h. Another advanced guy in tight shorts and on the the fancy bike bypassed me with ease, but I didn't try to keep up, I instead started to check my breaks and preparing for the turn.

A couple of seconds later, I was watching this guy losing control and going head first into the stream near the road. My first thought was: if he got unconsiousness, he can drawn! I need to stop quickly and help him out. I pressed breaks. Probably pressed them too hard. At the same time I've reached the wet asphalt section. I'm not used to ride narrow tires and didn't expect how they will interact with the surface. You can guess what happened next.

Instead of gradually slowing down, my bike started to wiggle like a crazy. For a few second instead of riding I was sweeping with the tail of my bike like a newbie snowboarder in their first days learning edging. It could last forever and at some point I lost the control and flew away.

It's funny, but I didn't feel any worried before the crash. I was certain that everything is under control and I can easily stop at any moment. Even when the bike started to wiggle I was more surprised than stressed. I don't even get any noticeable adrenaline kick.

The crash itself was quite comfortable: I hit the ground and slided a bit on my back, I was in a helmet, but I didn't touch the ground with my head. Probably the wet asphalt helped to slide and avoid serious skin damage. I started to feel the parts of the body I hit straight after the crash and it wasn't any bad. The next day I could feel brusies and soar neck muscles. It was hard to do mobility workout cause of soar bun, but the next day it was good.

I already had 2 yoga and kettlebell workouts and it's fine. The only worrying part is that a part of the elbow bruise has a sharp pain on press. I guess I need to do an X-ray to check there is no bone fracture. BTW, the guy went head first into the stream had even less bruises and scratches, but much more mud on him :)

I hope you enjoyed the details of my fun morning on the monkey mountain, but the best part came later. We ensured that everyone is ok, and hot fixed our bikes and I realized that I'm finally healthy and safe, I'm in a good and supporting community, I don't have cough, I don't have anexiety. I feel so much better now.

Stay away from fungies, ride more, find great people, have a piece 🤟

Actually Useful Stack Traces

2025-06-20T12:00:00Z

Stack traces, backtraces—whatever you call them, I never liked them. Every time I saw one, the only thought in my mind was: "And now what?" Then I discovered a particular implementation, and I felt like a kid in a candy store. I guess I know what made it so useful for me, and thus, so exciting. We will take a look at a visual demo and talk about how one can build an interactive debugger on top of it; but first, we need to discuss three issues.

The problem is simple: the usability of stack traces sucks. Let's take a look at primary suck points, and we will quickly understand how to avoid them and how to get a good UX:

Stack trace is a text
It's either convoluted or lacking
It's upside down

Why is it upside down? That's a very good question at the very right time. As you can see, the narrative of this post goes from top to bottom and most recent things appear … at the bottom. Your focus naturally follows it. The same happens, when you read output of the program. Let's take a look at this:

/home/bob/tmp/demo.js:10
  notDefined();
  ^

ReferenceError: notDefined is not defined
    at thirdFunction (/home/bob/tmp/demo.js:10:3)
    at secondFunction (/home/bob/tmp/demo.js:6:3)
    at firstFunction (/home/bob/tmp/demo.js:2:3)
    at Object.<anonymous> (/home/bob/tmp/demo.js:13:1)
    at Module._compile (node:internal/modules/cjs/loader:1565:14)
    at Object..js (node:internal/modules/cjs/loader:1708:10)
    at Module.load (node:internal/modules/cjs/loader:1318:32)
    at Function._load (node:internal/modules/cjs/loader:1128:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)

The recency and relevance of the information drops rapidly with every new line. Which is kind of the opposite of the reading flow direction we were discussing a couple of sentences ago. Surprisingly, most of the mainstream languages (except maybe Python) do this. From usability standpoint it doesn't make much sense: when program finished printing the trace, I have to scroll up to get to the most interesting stack frames. In this tiny example it may not seem that critical, but in real world scenarios stack traces can become beefy very quickly, so it will become a pain in the back. And last but not least: this order of frames is important for making a debugger, but we will cover it closer to the end of the post.

Are there any cases, when it makes sense to print it upside down? Yes. Will I tell you about them? No.

Okay, we covered the printing direction, now let's talk about the content. To represent the state of the stack we need to communicate a lot of information: function names, values of arguments, frame numbers, local variables, corresponding source code location. Presenting it to the developer in a meaningful way is an impossible challenge: it will be always a tradeoff between comprehensibility and readability.

Yes, there is no universal solution here: you either provide too much and it becomes noisy incomprehensible mess or not enough and dear stack trace reader can't do a thing with it. And here we come to a very important point: I want to do a thing with it and don't want to be flooded with wall of text at the same time.

Let's take a look at almost good stack trace and explore this exact problem. One small note here, for function calls it uses a slightly special notation (function-name arg1 arg2) instead of more usual function_name(arg1, arg2), be aware.

In ice-9/boot-9.scm:
  1755:12 11 (with-exception-handler _ _ #:unwind? _ # _)
In unknown file:
          10 (apply-smob/0 #<thunk 7f46684f4300>)
In ice-9/boot-9.scm:
    724:2  9 (call-with-prompt _ _ #<procedure default-prompt-handle…>)
In ice-9/eval.scm:
    619:8  8 (_ #(#(#<directory (guile-user) 7f46684f7c80>)))
In ice-9/command-line.scm:
   185:19  7 (_ #<input: custom-port 7f46684f1850>)
In unknown file:
           6 (eval (begin (use-modules (ares suitbl)) (#)) #<directo…>)
In ares/suitbl.scm:
    499:6  5 (test-runner _)
   264:31  4 (_ ((type . print-test-suite) (test-suite #<proced…> …)))
In ice-9/boot-9.scm:
   260:13  3 (for-each #<procedure 7f465be50c60 at ares/suitbl.scm:…> …)
In ares/suitbl.scm:
   325:13  2 (test-reporter-hierarchy ((type . print-test-suite) (…)))
    291:2  1 (tests->pretty-string #f)
In ice-9/boot-9.scm:
    218:9  0 (map #<procedure 7f465bbab160 at ares/suitbl.scm:292:3…> …)

ice-9/boot-9.scm:218:9: In procedure map:
In procedure map: Not a list: #f

First of all, it's printed from the beginning to the end, the most recent and relevant calls are at the bottom of the output, just above the problem message, and this is already a huge improvement over the initial example. The ordering will matter even more for debugger: when you jump from break point to break point the first part of the stack remains the same and only the tail changes and this order allows to easily redraw the tail.

Second of all, I can see arguments to the function. Here #f means False, #<procedure ...> is an object of type procedure and ((type . print-test-suite) (test-suite #<proced…> …)) is a list of two pairs: type to print-test-suite and test-suite to the list of procedures (you probably noticed omitted dot and missing parenthesis, yeah). Not the most convenient notation, but at least the arguments are here.

If you stare at this stack trace long enough, you can even understand (to some degree) what was happening before we got into troubles.

BTW, do you find it a bit noisy? Those file names, line and column numbers — visual clutter I don't care about. Yes, I would like to jump to the source code and look around, but we can do so without clogging the output. Let's go back for a moment and try to debug our problem.

From the exception message I can guess that we passed #f instead of a list to the map function. And here is the first issue: we are lucky to have useful exception message, but we don't see arguments passed to the map in the stack trace, because they were truncated to fit the terminal width.

We still can guess that the root cause is somewhere earlier because tests->pretty-string also got #f as an argument. The problem may be in the test-reporter-hierarchy function, and again, we can't see arguments passed to it, moreover, we don't see local variables. Thus it's unclear why tests->pretty-string got called with #f, so we are basically stuck and can't proceed our investigation using only the stack trace.

We try to make stack trace useful — it gets overcrowded, we try to make it readable — it becomes lacking. Are we doomed and can't do anything about it? No. The primary problem is that we try to fit everything into the text representation, but computers are much more than just text printing machines.

I will skip the part where we discuss obvious solution: to make stack trace ultimately informative and create a special tool, which parses it and provides a rich interactive GUI/TUI. Instead, we can go straight and store a structured data about stack frames in a format more suitable than the plain text and continue the discussion from here.

Okay, imagine, we discarded the text-only representation, now let's make a slick interactive UI. That means, while we still store all auxiliary information, we don't need to make it visible to the readers and flood their brain with it.

(test-runner ((type . run-scheduled-tests)))
(loop (#<procedure test-reporter-hierarchy (message)>))
(for-each #<procedure 7fd42192d3a0 at ./ares/suitbl.scm:257:14 (r)> _)
(test-reporter-hierarchy ((type . print-test-suite) (test-suite . (simple-test))))
(prettify-list #f)
(map _ #f)

Origin: "map"
Not a list: #f

This is much cleaner version of the previous stack trace. The click on the function name leads to the source code location, where this function gets called. I can use keybindings to jump back and forth between stack frames and now can easily understand the flow of the code. We've reduced feedback loop (the time from seeing a stack trace and finding a place of potential failure) from seconds and minutes to fractions of a second. No hassle, no guessing, just pure usability.

It's not a theoretical reasoning, my very smart and diligent intern Noé and I already implemented it in Ares/Arei IDE and this is a video of how it works: the video.

The tool has already saved me hours of my life and I enjoy every moment I spend with it. And yes, it has some room for improvement, so let's quickly go through the things around the corner:

Value Inspector :: instead of using a text representation for highly nested data structures, we can just put a clickable link that will bring up a value inspector.
Local Variables :: when we jump from frame to frame, it would be cool to see the lexical scope of the function in that stack frame.
Code Evaluation :: evaluating code in the context of exception is a sick functionality, almost a miracle, but you won't believe it's possible anyway. When we get it implemented, this "just a stack viewer" will turn into the most powerful debugging machine known to human race, hehe.

Ares/Arei Guile Scheme IDE is a Free and Open Source Software, so feel free to play around, study, improve or whatever you want to do with it.

TLDR and my recommendation: if you have to make text-only stack traces, provide as much information as possible and sacrifice readability: it's easy to filter out the noise, but extremely hard to get the needed info when data is missing. If you have access to computers not only through a teletype console, just provide a nice interactive UI and make your stack traces readable, actionable and actually useful.

No JS, No BS Ethical Web Analytics

2025-05-31T12:00:00Z

I had two goals: to count AI crawlers DDoSing my nginx infrastructure and to see if anybody reads at least one of my three posts in the blog. To achieve both, I needed to gather data and transform it into meaningful insights, so basically I needed web analytics.

I don't think I need to explain why I wanted an ethical solution. If you are here, you likely have your own reasons. If you follow my work, you might also have some clues, but of course, you can always ask me for more.

In addition to ethical reasons, there are at least three more technical issues with convenient JS-based analytics.

The setup is complicated: deploying a database and backend, injecting js into every response, maintaining all of that.
JS won't count people with ad-blockers, NoScript, or RSS, and I bet most of my readers use at least one of them.
It won't count crawlers and bots that have limited or absent js evaluators.

Yes, without JS I won't be able to track the eye movement and body temperature of the reader.

The funny part is that I already have a lot of data for analytics in a web server's access.log. It's quite surprising how much useful information we can extract from it; we just need to provide a cute representation for the extracted info.

Luckily, there is a GoAccess project, which does exactly that. I could stop right here, and this post would already be useful, but I'll try to save you a few more hours of your life by covering its rough edges and sharing my tricks and findings.

A three-sentence introduction to GoAccess: it takes an arbitrary log file and generates an HTML dashboard with panels having various beautiful plots and tables (try demo or search for goaccess screenshots). You can adjust its behavior with CLI options and persist them in a configuration file. The rest is done by tweaking ({grep,awk,sed}-ing) a log file.

cat ./access.log | goaccess - --config-file ./goaccess.conf

We already have a lot in the default nginx's log file: timings, referers, requests, user agents; however, one thing is missing. I have multiple domains served by my nginx server, and to distinguish requests to different hosts I enriched my nginx's log file with '$host:$server_port ' by setting log_format:

log_format vcombined '$host:$server_port '
        '$remote_addr $remote_user [$time_local] '
        '"$request" $status $body_bytes_sent '
        '"$http_referer" '
        '"$http_user_agent"';

access_log access.log vcombined;

The sample log entry below is from my click on the blog link (I adjusted indentation to mimic newlines from the configuration above, but in a real log, it's one line).

trop.in:443
171.225.184.136 - [31/May/2025:05:52:48 +0200]
"GET /blog HTTP/1.1" 200 1411
"https://trop.in/blog/modern-writers-block-or-how-to-blog"
"Mozilla/5.0 (X11; Linux x86_64; rv:136.0) Gecko/20100101 Firefox/136.0"

It's clear that to get to the blog page, I clicked the link in Modern Writer's Block post and was using trop.in host and https port.

Now I can grep the log file by host[s] and select data for domains or sites I'm interested in. To parse the updated log file format, I added --log-format=vcombined to goaccess. I'll show a complete configuration at the end.

Also, I was curious about how many people read a particular page from Yggdrasil Network and how many from the Clearnet, so I added host:port into "$request" to the beginning of the URI with awk '$7=$1$7' access.log, so the resulting log entry looks like:

trop.in:443
171.225.184.136 - [31/May/2025:05:52:48 +0200]
"GET trop.in:443/blog HTTP/1.1" 200 1411
"https://trop.in/blog/modern-writers-block-or-how-to-blog"
"Mozilla/5.0 (X11; Linux x86_64; rv:136.0) Gecko/20100101 Firefox/136.0"

Thanks to this modification, I can build a separate report where I have two distinct entries trop.in:443/blog and ygg.trop.in:80/blog instead of one /blog. I don't use this report often, but I satisfied my curiosity.

After that, I realized that I rarely need information about all the hosts at once in the reports, so I decided to create a separate log for each server context.

access-in-trop-files.log
access-in-trop-genenetwork.log
access-in-trop-guix-ci.log
access-in-trop.log
access-local.log
access-wildcard.log

Logs for related hosts like ci.guix.trop.in and ci.guix.ygg.trop.in are grouped in access-in-trop-guix-ci.log, for trop.in and ygg.trop.in in access-in-trop.log, and the rest goes to wildcard.

Let's talk about the world map view. To understand the geography of readers and the ISPs of bots, I wanted Geo Location and ASN panels. To make them work, you need geodatabase files with IP to location and ASN mappings. I searched the internet for both GeoLite2-City.mmdb and GeoLite2-ASN.mmdb files, downloaded them to the server and added to the goaccess's configuration.

The last tweak is somewhat naughty, but I wanted real-time analytics, and there is a built-in option for it: goaccess can spawn a WebSocket to constantly update data for the dashboard. Of course, I don't want to expose it to the whole internet, so I made it listen only on localhost.

--real-time-html --host=localhost --port=17001

Now I need to expose both generated HTML and WebSocket to my laptop to conveniently access it. For this, I made a local server context in nginx config:

server {
  listen localhost:80;

  access_log "logs/access-local.log" vcombined;
  location /websocket/goaccess/in-trop {
    proxy_pass http://localhost:17001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
  location / {
    root /srv/nginx/local;
    autoindex on;
  }
}

and provided an access to it for my laptop on http://localhost:8880 through an SSH tunnel.

ssh -N -L localhost:8880:localhost:80 pinky-ygg

That's the whole setup, now it's time to run goaccess and enjoy the view. Here is a report I use for analytics on my primary site. The report focuses on my flesh-and-blood readers, so I excluded Unknown and Crawlers user agents.

goaccess \
/var/run/nginx/logs/access-in-trop.log --log-format=vcombined \
-o /srv/nginx/local/analytics/trop.in.html \
--real-time-html --port=17001 --host=localhost \
--ws-url=localhost:8880/websocket/goaccess/trop.in \
--geoip-database=GeoLite2-ASN.mmdb --geoip-database=GeoLite2-City.mmdb \
--unknowns-as-crawlers --ignore-crawlers \
--enable-panel=REFERRERS

Also, I have a bot-fighting report and am still playing with parameters, but I already know where they come from, at what time, and what they are looking for. That means, I accomplished both goals: I counted evil crawlers and nicest hoomans.

One missing feature is the ability to splice and filter the data in runtime. I'd like to have an overview for an adjustable time frame and to filter out requests by regex interactively. However, from goaccess and the web server log, I already get more insights than I wished for—and much more than I could get from "convenient" web analytics.

Have any thoughts or comments? Publish them on Fediverse and reference me or publish them somewhere else on the internet and send me a link.

Modern Writer's Block or How to Blog

2025-05-23T12:00:00Z

Through the course of a couple of decades I've been online, I tried to run my blog multiple times, used different blogging engines from blogspot.com to self-hosted SSGs (Jekyll, Hugo, etc) and failed miserably in all attempts except two. For the last 7.5 years I published around 1000 small-to-medium-sized good-quality original posts, and this is a recap of what I learned from this journey and how I would do it in the future.

The further the publish button is, the harder it is to … publish. It's always tempting for me to tweak CSS, URL scheme, post layout, RSS/ActivityPub integrations, and that makes me further from writing and publishing. I've read this idea multiple times in other people's blogs and always thought that I'm beyond that and it wouldn't stop me from posting, but I was wrong.

My most productive blogging setup turned out to be a Telegram channel. It had subscribe functionality, basic markup, a number of views under the published post and a publish button - that's it. No analytics, no comments, no integrations, nothing. I could just write down the thought, maybe highlight a couple words with bold/italic and press the send button.

What? pro-FOSS person blogging on Telegram? Yes. Do I have reasons for it? Absolutely, and you can ask me about them. Do I recommend you to do so? No. Will I continue to blog on it? Probably no. The most important thing that you can take from it is that: to become consistent in blogging I needed a good enough publish button and a place, where people can sanely read what I've published.

Feedback is important; comments are overrated. I could get far on my initial motivation, but if I didn't see people read my stuff I would stop writing before I make a writing habit. Thus seeing the growing number of views is already huge, and getting questions, constructive critique and kind words is enormous.

Fun fact: I don't need the comments functionality for it. People can discuss my posts in other corners of the internet (and sometimes I'm not even aware of those discussions, which is totally ok). People find the way to contact me directly or send the feedback to my inbox. Moreover, implementing a good comment system in the blog is really hard.

It's easier to write regularly. When I skip writing a post for a couple of weeks, it's hard to come back to writing the next one, however, when I publish consistently I always get more ideas than I can write down.

Better good enough than nothing. We can learn and grow only when we have enough practice, and it's inevitable that we make imperfect things during it. So I came up with a throw-away mindset: start writing a text that you will discard, then improve this text until it becomes good enough. Publish it, profit! I apply a similar principle for tasks and projects, which feels hard and daunting and it usually produces impressively good results.

As you can tell, I already spent some time over-engineering the blog setup, but this time I stopped at a good enough state: I have a decent CSS, RSS/Atom feed, minimal analytics and a publish "button" nearby. In addition to that, I have a writing habit and skills under my belt and better understanding of what is essential and what is secondary. And of course the most important thing: I published this post.

Continuations Brief Summary

2023-06-09T12:00:00Z

Introduction

Continuations are quite flexible and powerful mechanism and can be used in a good number of different scenarios: early return, proper tail-recursion, generators, exception handling, coroutines, multiple return values, etc.

It's a GOTO in the world of functional programming: they give a power to control the flow of execution, but feels much more high level, more involved and require time to understand.

Continuations were first discovered in 1964 and later rediscovered a few times in different settings by different people. They are first-class citizens and a part of Scheme Language and appears one way or another here and there. It make sense to learn this concept to get a better understanding of Scheme Language and its ecosystem and this article is a brief sum up on the topic.

Continuations

An expression's continuation is "the computation that will receive the result of that expression". Also, it can be perceived as a checkpoint or quick-save, where you can come back later.

(+ 4 (+ 1 2))

The continuation of the expression (+ 1 2) will be something that adds 4 to the value, like (lambda (x) (+ 4 x)) would do, BUT! continuation is not a function, it doesn't return a value. When resumed (called), it jumps to the place, where it was captured and continue the execution of the program from that point and never jumps back. Let's rewrite the example above, but storing continuation in the variable.

(define kont)
(+ 4 (call/cc (lambda (k) (set! kont k) (k (+ 1 2))))) ; (+ 4 (+ 1 2))

kont ;; => #<continuation 7f7a1cc269c0>

Contiunations implicitly exist everywhere, but to get it we need to capture it with call/cc and store it somewhere (with set! for example). The call/cc is a shorthand for call-with-current-continuation. Now we can use the value of kont and resume a continuation in a similiar way as we call one-argument functions (by passing one argument to it, which will be used in place of (call/cc ...)):

(kont 6) ;; => 10

However, the big difference here is that continuations change the flow of the execution and doesn't return (as functions do) and thus can't be composed.

(kont (kont 6)) ;; => 10

If kont was a function it would return 16 in the example above, but the continuations are NOT functions. To demonstrate it better, let's add a few side effects, which print strings.

(begin
 (display "hi\n")
 (+ 4 (call/cc (lambda (k) (set! kont k) (k (+ 1 2)))))
 (display "hello\n")
 5)

After evaluation of this expression hi and hello will be printed and return value of the whole expression will be 5, however when we resume continuation (kont 10) only hello will be printed and return value will be 5 again.

While [undelimited] continuations provide a lot of flexibility and power, the programs written with them are hard to reason about, the perfomance and memory usage can be suboptimal, the continuations themselves are not composable, and better, more generalized alternatives exist. Read more about potential problems in An argument against call/cc.

The simple code snippets above should give a basic understanding of continuations, but more advanced examples available in wikipedia article, Functional Programming in Scheme relevant chapter and The call/cc Yin-Yang Puzzle.

Continuation-Passing Style

The style of programming in which the execution flow is controlled explicitly through continuations passed as function argument. The analogy of callbacks is floating somewhere around. Let's write a simple (* 3 (+ 1 2)) expression in CPS:

(define return)
(display (call/cc (lambda (k) (set! return k) (k "hi"))))
;; You can think about it somehow like this:
;; (define return (lambda (x) (display x) (exit))

(define (+& a b k)
  (k (+ a b)))

(define (*& a b k)
  (k (* a b)))

(+& 1 2 (lambda (x) (*& x 3 return))) ;; prints 9

There are more examples comparing the direct and continuation-passing styles. In CPS some things, which were implicit in direct style become explicit (returning a value for example), but the code becomes somewhat turned inside-out, more verbose and harder to reason about, so this style of programming is quite uncommon among developers, however it can be useful for some use case (representing intermediate compilation targets, programming language researches, etc).

Delimited Continuations

Delimited continuation (aka prompt) is a generalization of continuation, instead of capturing the context up to the beginning of expression, it captures the context only up to delimiter, also, it returns a value and can be composed in contrast to usual one.

(use-modules (ice-9 control)) ;; for reset and shift

(define kont)
(* 2 (reset (+ 1 (shift k (set! kont k) (k 5))))) ;; => 12
kont ;; => #<procedure 7f29fdf05040 at <unknown port>:64:17 vals>
(kont 3) ;; => 4
(kont (kont 3)) ;; => 5

;; Example with side effects
(* 2 (reset
      (begin
        (display "hi\n")
        (let ((r (+ 1 (shift k (set! kont k) (k 5)))))
          (display "hello\n")
          r)))) ;; => 12 ; prints hi hello

(kont 3) ;; => 4 ; prints hello
(kont (kont 3)) ;; => 5 ; prints hello two times

It's clear from example that (* 2 <>) is not captured as a part of continuation and delimited continuation are functions, can be used as such and thus can be composed. There are different names and interfaces in different languages, even Guile Scheme in addition to shift and reset has call-with-prompt and friends.

Dynamic Wind and Continuation Barriers

There are two mechanism, which are tightly related to non-local enters, exits and reenters. Dynamic Wind allows to trigger actions on [re-]enter and exits, it can be useful for setting up or cleaning up resources and maybe some other use cases.

(* 2 (reset (+ 1
               (dynamic-wind
                 (lambda () (display "entered\n")) ; on-enter hook
                 (lambda () (shift k (set! kont k) (k 5)))
                 (lambda () (display "exited\n")))))) ; on-exit hook
;; => 12, prints entered exited two times because we call k in shift

(kont 3) ;; => 4, prints entered exited

Continuation Barriers prevents non-local enters and exits by erecting the fence, impassable for continuations.

(with-continuation-barrier
 (lambda ()
   (define tmp #t)
   (display (+ 1 (call/cc (lambda (k) (set! kont k) 3))))
   (when tmp
     (set! tmp #f)
     (kont 6)))) ;; prints 4 7

;; In procedure %continuation-call: invoking continuation would cross continuation
;; barrier: #<continuation 171 @ 7faffed6d800>
(kont 3)

It only applies to non-local enters and exits, which tries to cross the barier, if they jump around inside barier they are good and will work without problems.

Conclusion

It's good and sometimes necessary to know about call/cc to better understand how things works in Scheme in particular and in programming in general, however it usually should not be used in production code. The first-class support for it is a controversial design decision, but it's already a part of Scheme, so let's just embrace it.

Delimited continuations are a generalization and overall a better alternative to undelimited continuations, however they should be used with a great care as well.

The good entry point for in-depth materials on the topic are on Oleg Kiselyov's site. More links and examples in Andrew Tropin's personal notes.

Acknowledgments. Thanks to all the great Computer Scientists, Engineers and Writers, who bring the light of knowledge and such power.

Scheme Static Site Generators Review

2023-05-23T12:00:00Z

Introduction

Static site generator is a program, which accepts text files as input and produces static web pages as output. It can be useful in various scenarios: for building blog, book, documentation, project or personal page for example.

There are a few SSGs written in Scheme available in the wild, namely Haunt, Skribilo and Hyde and two more for Racket: Pollen and Frog, which are outside of Guile ecosystem, but still quite close and can be taken as a source of inspiration.

Hyde doesn't seem to be maintained, but the source code still available and even an attempt to go further/reincarnate the project exists.

Skribilo is documentation production toolkit and capable of much more and provides a lot of functionality outside of SSG scope, so we don't cover it in this writing.

Basically we have only one option left at the moment: Haunt and the further discussion will be related to it, but before exploring it, we need to get to common ground and cover the topic of different markup languages.

Markup Languages

Markup languages are used for defining documentation structure, formatting, and relationship between its parts. They play an important role in SSGs, different languages can suite better for different tasks: simple and expressive for human convenience, powerful and capable for intermediate representation and manipulation, compatible and wide-spread for distribution.

SGML, XML, HTML, XHTML

This is a probably most widespread family of markup languages, currently used all over the web. Not always, but usually SSGs create HTML or XHTML documents as an output. Also, it is good to know the relationship between those languages to understand some technical issues we will face later.

SGML (Standard Generalized Markup Language) appeared in 1986 and highly influenced HTML and XML.

XML (Extensible Markup Language) is a meta language, which allows to create new languages (like XHTML), originially developed as a simplification of SGML with rigid and not open for confusion syntax, it's defined in the SGML Doctype language. Often used for representing and exchange data.

HTML is a more user friendly markup language, it's defined in plain english, has more forgiving parsers and interpreters, allows things like uppercased tags, tags without matching closing tag. Such flexibilities can be convenient for users, but it makes it harder to programmaticaly operate on it (parse, process and serialize).

XHTML (XML serialization of HTML) is a version of HTML, which is compliant with an XML grammar. XHTML can be used with XML parsers, tools for querying, transformation should work as well.

While both HTML and XML are influenced by SGML, there is no direct relationship between them and tools for XML can't be used for HTML in general case.

Lightweight Markup Languages

This is another family of markup languages, which are simpler, less verbose, and more human-oriented in general. The notable members are Wiki, Markdown, Org-mode, reStructuredText, BBCode, AsciiDoc.

Often SSGs use those languages for representing the content of pages, posts, etc. Later it is combined with other parts and templates and final output is produced, usually in the form of (X)HTML documents.

Other Markup Languages

There are a number of languages and typesetting systems, which are not covered by the previous two sections: Texinfo, LaTeX, Skribe, Hiccup, SXML. The goals for them can be different: preparing hardcopies, use as an intermediate format, or better suitability for specific needs like writing documentation.

Haunt Overview

Haunt is a simple and hackable SSG written in Scheme, it tries to apply functional programming ideas and the usual approach for building a site with it: prepare SXML page templates, read the content from HTML, Markdown or any other markup files and convert it to SXML, insert the content into templates and serialize resulting pages to HTML. Let's discuss various parts of this process in more details.

SXML

SXML is a representation of XML using S-expressions: lists, symbols and strings, which can be less verbose than the original representation and much easier to work with in Scheme.

SXML is used as an intermediate format for pages and their parts in Haunt, which is relatively easy to process, manipulate and later serialize to target formats like XHTML. It can be crafted by creating s-expressions from Scheme code manually, or programmatically, or with a mix of both. It looks like this:

(define n 3)

(define slide-content
  (get-html-part "./slide3.html" "body>div.content"))

(define (sxml-slide n slide-content)
  `((h2 ,(format #f "Slide number: ~a" n))
    (div (@ (class "slide-content"))
         ,slide-content
         (p "the additional text of the slide"))))))

As it was mentioned in the introduction there is no direct relationship between XML and HTML, and while we usually can parse arbitrary HTML and convert it to SXML without losing significant information, we can't directly use XML parsers for that. For example this HTML is not valid XML:

<input type="checkbox" checked />

Luckily, we can present boolean attributes in full form as hidden="hidden", which is valid both in HTML^4 and XML.

Most lightweight markup languages as well as SSGs usually target HTML, but SSG needs to combine the content, templates and data from various sources and merge them together, so SXML looks like a solid choice for intermediate representation.

The Transformation Workflow

Each site page is built out of a series of subsequently applied trasformations. The transformation is basically a function, which accepts some metadata and data and returns another data (usually SXML) and sometimes additional metadata. Because this transformation is a pure function, a few transformations can be composed in one bigger transformation.

We will cover it in more details in the next section, but readers, templates, layouts, serializers, builders are all just transformations. For example the top level template, called layout just produces SXML for the final page, which can be serialized to the target format. To demonstrate the workflow we will take a bottom-up approach.

Let's take a simple Markdown file, where one wants to write the content of a blog post in human-friendly markup language and let's add metadata to the top of this file: title, publish date, tags.

title: Hello, CommonMark!
date: 2023-05-09 12:00
tags: markdown, commonmark
---

## This is a CommonMark post

CommonMark is a **strongly** defined, *highly* compatible
specification of Markdown. Learn more about CommomMark
[here](http://commonmark.org/).

It can be parsed into metadata (alist) + data (SXML).

=> ((tags "markdown" "commonmark")
    (date . #<date nanosecond: 12 day: 9 month: 5 year: 2023 zone-offset: 14400>)
    (title . "Hello, CommonMark!"))
=> ((h2 "This is a CommonMark post")
    (p "CommonMark is a " (strong "strongly") " defined, "
       (em "highly") " compatible" "\n"
       "specification of Markdown, learn more about CommomMark" "\n"
       (a (@ (href "http://commonmark.org/")) "here") "."))

Metadata+data representing one post is a good unit of operation. With one more transformation (it can be just a template, function adding html, head, body tags and a few more minor things) SSG can produce almost ready for serialization SXML. After deciding on the resulting file name and serialization step, the final HTML is produced.

Some additional transformations can be desirable. For example, substituting relative links to source markup files in the generated html files or something else, but overall it fits this general trasformation workflow well.

Let's zoom out a little and take a look at the directory structure, rather than a single file. Usually, SSGs operate on a number of files and in addition to simple pages can generate composite pages like a list of articles, rss feeds, etc. For this purpose our unit of operation become a list of data+metadata objects: instead of parsing one markup file, SSGs traverses the whole directory and generate a list of objects for future transformation. The overall idea is still the same, but instead many output files get produced from many input files. SSGs produces a list containing only a few or even one output file.

The Implementation

The Entry Point

The entry point in haunt is a site record, which can be created with a function that has the following docstring:

Create a new site object.  All arguments are optional:

TITLE: The name of the site
DOMAIN: The domain that will host the site
SCHEME: Either 'https' or 'http' ('https' by default)
POSTS-DIRECTORY: The directory where posts are found
FILE-FILTER: A predicate procedure that returns #f when a post file
should be ignored, and #f otherwise.  Emacs temp files are ignored by
default.
BUILD-DIRECTORY: The directory that generated pages are stored in
DEFAULT-METADATA: An alist of arbitrary default metadata for posts
whose keys are symbols
MAKE-SLUG: A procedure generating a file name slug from a post
READERS: A list of reader objects for processing posts
BUILDERS: A list of procedures for building pages from posts

The primary thing here is a list of builders. As previously mentioned, a builder is a special case of complex transformation, which does all the work of parsing, templating, generating collections, serialization, etc.

The rest of the list is basically metadata or auxiliary functions. While many of those values can be useful, almost none of them are needed in many cases. scheme and domain are used for rss/atom feeds, which are rare for personal or landing pages. Similiar logic is applicable to the rest of the function arguments, except for maybe build-directory, which almost always make sense.

Providing default values for them is convenient, but making them fields of site records incorporates unecessary assumptions about the nature of the blog and can negatively impact the rest of the implementation by adding unwanted coupling as well as reducing its composability. One of the options to avoid it is to make them values in the default-metadata rather than fields in the record.

Builders, Themes and Readers

Builders are functions, which accept site and posts, apply series of transformations and returns a list of artifacts. Themes and Readers are basically transformations used in the build process. Artifacts are records, which have artifact-writer field, containing a closure writing the actual output file. There are a number of different builders provided out of the box, but the most basic one (static-page) is missing, luckily it's not hard to implement it, so let's do it.

(define* (page-theme #:key (footer %default-footer))
  (theme
   #:layout
   (lambda (site title body)
     `((doctype "html")
       (head
        (meta (@ (charset "utf-8")))
        (title ,(string-append title " — " (site-title site))))
       (body
        (div (@ (class "container"))
             ,body
             ,footer))))
   #:post-template
   (lambda (post)
     `((div ,(post-sxml post))))))

(define* (static-page file destination
                      #:key
                      (theme (page-theme))
                      (reader commonmark-reader))
  "Return a builder procedure that reads FILE into SXML, adjusts it
according to the THEME and serialize to HTML and put it to
build-directory of the site.  DESTINATION is a relative resulting file
path."
  (lambda (site posts)
    (list
     (serialized-artifact
      destination
      (render-post theme site (read-post reader file '()))
      sxml->html))))

As described in a section about transformations, the series of transformations happens here:

read-post basically parses markdown and returns SXML + metadata.
render-post uses post-template from theme to produce SXML post body.
render-post uses layout from theme to produce SXML post body.
serialized-artifact creates a closure, which wraps sxml->html and will later serialize obtained SXML for the page to HTML.

The implementation using already existing APIs is quite easy, but unfortunately not perfect. While functions and records are composable enough to produce desired results, names are quite confusing and tightly related to blogs, but doesn't make much sense in the context of other site types.

Every builder always accepts a list of posts, which were read and transformed into sxml ahead of time. This transformation is implicit and again blog related, which makes the implementation less generic. It could be implemented in the blog builder, but this way other builders like atom-feed won't be able to reuse readed posts from from blog builder and would need to read them again. This is due to the fact, that the build process has three primary steps and looks like this:

;; 1. Prepare site and posts

;; 2. Build artifacts
(builder1 site posts) ;; => artifacts-1
(builder2 site posts) ;; => artifacts-2
(builder3 site posts) ;; => artifacts-3

;; 3. Produce actual site:
(serialize-artifacts
 (append artifacts-1 artifacts-2 artifacts-3))

It makes a build process rigid and makes it harder to compose procedures. The alternative more streamlined process could look like this:

(define readers (list ...))
;; threading macro passes the result of the form
;; as a first argument to the next form
(->
 (make-site ...) ;;=> ((site . <site-record>))
 (read-posts
  "posts/" readers) ;;=> ((posts . <list-of-posts>) (site . <site-record>))
 (static-page "index.md" "index.html") ;;=> ((artifacts <index-artifact>) ...)
 (blog-posts theme) ;;=> ((artifacts <post1-artifact> <index-artifact>) ...)
 (collection "main") ;;=> ((artifacts <coll-artifact> <post1-artifact> ...) ...)
 (atom) ;; takes value from posts and appends a few more artifacts
 (atom-by-tags)
 (serialize-artifacts!))

Just a series of transformations, which enriches one associative data structure. Moreover it makes the implementation of such transformations much more composable:

(define (read-posts o dir readers)
  (let* (;; (dir (site-posts-dir (assoc-ref x 'site))) ; could be
         (posts (map (read-with-readers readers) (files-in dir))))
    (alist-update o 'posts (lambda (x) (append x posts)))))

(define* (static-page o file destination
                      #:key
                      (reader commonmark-reader)
                      (page-layout default-page-layout))
  (let* ((sxml-body (get-sxml (reader from)))
         (sxml-page (page-layout sxml-body))
         (page (serialized-artifact destination sxml-page sxml->html)))
    (alist-update o 'artifacts (lambda (x) (append x (list page))))))

(define* (blog-posts o destination-dir
                     #:key
                     (page-layout default-page-layout)
                     (post-layout post-layout))
  "Implementation for the first posts here is to clearer demonstrate the
idea of reusability."
  (let* ((post (first (assoc-ref o 'posts)))
         (destination (string-append destination-dir (post-file post)))
         (sxml-content (get-sxml post))
         (sxml-body (post-layout from))
         (sxml-page (page-layout sxml-body))
         (page (serialized-artifact destination sxml-page sxml->html)))
    (alist-update o 'artifacts (lambda (x) (append x (list page))))))

(define* (collection o name
                     #:key
                     (filter-function identity)
                     (collection-generator default-collection-generator)
                     (page-layout default-page-layout))
  (let* ((posts (filter-function (assoc-ref o 'posts)))
         (file (string-append name ".html"))
         (sxml-body (collection-generator posts))
         (sxml-page (page-layout sxml-body))
         (collection (serialized-artifact file sxml-page sxml->html)))
    (alist-update o 'artifacts (lambda (x) (append x (list collection))))))

The naming of intermediate transformations is much more suitable (no notion of the post in static-page builder), the transformations are more atomic and it's easier to reuse them (page-layout and similiar) and there is no need to combine them into records like theme, it's easier to restructure complex transformations, for example there is an option to make a collection a part of blog builder or be a separate step as in example above, there is no need to special case read and serialize steps, the read step can skip posts, which are flagged as drafts or have some other advanced logic, now it's possible to build a page, which relies on the content of previous steps, for example a collection of generated rss/atom links.

However, such implementation has its own flaws: more flexibility and less rigid structure can lead to more user mistakes and a steeper learning curve. The original implementation could theoretically run builders in parallel, but one will need to implement it on the user or builder side.

Readers

As a component of the build process we encountered a step, where the file within the markup language is read by readers. There are two parts for it: reading metadata and reading actual content. Let's cover implementation details for them.

Metadata

As shown in the example code snippet in the section related to transformation, one can provide additional metadata in a simple key-value format delimited by --- from the content of the markup file. There are two main issues with the implementation, let's discuss them.

The metadata is required for built-in readers and even if one doesn't want to set any values, they have to add --- at the beginning of the file. This requirement is not needed and could be easily avoided.

The metadata reader simply accepts colon-delimited key-value pairs. It is potentially not be as flexible as yaml frontmatter. Metadata in such format usually is not a part of the markup grammar and that means files are written in an invalid markup. However, it's not a big deal, as readers can use custom metadata parsers.

Guile-Commonmark and Tree-Sitter

Guile-Commonmark is used in Haunt by default to parse markdown files in SXML, it doesn't support embedded html, tables, footnotes and comments, so it can be quite inconvenient for many use cases. It somehow works and serves basic needs and more advanced use cases can be potentially implemented with more feature full libraries like a hypothetical guile-ts-markdown (tree-sitter based markdown parser).

Conclusion

Haunt is the primary player in the Scheme static site generators arena at the moment of this writing. It gives all the basics to get up and running. The number of available learning resources in the wild are much smaller than for similiar solutions from other languages ecosystems, but provided documentation and source code is enough for a seasoned schemer to start with. Exploring the whole project is just a matter of hours, this is not possible with codebase of hugo or jekyll.

The functionality can be lacking in some cases, but due to the hackable nature of the project, it is possible to gradually build upon the basics and as well as any future needs. Unfortunately, the current state of the Scheme ecosystem and Guile in particular feels behind more mainstream languages, but hopefully the popularity of Guile will reach a higher level and the ecosystem will start growing in the nearest future.

Future Work

There are a number of improvement points for Haunt in particular, and Guile Scheme in general. We need more complete tooling for working with markup languages like org, md, html, yaml, etc. As a generic solution, tree-sitter seems like a good candidate to quickly cover this huge area.

More streamlined and composable build processes for Haunt as described in the Builders section could add to haunt's flexibility in general as well as encouraging the use of reusable components.

Possible integrations with other tools like Guix, REPL, Emacs for easier deployment, better caching, more interactive development and other goodies.

More documentation, materials and tools for possible workflows and use cases from citation capabilites and automatic url resolution to on-huge-file workflows and org-roam integration.

Acknowledgments. Kudos to David Thompson for making Haunt, Erik Edrosa for making guile-commonmark and jgart for extensive and careful editing of the post.

trop.in

Pay for Software That Respects You

My list

Operating systems

Content and Social Networks

Conclusion

Context Makes Tests Reusable

Context Makes Tests Reusable

Original Design and Syntax

Dynamically Scoped Variables

The Inconvinience of Original Design

The Solution

Contextual Awareness

Excessive Uncoupling

The Synergetic Power Of Friendship

Conclusion

Support

Future work

Appendix

Complete example

Quick Review of "Nix Flakes and their Guix Equivalents"

Table of Content

"2. What even is a flake, anyway?"

"3 Declaring dependencies: inputs vs. channels"

"4. Pinning dependencies: flake.lock vs. guix describe"

"5. Purity: enforced isolation"

"6-8"

"9. So what does Guix NOT have?"

10. And what does Guix have that flakes don't?

Conclusion

Support

A Sane Directory Structure for Software Projects

Introduction

Modules

Module-Path Correspondence

Namespace (Module) Naming Rules

Never Top-level Sidefectful Expressions

Language Subdirectories (Not Really)

Top-level Project Directories

How to Set Up Guile Load Path

Introduction

Getting the Load Paths

Getting a Clean Environment

Setting GUILE_LOAD_PATH

The Order Matters

Adding to GUILE_LOAD_PATH

Modifying via CLI

-L Has Priority Over GUILE_LOAD_PATH

Modifying via API

Clean Up

Acknowledgments

I Have to Live in a Forest to Work on Open Source

The Corporate Work

New University and Startups

The Dark Times

The Alps

Grown-Up Start-Up

Burning and Saving

Vacations and the Start of Open Source Journey

The War

Running Out of Money

Donations and Trip to Turkey

UAE to Save Money

Hiding in the Forest

Surviving

I Crashed on the Road Bike at 50km/h, and I ...

Struggles, Ilness, Anexiety

The Crash

Actually Useful Stack Traces

No JS, No BS Ethical Web Analytics

Modern Writer's Block or How to Blog

Continuations Brief Summary

Introduction

Continuations

Continuation-Passing Style

Delimited Continuations

Dynamic Wind and Continuation Barriers

Conclusion

Scheme Static Site Generators Review

Introduction

Setting `GUILE_LOAD_PATH`

Adding to `GUILE_LOAD_PATH`

`-L` Has Priority Over `GUILE_LOAD_PATH`