Forem: Vehbi Sinan Tunalioglu

I Blogged Every Day for a Month -- Again

Vehbi Sinan Tunalioglu — Sat, 31 May 2025 14:54:49 +0000

Today marks the final day of my second month-long blogging challenge. The first was in August last year. This one, in May, felt different -- but just as transformative.

Here are my takeaways.

The grind is real -- and it teaches you

I have a few jobs to do, with different hats to wear. I also have a family. So, blogging almost always happened late in the evenings.

Some evenings I had not even thought about what to write until 9pm-10pm. Then I had to find a topic, write, and publish. It was stressful and felt like a grind. But this taught me something important: grind is everywhere.

If you are a marketer, you grind to get leads. If you are a developer, you grind to fix bugs and run chores for housekeeping. The examples may change, but the grind stays.

If your job never feels like a grind, maybe you are lucky. But maybe not. Grind, in some form, is inevitable. The real question is -- how do you face it without burning out or dropping the ball?

I wanted to quit around Day 15

I distinctly remember telling myself: "Enough. This is too stressful." But I kept going. It was doable -- and I am glad I resisted the urge to quit.

Streaks help with accountability

There is something motivating about not breaking the chain. It is visual, tangible and slightly addictive in a way, and I hope it is in a good way.

Constraints trigger creativity

Do not get me wrong -- I am not claiming to be a creative person.

But a daily deadline forces you to think faster, write leaner, and sometimes take unusual angles. That is a good thing. Constraints are not limits -- they are frameworks.

More about constraints in a future post!

It is possible to write a blog post in less than 2 hours

It depends on the topic, the depth, and how prepared I am. My motivation was twofold:

The key is to just start.
Not every post needs to be perfect, long or deep.

And it worked for me. I wrote some posts in under an hour, and mostly in less than two.

Quantity over quality

That perfectionism kept me from blogging for the longest time. The August exercise helped me to overcome that. I was told that "quantity leads to quality". That might sound counterintuitive, but it is true.

As an old drummer, I can tell that the more you practice, and the more grinding the practice is, the better you get.

Why should writing be any different?

My motto was: just hit publish. Not everything needs to be perfect. So, I learned that letting go is a skill that needs to be practiced too.

Writing helps me learn

Often, I catch myself saying, "Wait, is that even true?" It made me go and verify lots of things this month.

I suppose that this is normal: writing requires clarity and clarity requires learning.

Crossposting revealed what people actually read

I post to dev.to and Hashnode. Over time, I am starting to understand which posts resonate and which do not.

I also have a clearer sense of what I enjoy writing about.

I now have a content archive

A month of blog posts is not just a streak -- it is a body of work, regardless of quality. I can build on these or turn them into something more later.

I showed up for myself

In the end, this challenge was a commitment to myself. I kept that promise. That builds confidence and internal trust -- something no metric can measure.

What next?

After my first challenge, I told myself that I should write occasionally, which I did not. That was a mistake.

Now, I should really try to keep the momentum going.

Thinking of trying your own challenge? Start small. You might just learn more than you expect.

Daily Z Reports and Weekly Reviews

Vehbi Sinan Tunalioglu — Fri, 30 May 2025 16:53:33 +0000

This is not about improving productivity, but rather a simple but bottom-up hack to improve personal awareness and accountability and extend it to the team. Productivity should be a natural byproduct of that.

It is important how we plan, but more important is how we execute and adapt to the ever-changing environment.

Any plan without operational touch is just a wish list. Any day full of doing but lacking clear direction is just another wasted one.

Which one follows which? It is a chicken-and-egg situation.

The Z Report

A long time ago, my business partner took a month off. Not that he asked for it, but I sent him an email every single day with a list of things I did or that came up during the day.

Forget the value of the list for the business or even for him -- what I learned was that I had been floating through the day.

Once I started documenting the day, I realised how easy it is to derail and do the wrong things. Ask me in the evening -- I worked all day. But what did I actually deliver? Nothing. I recently learned that it even has a name: motion versus action.

In point-of-sale systems, a Z Report is the summary that closes the register at the end of the day. For me, it became my personal audit log -- a simple way to close the day with awareness.

A good Z Report is not just a list of tasks. It is a reflection. A checkpoint. A mirror. It should not be complex or long, but it should be honest and clear. No need for elaborate tooling. Just a log -- something to end the day with a sense of clarity.

This is how I managed to do it for a very long time without giving up.

The Weekly Review

At the end of 2022, I automated the habit. A GitHub Action would open a "Daily Review" issue for me every day -- seven days a week -- with a template that changes over time. I only skipped one day! Around the same time, another GitHub Action would create a "Weekly Review and Plan" issue every Sunday.

The intent was not to project-manage myself or my team. The goal was simpler: to X-ray the week. To observe patterns. To reveal where we thought we were going and where we actually landed.

The first thing I noticed: the weekly plans were too ambitious. And the daily routines were too scattered. Toning down the weekly goals and dropping unimportant chores helped immediately. Energy and focus are finite. The Weekly Review made that painfully obvious.

Eventually, I extended the practice to the team. Each member had their own version of the daily issue. It was never mandatory. Whether written or not, the daily report helped everyone realise what was being left undone.

I do not claim this made us a more productive team. But it made us a wiser team -- one more aware of its own limitations and dynamics.

We are now extending this practice to monthly and quarterly tasks and reviews, and integrating our compliance and audit practices into the same routine.

Reflection as Operational Practice

Together, Z Reports and Weekly Reviews form a valuable feedback loop:

Z Reports help you close the day with clarity.
Weekly Reviews let you step back and adjust direction.

After years of doing this, I have a better idea of where my time goes, what I keep postponing, why I fail to ship and what strategies fail to fix these.

I think that it is a pretty good return on investment for a 10-minute daily review and a 30-minute weekly reflection.

Close the Register, Open the Week

I do not claim that I have found the perfect productivity system. There are so many tools, methodologies and frameworks out there, some of which I have tried and many I have not. I am also aware that tools change as we change, our environment changes and our needs change, temporarily or permanently.

What I do claim, however, is that self-awareness, accountability and persistence are the keys to improving your own productivity and that of your team. As tools need to change, you do not need to change the overarching principles and practices: You will still need to close the day with a Z Report and you will still need to review the week and plan the next one.

That is the lifehack.

Cross-Compiling Haskell under NixOS with Docker

Vehbi Sinan Tunalioglu — Thu, 29 May 2025 18:37:09 +0000

I learned how to cross-compile Haskell projects under NixOS using Docker images for ARM architectures, and how to run them under emulation on x86_64 hosts.

Motivation

I attended the AWS Summit 2025 in Singapore. I enjoyed the event. There were booths from various companies which I found interesting, such as GitLab and ClickHouse. More importantly, I got to meet very interesting people.

Among the booths, there was a particular one that caught my attention: AWS was showcasing their ARM-based Graviton processors. I chatted with the AWS folks, and asked a few questions which I had in mind for quite some time.

I compiled a few of my Haskell projects on my Raspberry Pi 4, which is based on the ARM architecture. I was curious to see how some others would perform on the Graviton processors. I could go and compile them on the Graviton processors, on my Raspberry Pi 4, or rather cross-compile them on my x86_64 workstation.

Cross-Compiling Haskell Projects

Cross-compiling Haskell projects always seemed intimidating to me. I do not know if it is practically possible, either. Even statically linking Haskell binaries is quite a challenge, especially under Nix. Instead, I am currently statically compiling my Haskell projects under a Docker image that is built and published by benz0li:

https://github.com/benz0li/ghc-musl

I am using a script that generates a cabal.project.freeze from my Nix setup, compiles the project inside a Docker container from the above image, copies the binary to the host, and then compresses it using upx.

You can check the script under my Haskell project template repository.

I knew that benz0li publishes the Docker images for both x86_64 and arm64 architectures. He has even recently published additional images to deal with the GMP licensing restrictions.

So I decided to try running the ARM-based Docker image on my x86_64 host, which I had never tried before. First, I needed to make sure that I can do that. This is the normal invocation of the Docker container:

$ docker run --rm quay.io/benz0li/ghc-musl:9.8.4 uname -a
Linux 8c14a21fc636 6.12.30 #1-NixOS SMP PREEMPT_DYNAMIC Thu May 22 12:29:54 UTC 2025 x86_64 Linux

As expected, the uname -a command ran inside the container shows that it is running on the x86_64 architecture. Now, we can try to run the ARM-based Docker image:

$ docker run --rm --platform linux/arm64 quay.io/benz0li/ghc-musl:9.8.4 uname -a
# exec /usr/bin/uname: exec format error

Configuring QEMU Support on NixOS

That is expected: We cannot run an ARM-based Docker image on an x86_64 host without some additional setup, in particular, using QEMU.

Most of the tutorials I found online suggested using:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

... which I decided would not work on my NixOS host. Instead, I used the NixOS option to enable QEMU emulation:

{
    boot.binfmt = {
      emulatedSystems = [ "aarch64-linux" ];
    };
}

This did not work, either. Apparently, Docker needs the static binaries provided by the multiarch/qemu-user-static image. So I changed my configuration as advised:

{
    boot.binfmt = {
      emulatedSystems = [ "aarch64-linux" ];
      preferStaticEmulators = true; # Make it work with Docker
    };
}

Good News

And it worked as such:

$ docker run --rm --platform linux/arm64 quay.io/benz0li/ghc-musl:9.8.4 uname -a
Linux 15afb3b1a45b 6.12.30 #1-NixOS SMP PREEMPT_DYNAMIC Thu May 22 12:29:54 UTC 2025 aarch64 Linux

Now, I could change the script to consume arbitrary arguments and pass them to the docker run command:

bash build-static.sh --platform=linux/arm64

Honestly, I was not expecting it to work, but it did, although it was noticeably slower! One thing I noticed was being able to run both the x86_64 and arm64 binaries on my x86_64 host, which I was not expecting at all. Apparently, my system is now capable of running both architectures at the same time -- with the latter running under emulation.

You can check the script and adopt it for your own Haskell projects.

Conclusion

It was an interesting day.

Firstly, I ran a non-x86_64 Docker image under emulation on my x86_64 host, which I had never done before. Secondly, now I know that I can cross-compile my Haskell projects for ARM architectures using the arm64 Docker image provided by benz0li. Going forward, I can fearlessly cross-compile my Haskell projects for any supported, non-native architectures.

And I am definitely going to try the Graviton processors, as soon as I spin up a Graviton EC2 instance on AWS.

The Terminal State of Mind

Vehbi Sinan Tunalioglu — Wed, 28 May 2025 15:46:30 +0000

I use the terminal. Not because I am a command-line wizard or particularly efficient with it, but because the GUI has never given me the rhythm and flow I need.

The GUI Does Not Fit My Mind

I have tried. I have used Gnome and KDE when they were just toddlers. I developed with both GTK and Qt, back when Qt had not yet seen Nokia coming. I know how powerful desktop environments can be. But they never worked for me the way I wanted.

I do not run a desktop environment anymore. I use a window manager, a Web browser and a terminal emulator. That is all. I do not even have a file manager.

Not a Wizard, Just a Survivor

I envy the real terminal wizards. They juggle panes, navigate the code as if it were nothing, and configure things I did not even know were configurable. I have seen people eating escape sequences for breakfast!

Me? I muddle through. For nearly 20 years, I was stuck with Emacs, not because I mastered it, but because I could never really wrap my head around vim keybindings. Emacs let me use commands and functions if I could not remember the keybind. That just made sense to me.

Even now, I do not consider myself a power user. There are these modern tools I always wanted to add to my workflow, like fzf, ripgrep, fd, bat. I did not have the time. But recently, I find myself reaching for bat and fzf more and more. They reward even a shallow investment.

Better Late Than Never

Take tmux. For years I used screen, mainly because it was what I knew and it worked on my remote hosts. Since I relied on tabbed terminal emulators on my workstation, I never felt a strong need for tmux.

But eventually, I gave it a shot. And after a few days of poking around and learning just enough to do my job with it, it clicked. I am not a tmux expert. I probably never will be. But even my simple understanding has made my work more comfortable.

The same thing happened with neovim. I used vim only when I had to, usually over SSH. However, there was so much excitement around neovim lately that I felt like I was missing out. So when Emacs started giving me trouble, I gave it a try. The muscle memory was not there. The command prompt felt awkward compared to Emacs. But I stuck with it, and eventually, I became productive.

The Pattern Is the Same

In both cases, the pattern repeated: a few days of grinding, a little reading, some trial and error, and then progress! Like learning a language or picking up a new instrument, there is a point where you stop struggling and start expressing.

The key is patience. Once you reach that threshold of effectiveness, everything gets smoother. And the more you practice, the more efficient you become.

Neurodiversity and the Terminal

Lastly, I want to touch on a topic that I did not expect to write about.

I easily get overwhelmed by visual clutter and decision fatigue. The terminal helps me quiet all that. My terminal-first setup is not about flexing or showing off, not even about efficiency in the traditional sense. It is about being less distracted. There is a calm to it.

Also, the mouse! When I reach my mouse and my eyes start looking for the pointer, I get anxious: Locate, aim, and shoot! This completely breaks my flow.

This got me wondering: what if the choice of terminal-first setup over more common GUI setups is not only about tradition or efficiency, but also about how the mind works?

Disclaimer: I am not diagnosed with any neurodivergent condition. But I am somewhat exposed to the literature and discussions around neurodiversity, in particular dyslexia and ADHD. I do not know if what follows holds true from an expert's perspective, but I will still share my opinions.

Fewer visual distractions, clear constraints and feedback, easier deep-work, and most importantly, reliance on logical and mental frameworks rather than muscle memory are all reasons why terminals might work better for people with neurodivergent conditions.

Don't get me wrong, GUIs might have their own benefits, too. But I can approach TUI applications like neovim or tmux with a similar mindset to GUIs: Discovery is easier, multi-tasking feels more natural and transparent, and they offer better environmental control than plain terminal commands.

Again, this is just my experience, but I find it interesting to consider that our choice for interfaces might be due to deeper patterns in how we think and process information.

Or maybe it is much simpler; it might be just about finding a space where we can think clearly and work effectively.

NixOS Rebuilds, Upgrades and Generation Diffs

Vehbi Sinan Tunalioglu — Tue, 27 May 2025 15:31:15 +0000

Today, I upgraded my NixOS system to the latest version, v25.05. It went smoothly. I just want to report my experience here.

In-Place Upgrades: NixOS vs Other Distributions

I have been using GNU/Linux for well over two decades now. And I have never upgraded my distribution in-place. I always did a fresh install, because I did not want to deal with leftover files, changed configuration options and so on.

But with NixOS, I only did fresh installs a few times across half a dozen workstations and cloud hosts, only when I provisioned them for the first time or changed my disks. The rest of the time, I just changed my NixOS channel to the latest version and ran nixos-rebuild switch --upgrade. It almost always worked without a hitch. Only sometimes, I had to fix some minor issues, like deprecated options or changed package names. But I never had to reinstall my system.

Today was no exception. In about half an hour, I had my system upgraded from NixOS v24.11 to v25.05.

NixOS Rebuilds and Diffs

While I was upgrading, I took note of a feature I have been using for a while now: Checking the differences between the new and the old generations.

A generation is a snapshot of your NixOS system at a certain point in time. This concept is quite central to both NixOS and Home Manager. It allows you to roll back to a previous state of your system if something goes wrong.

These generations are stored in the /nix/var/nix/profiles/ directory:

$ ls -dv /nix/var/nix/profiles/system-* | tail -n10
/nix/var/nix/profiles/system-86-link
/nix/var/nix/profiles/system-87-link
/nix/var/nix/profiles/system-88-link
/nix/var/nix/profiles/system-89-link
/nix/var/nix/profiles/system-90-link
/nix/var/nix/profiles/system-91-link
/nix/var/nix/profiles/system-92-link
/nix/var/nix/profiles/system-93-link
/nix/var/nix/profiles/system-94-link
/nix/var/nix/profiles/system-95-link

Each of these directories is a symlink to a specific generation of your system, which is a derivation stored under /nix/store/.

If you make even the smallest change to your NixOS configuration and run nixos-rebuild switch, it will create a new generation of your system. You can then compare the current generation with the previous one using nvd:

$ nvd diff /nix/var/nix/profiles/system-65-link /nix/var/nix/profiles/system-66-link
<<< /nix/var/nix/profiles/system-65-link
>>> /nix/var/nix/profiles/system-66-link
Version changes:
[ ... TRUNCATED FOR BREVITY ... ]
[U.]  #82  qsv                       2.2.1 -> 4.0.0
[C.]  #83  rofi                      1.7.5, 1.7.5+wayland3 -> 1.7.5+wayland3
[ ... TRUNCATED FOR BREVITY ... ]
[C*]  #87  systemd                   <none>, 256.10 x2, 256.10-man, 257.3 -> <none>, 256.10 x2, 256.10-man, 257.5
[C.]  #88  systemd-minimal           256.10 x2, 257.3 -> 256.10 x2, 257.5
[ ... TRUNCATED FOR BREVITY ... ]
Added packages:
[A.]  #1  bemoji                     0.4.0
[A.]  #2  ponymix                    5
[A.]  #3  rofi-bluetooth-unstable    2023-02-03
[A.]  #4  rofi-network-manager       0-unstable-2024-09-03
[A.]  #5  rofi-pulse-select          0.2.0
Removed packages:
[R.]  #1  python3.12-configargparse  1.7
[R.]  #2  rofimoji                   6.5.0
[ ... TRUNCATED FOR BREVITY ... ]
Closure size: 8610 -> 8683 (1200 paths added, 1127 paths removed, delta +73, disk usage +151.4MiB).

You can see the differences in three sections:

Version changes: Packages that have been upgraded/downgraded.
Added packages: New packages that have been added to the system.
Removed packages: Packages that have been removed from the system.

The reason I left systemd in the sample output above is to talk about when we need a reboot.

Rebooting After NixOS Updates

Whether you upgrade to a new NixOS version or just upgrade your system within the same version, you might need to reboot your system if certain packages have been upgraded.

When using Ubuntu, you might have noticed that the system prompts you to reboot after a kernel upgrade. This is because the package manager knows when to reboot. NixOS does not prompt you, so you have to check yourself.

There is no hard and fast rule, but a good rule of thumb is to reboot if

the Linux kernel has been upgraded, or
systemd has been upgraded.

The curse of NixOS is that it is a symlink hell, but this is also a blessing. Check it out:

$ stat -c '%N' /run/booted-system /run/current-system
'/run/booted-system' -> '/nix/store/9lhqy6mvqgmrisirdhbli43i5kmv3aky-nixos-system-myhost-25.05.20250525.7c43f08'
'/run/current-system' -> '/nix/store/9lhqy6mvqgmrisirdhbli43i5kmv3aky-nixos-system-myhost-25.05.20250525.7c43f08'

These two symbolic links point to two derivations in the Nix store, exactly what we call generations which we can list under /nix/var/nix/profiles/. You can check yourself.

When we run nixos-rebuild switch, it will create a new generation of our system, and change the /run/current-system symlink to point to the new generation. The /run/booted-system symlink will still point to the previous generation, which is the one that was active when the system booted.

So, if you want to check whether you need to reboot your system, you can run:

nvd diff /run/booted-system /run/current-system | grep -E 'systemd|linux'

If there is no output, you do not need to reboot. If there is output, you might need to reboot your system to apply the changes.

There is even a tool that does this for you: nixos-needsreboot. I did not feel like installing it, so I used the command above.

Bonus

You can add the following to your NixOS configuration:

{
  system.activationScripts = {
    diffGens = ''
      PATH=$PATH:${lib.makeBinPath [ pkgs.nix ]}
      echo "----- CHANGES (ROOT) -----" | ${pkgs.lolcat}/bin/lolcat -S 40
      ${pkgs.nvd}/bin/nvd diff /run/current-system "$systemConfig"
      echo "----- END OF CHANGES -----" | ${pkgs.lolcat}/bin/lolcat -S 40
    '';
  };
}

This will run the nvd diff command every time you switch to a new generation of your system. It will show you the differences between the current generation and the one you are switching to. It helped me out a lot to quickly see and understand what a rebuild did to my system.

I use the lolcat package to colorize the two lines indicating the start and end of the nvd diff command output.

The $systemConfig variable is a symlink to the recently built NixOS configuration, which is the one you are switching to. I had no idea that it existed until I read the source code of the related NixOS module.

That is what I like about NixOS: Often, you can find a solution to your problem by reading the source code of the NixOS modules.

Boring on Purpose: Bold Moves in Internal Tooling

Vehbi Sinan Tunalioglu — Mon, 26 May 2025 19:06:46 +0000

Boring work is often the most effective work. It is the kind of work that might lead us to understand patterns and solve problems that we did not even know we had.

Tolerance to boredom and tedium is a superpower, especially for programmers. Once we begin to recognize the patterns in our work, we can factor out the repetitive parts, automate them, and focus on what actually requires our attention. Tolerance is the key to such recognition in the first place.

Over the past few years, I have been reflecting on how I deal with work chores -- the kind of tasks nobody volunteers for. Oddly enough, I have become more effective and efficient at doing these. One unexpected benefit has been the tools I ended up building for myself.

Sometimes, these tools are not just helpful for me -- they also turn out to be useful for my colleagues.

Basecamp

A few years back, I decided to replace our spreadsheet-based host and service registries with a proper, Web-based asset registry. It took us a few days to hack together a simple system that we could use to track our infrastructure elements. It was not a big project -- just a simple app backed by a database, Hasura, and a React frontend. Since we were already using OpenID for authentication, it was easy for our team to start using it.

The next immediate step was to build a CLI tool that would allow us to interact with the registry from the command line. We used Haskell for this. One of the most useful features was the ability to generate an entire SSH configuration file from the registry data:

basecamp ssh config --output-file ~/.ssh/conf.d/work

This enabled us to register even less significant services in the registry -- ones we would not even bother to add to a spreadsheet. I could see quickly which services were running on which hosts, and how they related to each other.

Giving a Place to Ideas

The name Basecamp was not a coincidence. Like a real basecamp, it served as a starting point for further exploration -- not just of infrastructure, but of ideas.

Since then, we have added an incident registry, a GitHub repository registry with quick stats such as the number of open issues, PRs, etc., a knowledge base, and most effectively, a simple expense tracker.

Understanding Patterns and Relations

After effectively using Basecamp for a while, I started to notice new patterns I could make use of. For example, I launched HOSTPATROL, a simple tool for collecting and consolidating information about hosts over SSH, and shipped clompse, the companion to HOSTPATROL for collecting and consolidating cloud information.

As a result, I was able to run our asset registry review process in less than an hour. Even better, I changed the frequency of certain quarterly reviews to monthly, because I could do them so quickly.

The best part was that we managed to reduce our monthly cloud expenses by at least 25 percent over the last year, simply by having a better overview of our infrastructure and its costs.

Boring and Bold

This is not a life-changing, motivational story. On the contrary, it is a boring story that just happens to turn out well.

It did not start with a grand vision I was invested in. It started with the reflex to replace a few spreadsheets with a simple but enabling tool.

It is boring, but also bold. It is bold because spending time on internal systems goes against the grain in many organizations. And it is bold because it meant investing in boring work that nobody wants to do.

The best part is that the total amount of time my team and I spent on this was already amortized within a few months -- let alone the benefits we continue to reap today.

Conclusion

You might think of other alternatives to my approach of building internal tools from scratch, such as using existing SaaS solutions or tools like Notion, Airtable, headless CMS, etc.

In my concept, they are the same. One tolerates boring and tedious work, recognizes patterns and relations, and builds structures that help to understand and manage work better.

This kind of work is not about chasing the next big thing. It is not your next startup idea. It is about building a system that works for you and your team, makes your life easier, and gives you a foundation for new experiments. The trick is to start small -- think weekend-sized.

Scratching your own itch can be risky: your use case may not generalize. But who knows, maybe someday those experiments turn into something others want to use as well. What you need is a good Mom Test to validate your problem and its solution.

A Glimpse into My Shell

Vehbi Sinan Tunalioglu — Sun, 25 May 2025 18:34:39 +0000

A glimpse into my shell history reveals the tools I rely on daily. These are not curated -- just raw, frequent commands logged over time.

Since I have exhausted all my curiosity, I ran a quick command on my terminal to see which commands I use the most:

history 0 |
  awk '{print $2}' |
  sort |
  uniq -c |
  sort -n |
  tail -n 25 |
  tac

Here are the results:

    756 ls
    683 ssh
    596 gh
    507 git
    436 watson
    413 vim
    412 cat
    398 cd
    343 nix
    276 docker
    166 bash
    141 direnv
    139 ruff
    125 nox
    125 find
    123 curl
     93 nix-shell
     92 sudo
     92 devcli
     92 basecamp
     89 zenpolicy
     87 npm
     73 vst-nixos-switch
     71 cabal
     70 mv

If I were a carpenter, would these be my tools? Not really. I practically live inside my terminal, where I run tmux and vim inside it, probably half a dozen at a time. Inside vim, I use quite a few plugins, most notably neogit, the magit replacement for vim.

Still, these 25 commands capture how I interact with my system or what I do on my projects.

Navigation

I do not have a GUI-based file manager on my system. Both ls (756) and cd (398) are my primary tools for navigating the filesystem.

Another function of ls is that it is my fidget spinner. I use it to do nothing while I am thinking about what to do next.

I am not using any zsh plugins like z or autojump. I prefer to use cd and ls explicitly. Maybe I should give them a try.

Core Tools

I record my life in git (507). Since I am using GitHub -- not completely willingly -- I use gh (596) quite often, but not with stock commands only. I have quite a few aliases and extensions, including gh watson to track my time in GitHub repositories.

vim is not a surprise here. It has been almost a year since I switched to neovim from Emacs.

Another core tool is nix (343) and nix-shell (93). I use Nix to manage both my system and development environments. direnv (141) helps me to enter the Nix development environment automatically when I cd into a directory with a .envrc file. And vst-nixos-switch (73) is a custom command I use to deploy my NixOS system.

I am quite surprised that I am using docker (276) so much. I used to depend on Docker a lot on my workstation, but I have been using it less and less lately. Well, not less enough to drop it from the top 25 commands, though.

Also, ssh (683) is my only tool for remote access. So, it is quite normal to see it here. One thing I do with ssh is to run commands on remote hosts without falling into an interactive shell, hence the high count.

Programming Tools

These commands tell quite a bit about my work, I guess.

Recently, I have been doing quite a bit of Python development. In particular, I have been replacing flake8, isort, and pylint with ruff (139). nox (125) is my primary tool for running Python tests. So, the concentration of Python-related commands is not surprising.

It is like blue-collar work for me, but I am still developing with JavaScript and TypeScript. I use npm (87) quite often. Nope, I am not using yarn or pnpm. I do not even know why pnpm exists and I do not want to know.

Although I usually provision a devcli (92) script for each project, I still run cabal (71) quite often. Unlike other programming languages, I do not keep running a program to see if it works in Haskell. There are times when I keep programming for hours, and then I run cabal test for performing doctests or cabal dev-test-build -c to build, test, lint and format the codebase.

Utilities

cat (412) and find (125) did not really surprise me. I use cat usually to pipe the contents of one or more files to another command, not just printing them to the terminal. I use find to search for files, but almost half of the time, I perform an exec or xargs operation on the found files or directories.

mv (70) is my primary tool for moving or renaming files, except when I am working on a project inside neovim, where I use the sidebar to move files around.

sudo (92) is also quite normal, because I am my own boss.

Finally, bash (166) is to be expected, because I use it to run shell scripts which I quickly write to automate some tasks which do not fit into a one-liner.

Custom Stuff

I track my time with watson (436).

basecamp (92) is a custom tool my team and I wrote to keep track of incidents, notes, announcements, server and service registries, etc.

And finally, zenpolicy (89) is something from my kitchen. It will take some time, but hopefully, you will know more about it when I ship it.

Conclusion

So, how do these numbers look?

$ history 0 |
    awk '{print $2}' |
    sort |
    uniq -c |
    sort -n |
    tail -n 25 |
    tac |
    awk '{printf "%s,%d\n", $2, $1}' |
    uplot barplot -d, -o /dev/stdout -t "Top 25 Commands"
                                 Top 25 Commands
                    ┌                                        ┐
                 ls ┤■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 757.0
                ssh ┤■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 683.0
                 gh ┤■■■■■■■■■■■■■■■■■■■■■■■■■■ 596.0
                git ┤■■■■■■■■■■■■■■■■■■■■■■ 507.0
             watson ┤■■■■■■■■■■■■■■■■■■■ 436.0
                vim ┤■■■■■■■■■■■■■■■■■■ 413.0
                cat ┤■■■■■■■■■■■■■■■■■■ 412.0
                 cd ┤■■■■■■■■■■■■■■■■■ 398.0
                nix ┤■■■■■■■■■■■■■■■ 343.0
             docker ┤■■■■■■■■■■■■ 276.0
               bash ┤■■■■■■■ 166.0
             direnv ┤■■■■■■ 141.0
               ruff ┤■■■■■■ 139.0
                nox ┤■■■■■ 125.0
               find ┤■■■■■ 125.0
               curl ┤■■■■■ 124.0
            history ┤■■■■■ 104.0
          nix-shell ┤■■■■ 93.0
               sudo ┤■■■■ 92.0
             devcli ┤■■■■ 92.0
           basecamp ┤■■■■ 92.0
          zenpolicy ┤■■■■ 89.0
                npm ┤■■■■ 87.0
   vst-nixos-switch ┤■■■ 73.0
              cabal ┤■■■ 71.0
                    └                                        ┘

Your shell history never lies. Mine reflects how I like it: simple interfaces, power tools, and workflows built around the CLI. If I use something hundreds of times a week, it must be a good, reliable investment.

Data Definitions, Not Flowcharts

Vehbi Sinan Tunalioglu — Sat, 24 May 2025 19:38:37 +0000

Computer programs are best understood in terms of the data they consume, process and produce. Flowcharts are useful for visualizing control flow, but not for understanding complexity.

One of the most famous quotes of Frederick Brooks is:

Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious.

-- The Mythical Man-Month, 1975

This quote is my constant reminder that computer programs are best understood in terms of the data they consume, process and produce. The information that a flowchart provides is not only too abstract, but also vague and underspecified even as a conceptual model.

Defining what a computer program is deserves its own blog post, but my point here is that it is NOT primarily about the procedures and control flows, but rather the data structures and their relationships.

I keep emphasizing that data definitions are not only important for the implementation of a program, but also for its design and documentation. It is the only connection to the phase of problem analysis: The more precisely the data is defined during analysis, the more precise the implementation will be.

Although I enjoy doodling diagrams, I never bring them to the fight. Instead, I sit down and write down the data types and their relationships in a programming language.

One benefit of using high-level, strongly typed functional programming languages is that functions and effects can be expressed in terms of type definitions: Function signatures and effect constraints are type definitions, and so on. You can even use defunctionalization to express functions as data definitions, which is a common technique in functional programming.

In Haskell, I usually create a module named Algebra and tinker with the definitions there. I still like to refer to my prototype as an algebra, a habit from when I was studying algebraic data types and free monads. How it is implemented (interpreted) is not important at this point.

What is wrong with flowcharts? Nothing, but they are not the right tool for analyzing and designing a program. They are useful for visualizing the control flow of a program, but not for understanding its complexity. When it comes to communicating the high-level view of a program or a system to a complete non-technical audience, I still use flowcharts.

Lastly, I have been thinking about how arrows can be used to describe a high-level view of a program. Inspired by category theory, they offer a way to represent computation (that is, that transforms input of type A into output of type B), abstracting away internal implementation details while still focusing on inputs and outputs.

This focus on data transformations is why I am exploring arrows as a design tool -- they force you to think in terms of data type transformations rather than procedural steps.

Magic JSON in Haskell

Vehbi Sinan Tunalioglu — Fri, 23 May 2025 15:15:04 +0000

Among all Haskell libraries I have used, the one I reach for the most is autodocodec. I will explain what it is and what freebies it gives you.

I have been thinking about writing this post for a while, but I never got around to it. There is no right time to talk about it, so it is now.

JSON in Haskell

It is almost too simple. aeson library, the most popular JSON library in Haskell, defines a JSON value as:

data Value
  = Object !Object
  | Array !Array
  | String !Text
  | Number !Scientific
  | Bool !Bool
  | Null

Haskell data types can have JSON value representations:

data Post = MkPost
  { postTitle :: Text
  , postContent :: Text
  , postPublished :: Bool
  }
  deriving (Show)


instance ToJSON Post where
  toJSON (MkPost title content published) =
    object
      [ "title" .= title
      , "content" .= content
      , "published" .= published
      ]


instance FromJSON Post where
  parseJSON = withObject "Post" $ \o ->
    MkPost
      <$> o .: "title"
      <*> o .: "content"
      <*> o .: "published"

This way, we can work with the JSON representation of our data types:

>>> encode (MkPost "Hello, World!" "This is a very short post." True)
{"content":"This is a very short post.","published":true,"title":"Hello, World!"}
>>> decode "{\"content\":\"This is a very short post.\",\"published\":true,\"title\":\"Hello, World!\"}" :: Maybe Post
Just (MkPost {postTitle = "Hello, World!", postContent = "This is a very short post.", postPublished = True})

If you are coming from JavaScript or TypeScript, this is what you are used to do with JSON.parse and zod. And you are right, in Haskell, this is quite verbose and boilerplate-driven. But it is quite principled and type-safe. For example, you can parse and map, but cannot perform IO operations when defining your ToJSON and FromJSON instances. Also, you cannot have multiple JSON representations of the same data type (so-called type-class instance coherence in Haskell). You need newtype wrappers for that:

newtype QuickPost = MkQuickPost Post
  deriving (Show)


instance ToJSON QuickPost where
  toJSON (MkQuickPost (MkPost title content _)) =
    object
      [ "subject" .= title
      , "body" .= content
      , "published" .= True
      ]


instance FromJSON QuickPost where
  parseJSON = withObject "QuickPost" $ \o ->
    MkQuickPost
      <$> (MkPost
              <$> o .: "subject"
              <*> o .: "body"
              <*> o .: "published"
          )

We are referring to the same data type, but with a different JSON representation, without any runtime overhead:

>>> encode (MkQuickPost (MkPost "Hello, World!" "This is a very short post." True))
{"body":"This is a very short post.","published":true,"subject":"Hello, World!"}
>>> decode "{\"body\":\"This is a very short post.\",\"published\":true,\"subject\":\"Hello, World!\"}" :: Maybe QuickPost
Just (MkQuickPost (MkPost {postTitle = "Hello, World!", postContent = "This is a very short post.", postPublished = True}))

JSON Field Order

You might have noticed that the order of fields in the JSON output is not the same as the order of fields in the Haskell data type. This is because aeson does not guarantee the order of fields in the JSON output if you define ToJSON without toEncoding. toEncoding would be a more efficient and predictable way to define how we output the JSON representation. If you do not define it, aeson will use toJSON to convert the data type to a JSON Value, and use Value's toEncoding to output the JSON. This is when the order of fields is based on what is pulled from the Map in the Object constructor, which is not necessarily the same as the order of fields in the Haskell data type.

Let us try to define toEncoding for our Post data type:

instance ToJSON Post where
  toJSON (MkPost title content published) =
    object
      [ "title" .= title
      , "content" .= content
      , "published" .= published
      ]

  toEncoding (MkPost title content published) =
    pairs
      (  "title" .= title
      <> "content" .= content
      <> "published" .= published
      )

And the result is:

>>> encode (MkPost "Hello, World!" "This is a very short post." True)
{"title":"Hello, World!","content":"This is a very short post.","published":true}

What if I am lazy?

If you are lazy enough, you will not want to define ToJSON and FromJSON instances for your data types manually. You will want to use Generic or TemplateHaskell to derive them automatically.

I have used the Generic approach for a very long time. It is quite simple and you might even want to centralize your JSON style to enforce it across your data types:

data Post = MkPost
  { postTitle :: Text
  , postContent :: Text
  , postPublished :: Bool
  }
  deriving (Show, Generic, Eq)


instance ToJSON Post where
  toEncoding = genericToEncoding defaultOptions {
    fieldLabelModifier = camelTo2 '_' . drop 4
  }


instance FromJSON Post where
  parseJSON = genericParseJSON defaultOptions {
    fieldLabelModifier = camelTo2 '_' . drop 4
  }

... which will give us:

>>> encode (MkPost "Hello, World!" "This is a very short post." True)
{"title":"Hello, World!","content":"This is a very short post.","published":true}
>>> decode "{\"content\":\"This is a very short post.\",\"published\":true,\"title\":\"Hello, World!\"}" :: Maybe Post
Just (MkPost {postTitle = "Hello, World!", postContent = "This is a very short post.", postPublished = True})

Do not worry much about the fieldLabelModifier function. You can create your own options generator that would work for all your data types as long as you tell it how to drop the prefix from the field names:

myOptions :: String -> Options
myOptions prefix = defaultOptions {
  fieldLabelModifier = camelTo2 '_' . drop (length prefix)
}

... then:

instance ToJSON Post where
  toEncoding = genericToEncoding (myOptions "post")

instance FromJSON Post where
  parseJSON = genericParseJSON (myOptions "post")

What if I am even lazier?

OK, if you have not used Haskell before, by now, you might have already given up. But this approach of defining type-class instances is quite common in Haskell. They often involve boilerplate, but they provide significant safety and discipline.

What if we want to generate the YAML representations? How about JSON schema or OpenAPI schema?

They all have their own type-classes (ToSchema) or piggyback on the existing ones (for example, yaml uses aeson for decoding and encoding).

This is where autodocodec comes in. It is a library that allows you to automatically derive instances such as ToJSON, FromJSON, ToSchema and FromSchema. You will write the boilerplate once, and then you will be able to generate the rest of the instances automatically.

Let us reproduce the previous example using autodocodec:

data Post = MkPost
  { postTitle :: Text
  , postContent :: Text
  , postPublished :: Bool
  }
  deriving (Show, Generic, Eq)
  deriving (FromJSON, ToJSON) via (Autodocodec Post)


instance HasCodec Post where
  codec =
    object "Post" $
      MkPost
        <$> requiredField "title" "Title of the post" .= postTitle
        <*> requiredField "content" "Content of the post" .= postContent
        <*> requiredField "published" "Publish status of the post" .= postPublished

... and:

>>> encode (MkPost "Hello, World!" "This is a very short post." True)
{"title":"Hello, World!","content":"This is a very short post.","published":true}
>>> decode "{\"content\":\"This is a very short post.\",\"published\":true,\"title\":\"Hello, World!\"}" :: Maybe Post
Just (MkPost {postTitle = "Hello, World!", postContent = "This is a very short post.", postPublished = True})

We wrote more, but did we get more? Yes, we did. Look at this:

>>> Data.Text.IO.putStrLn $ renderColouredSchemaViaCodec @Post
# Post
title: # required
  # Title of the post
  <string>
content: # required
  # Content of the post
  <string>
published: # required
  # Publish status of the post
  <boolean>

With the help of renderColouredSchemaViaCodec function from autodocodec-yaml, we can generate a coloured schema for our data type. Cool, right?

Let us do more, with the help of jsonSchemaViaCodec function from autodocodec-schema:

>>> encode $ jsonSchemaViaCodec @Post
{
  "$comment": "Post",
  "properties": {
    "content": {
      "$comment": "Content of the post",
      "type": "string"
    },
    "published": {
      "$comment": "Publish status of the post",
      "type": "boolean"
    },
    "title": {
      "$comment": "Title of the post",
      "type": "string"
    }
  },
  "required": [
    "published",
    "content",
    "title"
  ],
  "type": "object"
}

Conclusion

I really like autodocodec. I am using it heavily in my projects, especially when I need to generate JSON Schema (for example, to aid configuration file specifications) or OpenAPIv3 Schema (for Servant projects). I recently noticed that there is even autodocodec-nix as an interpreter for Nix expressions.

I am fine with writing boilerplate as long as it gives me type-safety and discipline. Using autodocodec, I feel like maximizing my return on investment into writing boilerplate.

Hacking Haskell with Nix: Two Tricks

Vehbi Sinan Tunalioglu — Thu, 22 May 2025 15:44:44 +0000

I have mentioned a few times in my posts that Haskell is my go-to language. This is true even for small applications which go beyond a simple shell script.

Hacking Haskell with Nix is an easy and fun way to quickly prototype. I want to share two tricks that I use.

Nix-Based Haskell Scripting

If you are using Nix, you may have heard of Nix-Shell Shebang:

#!/usr/bin/env nix-shell
#!nix-shell -i python3 -p python3 -p python3Packages.click

import click

@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

if __name__ == '__main__':
    hello()

You can chmod +x script.py and run it directly:

$ ./script.py --count 3 --name "John Doe"
Hello John Doe!
Hello John Doe!
Hello John Doe!

This is a brilliant hack allowing you to not only pick the interpreter for your script, but also add dependencies to the shebang line.

Let us see how the same approach works with Haskell:

#!/usr/bin/env nix-shell
#!nix-shell -i runghc -p "haskellPackages.ghcWithPackages (hask: [ hask.aeson hask.bytestring ])"

import qualified Data.Aeson as Aeson
import qualified Data.ByteString.Lazy.Char8 as BLC
import System.Exit (die)

main :: IO ()
main = do
  jsonData <- BLC.getContents
  case Aeson.decode jsonData of
    Just value -> tellJsonType value
    Nothing -> die "Invalid JSON!"

tellJsonType :: Aeson.Value -> IO ()
tellJsonType (Aeson.Object _) = putStrLn "JSON value is an object."
tellJsonType (Aeson.Array _) = putStrLn "JSON value is an array."
tellJsonType (Aeson.String _) = putStrLn "JSON value is a string."
tellJsonType (Aeson.Number _) = putStrLn "JSON value is a number."
tellJsonType (Aeson.Bool _) = putStrLn "JSON value is a boolean."
tellJsonType Aeson.Null = putStrLn "JSON value is null."

Same as before, you can chmod +x script.hs and run it directly:

$ echo '{}' | ./script.hs
JSON value is an object.

Granted, this approach does not scale well, as you must manually pull in all development dependencies into a Nix shell, such as cabal, haskell-language-server, fourmolu, etc.

If that is the case, why not use a proper but minimal Haskell project template?

Minimal Haskell Project Template

I use cabal. A simple, cabal-based Haskell package needs only two files:

Main.hs
haskell-simple-app.cabal

Let us say that we are using the previous Haskell program, but without the Nix shebang:

import qualified Data.Aeson as Aeson
import qualified Data.ByteString.Lazy.Char8 as BLC
import System.Exit (die)

main :: IO ()
main = do
  jsonData <- BLC.getContents
  case Aeson.decode jsonData of
    Just value -> tellJsonType value
    Nothing -> die "Invalid JSON!"

tellJsonType :: Aeson.Value -> IO ()
tellJsonType (Aeson.Object _) = putStrLn "JSON value is an object."
tellJsonType (Aeson.Array _) = putStrLn "JSON value is an array."
tellJsonType (Aeson.String _) = putStrLn "JSON value is a string."
tellJsonType (Aeson.Number _) = putStrLn "JSON value is a number."
tellJsonType (Aeson.Bool _) = putStrLn "JSON value is a boolean."
tellJsonType Aeson.Null = putStrLn "JSON value is null."

Our script depends on two libraries: aeson and bytestring. Then, the cabal file looks like this:

cabal-version: 2.4
name:          haskell-simple-app
version:       0.0.0.1
license:       MIT
author:        Your Name
maintainer:    you@example.com
synopsis:      Minimal single-file Haskell executable
category:      Utility
build-type:    Simple

executable haskell-simple-app
  main-is:          Main.hs
  hs-source-dirs:   .
  ghc-options:      -Wall
  build-depends:
    , aeson
    , base        >=4.14 && <5
    , bytestring

  default-language: Haskell2010

I am not explaining the cabal file here, but you should get the general idea: A set of metadata followed by an executable section that describes how to build an executable with its dependencies.

In addition to the above two files, how about a Nix Flakes to develop and package this project as a Nix program?

{
  description = "A Simple Application in Haskell";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs { inherit system; };

        thisHaskell = pkgs.haskellPackages.override {
          overrides = self: super: {
            haskell-simple-app = self.callCabal2nix "haskell-simple-app" ./. { };
          };
        };

        thisShell = thisHaskell.shellFor {
          packages = p: [ p.haskell-simple-app ];
          withHoogle = true;
          buildInputs = [
            ## Haskell related build inputs:
            thisHaskell.apply-refact
            thisHaskell.cabal-fmt
            thisHaskell.cabal-install
            thisHaskell.cabal2nix
            thisHaskell.fourmolu
            thisHaskell.haskell-language-server
            thisHaskell.hlint

            ## Other build inputs for various development requirements:
            pkgs.nil
            pkgs.nixpkgs-fmt
          ];
        };

        thisPackage = pkgs.haskell.lib.justStaticExecutables thisHaskell.haskell-simple-app;
      in
      {
        packages = {
          haskell-simple-app = thisPackage;
          default = self.packages.${system}.haskell-simple-app;
        };

        devShells = {
          default = thisShell;
        };
      });
}

If you are familiar with Nix and Nix Flakes, this should be straightforward:

We create our Nix Haskell package set, thisHaskell, with our project haskell-simple-app using callCabal2nix.
We create a Nix shell, thisShell, with our project and a few other Haskell development tools.
We create a Nix package, thisPackage, with our project built as a static executable (not really statically linked, but the Nix closure cleared).

With all these three files in place, we can then:

$ echo '{}' | nix run
JSON value is an object.

You can do anything you want with this setup, including installing the program into your Nix profile and use it from anywhere on your system:

$ nix profile install .#haskell-simple-app
$ echo '{}' | haskell-simple-app
JSON value is an object.

Conclusion

I wanted to share with you two ways to quickly hack a Haskell script or even a minimal but complete Haskell project using Nix.

I kept these as snippets here and there. Today, I added the haskell-simple-app template to my Nix Flakes Templates repository. I am planning to refine it further, but you can use it now to create a new Haskell project with Nix:

nix flake init --template github:vst/nix-flake-templates#haskell-simple-app

Or even run this template straight away without creating a new project:

echo '{}' | nix run "github:vst/nix-flake-templates?dir=templates/haskell-simple-app" --no-write-lock-file

Still, why would you do that instead of creating a proper project?

Hacking with mdBook

Vehbi Sinan Tunalioglu — Wed, 21 May 2025 15:12:50 +0000

This post explores how to hack an mdBook project with scripts.

A few days back, I wrote a blog post about static site generators, in particular how I decided to migrate my blog from Zola to Hugo. One of my points was to be able to hack my own content before generating the final HTML.

mdBook

mdBook is a Rust-based tool to create Web-based books from vanilla Markdown files. Although it is quite minimalistic, you will bump into it quite often in the wild. Most notably, the Rust Book uses it. I see it quite often in the Nix ecosystem, too.

As I said, it is minimalistic. If you have a tree of Markdown files, you just need a SUMMARY.md file to render them into a navigable book. The Markdown flavor is CommonMark, without any extensions and front-matter. This makes it readable and navigable even on GitHub or GitLab without compiling the book.

I used mdBook in the past, and I reach for it every now and then. Occasionally, my needs quickly grow bigger than what mdBook offers out of the box. The good news is that I can help myself with a few scripts that pre-process my Markdown files before building the book.

Today, I did it again, and I thought it would be a good idea to share my approach with you.

The Setup

Let us create a simple mdBook project:

nix run nixpkgs#mdbook -- init --title="mdBook Demo" --ignore=git

The directory structure looks like this along with a quick overview of the files:

$ tree
.
├── book               <- The output directory
├── book.toml          <- mdBook configuration
├── .gitignore         <- Files to ignore in Git tree
└── src                <- Content directory for Markdown files
    ├── chapter_1.md   <- Sample Markdown file
    └── SUMMARY.md     <- Sidebar navigation file

3 directories, 4 files

We are interested in the files under the src directory. In particular, src/SUMMARY.md file must exist and refer to individual Markdown files for them to be included in the book:

# Summary

- [Chapter 1](./chapter_1.md)

The Problem

I faced two problems.

The first problem was to manage metadata in my Markdown files. mdBook does not allow any front-matter in the Markdown files. While there is a pre-processor that removes front-matter, I want to utilize the metadata before it is stripped.

My second problem was me being too lazy to manage the SUMMARY.md file manually. If I can put weight in the front-matter of the Markdown files, I can use it to define the order of each chapter in the book. This is a common pattern in many static site generators. Indeed, I wanted to add some further metadata to Markdown files, such as last review date, tags, todos and so on, to generate more Markdown files in addition to SUMMARY.md.

The Solution

Let us say we have two Markdown content files with front-matter:

introduction.md

---
title: "Introduction"
weight: 1
---

Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

chapter_1.md:

---
title: "Chapter 1"
weight: 100
---

Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The `SUMMARY.md` File

How about parsing the front-matter, sorting the records by weight, and preparing the SUMMARY.md file with mustache?

First, let us pull the dependencies using Nix:

nix-shell -p jq -p yq-go -p mustache-go

We need a Mustache template, SUMMARY.mustache:

# Summary

{{#.}}
- [{{title}}]({{path}})
{{/.}}

The following command will generate the SUMMARY.md file, running under the ./src directory for simplicity:

find . \
  -iname "*.md" -and -not -name "SUMMARY.md" \
  -exec yq --front-matter=extract --output-format=json '. += {"path": "{}"}' {} \; |
  jq --slurp "sort_by(.weight)" |
  mustache ../SUMMARY.mustache > SUMMARY.md

We find all Markdown files of interest, extract their front-matter as JSON and inject the file path (relative to src directory) to the JSON object, slurp individual JSON objects into an array and sort it by the weight field. Finally, we use the JSON data to be rendered by the Mustache template into the SUMMARY.md file.

Done! One task is complete.

Individual Chapters

Each Markdown file is now rendered with the front-matter included. Instead, we want to extract the title from the front-matter, add it as an # heading and remove the front-matter.

This is done using the mdBook pre-processor. Our pre-processor is a simple Python script, added to the book.toml file:

[preprocessor.my-preprocessor]
command = "python script.py"

What should the script.py file look like?

import json
import sys

import frontmatter


def main():
    if len(sys.argv) > 1:
        if sys.argv[1] == "supports":
            sys.exit(0)

    context, book = json.load(sys.stdin)

    for section in book["sections"]:
        process_section(section)

    json.dump(book, sys.stdout)


def process_section(section):
    if "Chapter" in section:
        process_chapter(section["Chapter"])


def process_chapter(chapter):
    data = frontmatter.loads(chapter["content"])

    if data.keys():
        chapter["content"] = f"# {data['title']}\n\n{data.content}"


if __name__ == "__main__":
    main()

What does it do? mdBook will collect all Markdown files of interest, pack them into an internal data definition (as a tuple of [context] and [book]), pass it to the pre-processor as a JSON value from stdin, and expect the processed book data to be returned as a JSON value from stdout.

Particularly in the above case:

mdBook will call our script with the supports argument to check if it supports the pre-processor. We do not care about it here, so the script just returns 0 to indicate success.
Otherwise, the script reads the JSON data from stdin into context and book symbols.
We are interested in the book value which has one or more sections.
We iterate over each section and process it.
For each section, we check if it is a chapter, and if so, process it.
For each chapter, we use the Python frontmatter library to extract the front-matter and the content. If there is any front-matter, we remove it by replacing the content with the title as an h1 heading and the rest of the content.

Now, let us serve the book:

nix-shell \
  -p mdbook \
  -p python3Packages.python-frontmatter \
  --run "mdbook serve"

Done! You can now open your browser and navigate to http://localhost:3000.

Conclusion

I like to use mdBook for quick documentation. Sometimes, I end up managing data in my Markdown files and I need to pre-process them before building the book. Likewise, I may need to generate additional Markdown files for the book, such as SUMMARY.md or other files.

The power of mdBook is due to its simplicity and clear design for pre-processing.

I strongly recommend keeping it in your toolbox, along with other command-line power tools, such as jq, yq, and mustache. No need to mention Nix, right?

Haskell Project Template with Nix Flakes

Vehbi Sinan Tunalioglu — Tue, 20 May 2025 15:06:04 +0000

This post introduces my Haskell project template powered by Nix Flakes -- a simple setup I use to quickly spin up new Haskell applications.

Haskell has been my go-to language for over 7 years. First, I started with Stack, then switched to plain Cabal and finally settled on Nix to provision a development environment for Haskell projects.

Since I primarily develop applications rather than libraries, I find it more practical to structure my development environment and builds around producing standalone Nix packages, statically built executables and container images using Nix.

Nix offers several approaches for working with Haskell. In my experience, the three most prominent are:

The Haskell infrastructure in Nixpkgs -- simple and built-in.
Haskell.nix -- a more flexible but complex option from IOHK.
haskell-flake -- a recent and modular setup based on flake-parts.

I tried the second option a few years ago but have not tried the third one. I have been using the first one, using classic Nix. Only recently, I have refactored some of my projects to use Nix Flakes. Today, I also refactored my Haskell project template to use Flakes.

My plan is to invest some time in flake-parts and Horizon Haskell. In this post, I will simply go through my template's flake.nix file and show what it does.

The template may evolve, but the examples in this post reference a pinned version for consistency. Also note that the template is a GitHub Repository Template that you can use to create a new repository with the same structure. Check out the run-template.sh script that will help you update template variables.

The flake.nix

Here is the flake.nix file:

{
  description = "Haskell Project Template";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        ## Import nixpkgs:
        pkgs = import nixpkgs { inherit system; };

        ## Load readYAML helper:
        readYAML = pkgs.callPackage ./nix/read-yaml.nix { };

        ## Read package information:
        package = readYAML ./package.yaml;

        ## Get our Haskell:
        thisHaskell = pkgs.haskellPackages.override {
          overrides = self: super: {
            ${package.name} = self.callCabal2nix package.name ./. { };
          };
        };

        ## Prepare dev-test-build script:
        dev-test-build = pkgs.writeShellApplication {
          name = "cabal-dev-test-build";
          text = builtins.readFile ./nix/dev-test-build.sh;
          runtimeInputs = [ pkgs.bash pkgs.bc pkgs.moreutils ];
        };

        ## Prepare Nix shell:
        thisShell = thisHaskell.shellFor {
          ## Define packages for the shell:
          packages = p: [ p.${package.name} ];

          ## Enable Hoogle:
          withHoogle = false;

          ## Build inputs for development shell:
          buildInputs = [
            ## Haskell related build inputs:
            thisHaskell.apply-refact
            thisHaskell.cabal-fmt
            thisHaskell.cabal-install
            thisHaskell.cabal2nix
            thisHaskell.fourmolu
            thisHaskell.haskell-language-server
            thisHaskell.hlint
            thisHaskell.hpack
            thisHaskell.weeder

            ## Our development scripts:
            dev-test-build

            ## Other build inputs for various development requirements:
            pkgs.docker-client
            pkgs.git
            pkgs.nil
            pkgs.nixpkgs-fmt
            pkgs.nodePackages.prettier
            pkgs.upx
          ];
        };

        thisPackage = pkgs.haskell.lib.justStaticExecutables (
          thisHaskell.${package.name}.overrideAttrs (oldAttrs: {
            nativeBuildInputs = (oldAttrs.nativeBuildInputs or [ ]) ++ [
              pkgs.git
              pkgs.makeWrapper
              pkgs.ronn
            ];

            postFixup = (oldAttrs.postFixup or "") + ''
              ## Create output directories:
              mkdir -p $out/{bin}

              ## Wrap program to add PATHs to dependencies:
              wrapProgram $out/bin/${package.name} --prefix PATH : ${pkgs.lib.makeBinPath []}
            '';
          })
        );

        thisDocker = pkgs.dockerTools.buildImage {
          name = "${package.name}";
          tag = "v${package.version}";
          created = "now";

          copyToRoot = pkgs.buildEnv {
            name = "image-root";
            paths = [ pkgs.cacert ];
            pathsToLink = [ "/etc" ];
          };

          runAsRoot = ''
            #!${pkgs.runtimeShell}
            ${pkgs.dockerTools.shadowSetup}
            groupadd -r users
            useradd -r -g users patron
          '';

          config = {
            User = "patron";
            Entrypoint = [ "${thisPackage}/bin/${package.name}" ];
            Cmd = null;
          };
        };
      in
      {
        ## Project packages output:
        packages = {
          "${package.name}" = thisPackage;
          docker = thisDocker;
          default = self.packages.${system}.${package.name};
        };

        ## Project development shell output:
        devShells = {
          default = thisShell;
        };
      });
}

The 125-line flake.nix file might look a bit overwhelming at first, but it is actually quite simple considering that this file gives us the following:

A Nix-installable package,
A Docker image with the package application as the entrypoint, and
A development shell with all the development dependencies.

There are some placeholders in the file, such as building man pages with ronn during the package's postFixup phase. I am not using this feature in all of my projects, but it comes in handy when I need it. Likewise, we can add extra bin paths to the PATH variable in the postFixup phase for system binaries.

Let us go over notable parts and features of the file.

First of all, we do not refer to the name of the package. Instead, we load the package.yaml file and read the name and version from it. Note that the readYAML function is a simple helper I manage in my nix directory as there is no built-in for reading YAML files in Nix yet:

readYAML = pkgs.callPackage ./nix/read-yaml.nix { };
package = readYAML ./package.yaml;

Then, we create a Haskell package set with our package included:

thisHaskell = pkgs.haskellPackages.override {
  overrides = self: super: {
    ${package.name} = self.callCabal2nix package.name ./. { };
  };
};

This is used when we create the development shell:

thisShell = thisHaskell.shellFor {
  packages = p: [ p.${package.name} ];
  buildInputs = [
    ## ...
  ];
};

... and when we create the package:

thisPackage = pkgs.haskell.lib.justStaticExecutables (
  thisHaskell.${package.name}.overrideAttrs (oldAttrs: {
    nativeBuildInputs = (oldAttrs.nativeBuildInputs or [ ]) ++ [
      ## ...
    ];

    postFixup = (oldAttrs.postFixup or "") + ''
      ## ...
    '';
  })
);

Finally, we build a Docker image with the package as the entrypoint:

thisDocker = pkgs.dockerTools.buildImage {
  ## ...
  config = {
    User = "patron";
    Entrypoint = [ "${thisPackage}/bin/${package.name}" ];
    Cmd = null;
  };
};

The tools I include in this flake.nix file come in handy, especially with other features of this template. For example, I included a cabal dev-test-build script that helps me build the package, run tests, linters and formatters. Additionally, and, probably most importantly, I have a script to statically build the application in a Docker image and compress it with upx to reduce the size of the final binary.

I am pretty sure that there are many better ways to do what I do in this template repository, but I am happy using it to quickly spin up a new Haskell project. There are quite a few other things and methods I use in real-life projects, such as multi-package builds and GitHub Release Please Action integration, which are quite easy to add upon this template.

If you find this template useful, consider starring the repository or bookmarking it for future reference. You might also want to check out my new Nix Flake Templates collection, where I plan to share more Haskell setups as my use cases expand.

Forem: Vehbi Sinan Tunalioglu

I Blogged Every Day for a Month -- Again

The grind is real -- and it teaches you

I wanted to quit around Day 15

Streaks help with accountability

Constraints trigger creativity

It is possible to write a blog post in less than 2 hours

Quantity over quality

Writing helps me learn

Crossposting revealed what people actually read

I now have a content archive

I showed up for myself

What next?

Daily Z Reports and Weekly Reviews

The Z Report

The Weekly Review

Reflection as Operational Practice

Close the Register, Open the Week

Cross-Compiling Haskell under NixOS with Docker

Motivation

Cross-Compiling Haskell Projects

Configuring QEMU Support on NixOS

Good News

Conclusion

The Terminal State of Mind

The GUI Does Not Fit My Mind

Not a Wizard, Just a Survivor

Better Late Than Never

The Pattern Is the Same

Neurodiversity and the Terminal

NixOS Rebuilds, Upgrades and Generation Diffs

In-Place Upgrades: NixOS vs Other Distributions

NixOS Rebuilds and Diffs

Rebooting After NixOS Updates

Bonus

Boring on Purpose: Bold Moves in Internal Tooling

Basecamp

Giving a Place to Ideas

Understanding Patterns and Relations

Boring and Bold

Conclusion

A Glimpse into My Shell

Navigation

Core Tools

Programming Tools

Utilities

Custom Stuff

Conclusion

Data Definitions, Not Flowcharts

Magic JSON in Haskell

JSON in Haskell

JSON Field Order

What if I am lazy?

What if I am even lazier?

Conclusion

Hacking Haskell with Nix: Two Tricks

Nix-Based Haskell Scripting

Minimal Haskell Project Template

Conclusion

Hacking with mdBook

mdBook

The Setup

The Problem

The Solution

The SUMMARY.md File

Individual Chapters

Conclusion

Haskell Project Template with Nix Flakes

The flake.nix

The `SUMMARY.md` File