Hello, World

December 28, 2024

Tags:

Welcome to Software Wanderings, my new technical blog. I hope this blog will encourage me to write about my experiences, learnings and observations about software engineering. I am also making this blog public and hopefully other people will find some of this useful.

This blog is going to cover software design, functional programming, API design and more. It will focus on the Clojure programming language, but should include other languages like JavaScript, TypeScript, Rust, Scheme and SQL.

I have several goals for 2025, and I will be using this blog to record my efforts in reaching these goals.

2025 Goals

I hope to learn or better understand the following software systems.

Learn about Game Development: Since I was a kid and playing Red Alert at my friend John’s house I have wanted to build a Command and Conquer or StarCraft like game. I want to make 2025 the year when I finally understand game development and build something.
Learn more about Immutable Linux: Understand and better use immutable Linux distros. NixOS, Gnu Guix, Fedora Sliverblue are all modern “immutable” distributions.
Deepen my understanding of Pandoc: Pandoc is an advance document transformation system. It allows you to convert any document into any other document. It also includes a “transformation” system that allow you to modify documents.
Deepen my understanding Rest API and GraphQL API: Continue to learn and write about the best ways to design and build these type of API Systems.
Write about it!: Hence the blog.

Blog Architecture

This blog is host on GitHub, using GitHub pages. The blog uses Haunt to build and organize our HTML Templates. Most of my understanding of Haunt comes from David Thompson’s own blog. Thanks to David for both writing Haunt and sharing his own blog.

Currently, I am using Pandoc to preprocess Markdown documents into HTML documents. These HTML documents are then processed by Haunt. Haunt supports Markdown, but I am using Pandoc’s render instead of Haunt for now.

I am doing this for a couple of reason. It’s mainly because Pandoc offers a more advanced system for generating diagrams for code blocks. Pandoc also support code highlighting for much more language than Haunt currently support. Lastly, learning about Pandoc is also one of my 2025 goals.

I’m also using GNU Make to build the blog system. It is fine, but a well known thing. Classic example of a boring technology.

Finally, I am attempting to use GNU Guix to manage my dependencies. However, my usage GNU Guix is only partly successful as of Dec 2024.

System Context Diagram

This is a System Context diagram of my blog system. Not super helpful but you can see we are using GitHub to host the blog. Hey, you the reader are there. We are building software with people first.

Container Diagram

This is a Container Diagram for the blogging system. We are using a GitHub git repo for storage, and GitHub’s build system to deploy changes. Pushes to the main branch currently trigger a new build and deploy to “production”.

Dependencies and GNU Guix

I am trying to use Gnu Guix to manage my dependencies. Currently, plantuml and its friends are not working with Guix. For now, I am just using fedora and pipx to manage those dependencies.

## Install pandoc
dnf install pipx plantuml
## Install pandoc filters
pipx install pandoc-plantuml-filter pandoc-include

## Load enviorment with guix
guix shell
## Rebuild the site locally
make build
## Run a local server
haunt serve

This is an example of the current manifest.scm file for this blog. You can see that I am using a commit from github for Haunt. I need a few things that are unreleased in Haunt, so I am pulling it in via git. This is what David’s blog does, and my blog is pinned against the same commit as his.

(use-modules (gnu packages autotools)
             (gnu packages base)
             (gnu packages uml)
             (gnu packages web)
             (gnu packages guile)
             (gnu packages emacs)
             (gnu packages emacs-xyz)
             (gnu packages haskell-xyz)
             (gnu packages guile-xyz)
             (gnu packages pkg-config)
             (gnu packages rsync)
             (gnu packages texinfo)
             (guix git-download)
             (guix packages)
             (guix profiles)
             (guix utils))

(define haunt*
  (let ((commit "2b8268683ad2406b38500cde18210100df67b745"))
    (package
     (inherit haunt)
     (source (origin
              (method git-fetch)
              (uri (git-reference
                    (url "https://git.dthompson.us/haunt.git")
                    (commit commit)))
              (sha256
               (base32
                "1dz0r5lds8dhzvk6x0qslq3q098vcw1ifyr6m27vlk67d5fxgpdm"))))
     (native-inputs
      (list automake autoconf pkg-config texinfo))
     (inputs
      (list rsync guile-3.0-latest))
     (arguments
      (substitute-keyword-arguments (package-arguments haunt)
        ((#:phases phases)
         `(modify-phases ,phases
            (add-after 'unpack 'bootstrap
              (lambda _
                (invoke "sh" "bootstrap"))))))))))

(packages->manifest
 (list guile-3.0-latest
       ;; plantuml This does not work with c4 diagrams because
       ;; plantuml can't seem to access the internet.
       emacs
       emacs-geiser
       emacs-geiser-guile
       pandoc
       jq
       tidy-html
       gnu-make
       haunt*))

That’s most of it for now. Thanks for reading.