Lately, I have been wanting to finally wanting to dive deep into a dynamic language. In the past, I have written a little about Ruby because of Ruby On Rails. While I do like Ruby on Rails, I am not exactly a huge fan of Ruby. It is not bad, but it will still missing something. I have heard quiet a bit about Elixir, but never thought about it until recently. It is a dynamic language like Ruby, but with more a more functional nature. There is also some overlap in the Rust and Elixir fans. So I decided to give it a go being since I do like Rust and Swift, with Swift having some overlap in language features and concept with Rust. Also, I had heard some great things about Phoenix, a web framework inspired by Ruby on Rails, but in Elixir.

At first glance, Elixir looked pretty nice. But you can't really get a feel for a language until you actually start to use it for something. So, being as there is homebrew written in Ruby, I decided to embark on a project to make a little system package manager in Elixir.

Why a package manager?

First a foremost, it has been something I've wanted to try my hand at for a long time. Since I was a young lad trying to bumble my way through LFS (Linux From Scratch). Outside of just doing apt install or yum install or pacman -Ss, I hadn't looked too deeply in package management at the time until LFS and also subsequently checking out Slackware. But that was many moons ago. But, seems like a fun project for Elixir.

Also, as noted, I have a little experience packaging software. In the past, I packaged, or wrote a port in the ports tree, for a few packages in Ravenports (I have some articles about this). Not too long ago, I packaged comtrya for homebrew. You can learn a lot about software development and software by packaging. Just seems like the next level to go for learning more about packaging and distributing software on UNIX-y systems is to now write my own package manager.

In comes spellbook. A witch-y theme package manager written in elixir.

What do I want it to do?

Alright, so now, what does it need to do? Well quiet a bit of it, for anyone with experience using a system package manager, is obvious. It needs to install, uninstall, and search for software. That is kind of the low hanging fruit, so I won't spend much time on that. But specifically how do I want it to do these things?

Right now, I have mostly only thought through the installing. I want to have a ports tree. For those not familiar, a ports tree is a directory of recipies for building packages from source. These recipies cover things like downloading a package's source code and then building it from source. So right now, I am ignoring installing binaries from a repository or grabbing binaries from github or other source. I am putting that off to later. So right now, it will be limited to building from source.

Okay, homebrew kind of does this! First, so what. Technically this is a "competitor" with homebrew, but I am mostly doing this out of fun and for learning. But, there is a future feature that I want to support that it doesn't look like homebrew has. But, it is a feature of Ravenports. As a side tangent, I would love to use Ravenports on macOS (my daily driver now), but it can't support any newer versions because Ravenports relies on nullfs, which is no longer very viable on macOS. At least that is what I remember when I was looking into a few years ago. But that feature is the concept of variants.

Variants in Ravenports are like supporting multiple versions of the same package, but with different feature sets. For those familiar with ebuilds, portage, and gentoo, variants in Ravenports is sort of like customizing your FLAGS. For an example for those not familiar, lets take a package like git. If you build git in the most basic way possible, you get the full package. But if you change some build variables, you can get a lighter version of git. In Ravenports, you can get the git-full or git-lite package. Its your choice. Another example is less. You can build less so it uses colors in it's output, or for less to be colorless. I want to eventually support this idea of variants. But that is a future feature.

What does a port look like

Before going further, lets take a look at a current working sample of a port definition. Or, as it is called in spellbook (a package/port), a spell definition.

defmodule Htop do
  @behaviour Spellbook.Spell

  @impl true
  def name(), do: "htop"
  @impl true
  def version(), do: "3.4.1"
  @impl true
  def homepage(), do: "https://htop.dev"
  @impl true
  def license(), do: "GPL-2.0"
  @impl true
  def type(), do: "bin"
  @impl true
  def checksum(), do: ""
  @impl true
  def deps(), do: []
  @impl true
  def source(), do: "https://github.com/htop-dev/htop/archive/refs/tags/3.4.1.tar.gz"

  @impl true
  def install(args) do
    System.cmd("sh", ["autogen.sh", "--prefix=#{args.prefix}"], cd: args.cwd)
    System.cmd("sh", ["configure", "--prefix=#{args.prefix}"], cd: args.cwd)
    System.cmd("make", [], cd: args.cwd)
    System.cmd("make", ["install"], cd: args.cwd)

    :ok
  end
end

Each spell is a module and it conforms to the Spellbook.Spell behavior, which is sort of like an interface. Quiet a bit of it is just package information like the name, version, license information, and where to get the source.

Then a spell definition needs to implement an install/1 function, these are the build instructions for building the software.

Building the port

To build a port right now, a function is ran that does a few things. First, it creates the 'environment' for building. It does this by creating a temp directory and downloding the package there, then it extracts it's contents. Afterwards, it will construct some environment variables and also create the information that will be injected into install/1 via the args parameter, then the method is called. The method executes it's instructions. Returning from that, need to 'install' it into the right place(s). So this would be some bin folder as an example, which it does by iterating over the build artifacts and creating symlinks to the appropraite spots. That is atleast the tldr of it. So far at least.

Output from a build

 ~/ElixirProjects/spellbook/ [main*] ./spellbook cast ~/ElixirProjects/StandardBookOfSpells/htop.exs
Casting spell: /Users/toddmartin/ElixirProjects/StandardBookOfSpells/htop.exs
Warming up to perform cast...
Casting /Users/toddmartin/ElixirProjects/StandardBookOfSpells/htop.exs
Build directory: /var/folders/vf/7r2g86991c788ppg6zq147r80000gn/T/htop-3.4.1
Now on to something else
Downloading https://github.com/htop-dev/htop/archive/refs/tags/3.4.1.tar.gz to /var/folders/vf/7r2g86991c788ppg6zq147r80000gn/T/htop-3.4.1/3.4.1.tar.gz

22:13:14.923 [debug] redirecting to https://codeload.github.com/htop-dev/htop/tar.gz/refs/tags/3.4.1
Download complete
Extracing /var/folders/vf/7r2g86991c788ppg6zq147r80000gn/T/htop-3.4.1/3.4.1.tar.gz....
Extraction complete: /var/folders/vf/7r2g86991c788ppg6zq147r80000gn/T/htop-3.4.1
autoreconf: export WARNINGS=all
autoreconf: Entering directory '.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force
autoreconf: configure.ac: tracing
autoreconf: configure.ac: not using Libtool
autoreconf: configure.ac: not using Intltool
autoreconf: configure.ac: not using Gtkdoc
autoreconf: running: /opt/homebrew/Cellar/autoconf/2.72/bin/autoconf --force
autoreconf: running: /opt/homebrew/Cellar/autoconf/2.72/bin/autoheader --force
autoreconf: running: automake --add-missing --copy --force-missing
autoreconf: Leaving directory '.'
Successfully installed htop
Linking...
[lib/spellbook/linker.ex:12: Spellbook.Linker.link_spell/2]
base #=> "/opt/spellbook/Spells/htop/3.4.1"

Creating symlink /opt/spellbook/Spells/htop/3.4.1/bin/htop -> /opt/spellbook/bin/htop
Creating symlink /opt/spellbook/Spells/htop/3.4.1/share/man/man1/htop.1 -> /opt/spellbook/share/man/man1/htop.1
Creating symlink /opt/spellbook/Spells/htop/3.4.1/share/pixmaps/htop.png -> /opt/spellbook/share/pixmaps/htop.png
Creating symlink /opt/spellbook/Spells/htop/3.4.1/share/icons/hicolor/scalable/apps/htop.svg -> /opt/spellbook/share/icons/hicolor/scalable/apps/htop.svg
Creating symlink /opt/spellbook/Spells/htop/3.4.1/share/applications/htop.desktop -> /opt/spellbook/share/applications/htop.desktop
Done casting...

As shown above, the build artifacts are in /opt/spellbook/Spells/htop/3.4.1, following a conventions of /opt/spellbook/Spells/<PACKAGE_NAME>/<VERSION>. When symlinking, it will see that there is a bin directory in /opt/spellbook/Spells/htop/3.4.1/bin. It will iterates over the files there and create symlinks in /opt/spellbook/bin.

Going full witch-y with it

Here is a the help menu from spellbook.

 ~/ElixirProjects/spellbook/ [main] ./spellbook
Magical system package manager 0.0.1
Todd Martin
A magical system package manager

USAGE:
    spellbook
    spellbook --version
    spellbook --help
    spellbook help subcommand

SUBCOMMANDS:

    cast            Cast (install) a spell (package)
    dispel          Dispel (uninstall) a spell (package)
    scry            Search for a spell
    grimoire        List casted spells
    reveal          Reveal information about a spell
    renew           Renew your spellbook shelf
    empower         Upgrade a casted spell

As shown above, to install we cast. To list all casted spells, we use the subcommand grimoire which will list all of our casted spells.

 ~/ElixirProjects/spellbook/ [main] ./spellbook help cast
Cast (install) a spell (package)

USAGE:
    cast SPELL
    cast --version
    cast --help

ARGS:

    SPELL        Package

And this is what the /opt/spellbook directory looks like.

 /opt/spellbook/ ls
bin     etc     lib     sbin    share   Shelves Spells

Conclusion

This is still very early days with a lot more left to implement. But all in all, I am enjoying my time with Elixir and as I get further in, I plan to post more about this project. And as I 'live' in Elixir a little but more, I will post more about my experience with that. Afterall, it is hard to really know if you like something until you've lived in it for a bit.

So, I have decided to try maybe proto-tpying a little bit of a tomagotchi clone in Zig. I've got a programming language, now I need some other bits. Obviously, I need to render something, so in walks SDL. Interoping Zig with C code is pretty simple. It is one of the 'promises' of Zig. Why not give it a shot? I will go over some basic on getting started, but not too much indepth. Just setting Zig up to work with SDL and just a few basic things while also talking a little bit about the Zig language. Nothing too complicated or indepth.

Zig <3 C

I've tried experimenting with using SDL with Swift and its a bit of a pain. The libraries which provide wrappers and setting them up takes a bit to read through the documentation on SwiftPM. Rust isn't too bad, but doing things with bindgen is not exactly easy or low effort. Zig though promises it to be pretty smooth.

First things first, need to have SDL on the machine. Another reason why I've had some issues with Swift is that since SDL3 has been around, I've been wanting to use the new hotness with SDL. Why build stuff on SDL2 when SDL3 is available. Granted, I was using it before they started releasing binaries, so I've been compiling it myself. Which SDL provides some good documentation for. Zig makes this easy. It really is just a line or two in the zig.build file and the compiler and build system handles the rest.

exe.linkSystemLibrary("SDL3");
exe.linkSystemLibrary("c");

That is really all there is to it for incorporating it in the build.

Much like Swift with SwiftPM, one thing that I like about Zig is that the build system is essentially defined in Zig itself. Well, with Swift, it might be more fair to say that defining dependencies and how those link and build are defined in Swift.

Setting up a Game struct and the main file.

A lot of examples of Zig with SDL that I have come across have done all the important setup in the main function of main.zig. I didn't want to do this, I wanted to to be somewhat separate. Here is what my zig.main looks like.

const game = @import("game.zig");

pub fn main() !void {
	var g = game.Game.init();
	try g.initialize();
	defer g.destroy();
	try g.run();
}

All of the 'game' logic resides in the game struct and it's methods/functions. The first line is importing the game.zig file which contains the struct and it's associated logic. The main function returns void, but can also return an error. This is almost like fn main() -> Result<()> in Rust. What is does is simple, initialize a Game object, then we try to initialize it. The line after that I will get to in a second, but it is interesting, and then we just try to call the run method on the object.

The defer g.destroy() is interesting. It is used to ensure that resources are cleaned up with no longer needed. I am not fully aware of all of the details around it, but it works a little bit like the destructor on a smart pointer in C++ or the drop trait in Rust. Not exact, but so far, I have been able to get by with thinking about it like that.

I use a different mix of systems. The server this site is hosted on is a Debian VPS. I have two machines. I use some local test servers in my home that are in the form of Mac Minis; one has FreeBSD installed while the other has NetBSD. A desktop that runs Arch linux and a Macbook Pro running macOS. However, I am often using my Macbook Pro.

Having done a little port work for Ravenports on the BSDs and running primarily macOS right now, I have always been interested in Homebrew and how that system works as far as packaging software. Homebrew is also cross platform, however, I have never used it on Linux. Although, it is hard to get deep into packaging and actually doing it without having something to package.

In comes Comtrya. I have not written about it before, but I should write a few articles. Comtrya is an open source project that I have been a contributor of for awhile and that I now am the primary maintainer and do the releases of. I won’t go too much into the details of Comtrya, since that is not the main focus of this writing.

What I will say is that Comtrya is distributed in a few ways. First, it is available in raw binaries under github releases. There is a script that can be curl’d and piped to bash that can pick the right binary and place it accordingly. I am not a huge fan of this method, but it is popular and for what Comtrya can do, I can see the reason why people would want it. Since it is a rust program, it can be gotten via cargo since it is published to crates. Installation can also occur through a small set of package managers. Primarily, before my work here, it was available in the AUR and in Ravenports. Even though I have introduced and maintained ports for Ravenports, I sadly am not the one to introduce Comtrya, or rather ironically. Instead a friend of mine does that, the same friend who introduced me to Comtrya to begin with.

Since I mostly work off macOS now, I figured I should make it available via Homebrew.

Initial work - Making a tap

Before looking too deep into what is needed and the requirements to get it into homebrew core, which will be explained a little later, I decided to make a tap for Comtrya. A tap you can think of as like a repository for a package or packages. If your familiar with Ubuntu’s PPA, it is sort of like that.

A tap also doesn’t have certain restrictions since it isn’t in homebrew-core. In a tap, it is okay to make a tap that just download the binary and places it. Which is the route I went for the tap, go with the easiest and make that available first.

Homebrew and the formula are primarily written in Ruby. Which is a little bit of coincidence since I recently have been using a little Ruby for a website with the Ruby on Rails framework. Packages are defined in Ruby and the recipe to make the package is called a formula. For someone to make use of a formula they just need to tell Homebrew to add the tap, which is like adding a PPA on Ubuntu for apt.

brew tap comtrya/comtrya
brew install comtrya

The formula has some details about the package and can perform some actions. The main action I focus is the install action. As mentioned, the route I went with was just grabbing the binary and installing it.

# Documentation: https://docs.brew.sh/Formula-Cookbook
#            	https://rubydoc.brew.sh/Formula
# PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!
class Comtrya < Formula
  desc "Configuration And Dotfile Management"
  homepage "https://comtrya.dev"
  url "https://github.com/comtrya/comtrya/releases/download/v0.9.0/comtrya-aarch64-apple-darwin"
  sha256 "1ca79b45a9c6cd91654fefe47a22fcfdfee7d05bb792b69e39e35e9d396dad6e"
  license "MIT"
  version "0.9.0"

  def install
	bin.install "comtrya-aarch64-apple-darwin" => "comtrya"
  end
end

It is that simple. There are a few drawbacks here. It only pulls the aarch64 build for macOS. So this would not work on a x86_64 macOS machine or linux. So pretty much only apple silicon. But, this was just getting a little bit of experience before looking into the requirement for homebrew-core.

The repository for the tap is located on github under Comtrya's organization.

Getting into homebrew-core

Homebrew has what is called “homebrew-core.” This is pretty much the official repository. The main requirement that comes into play for me to get Comtrya packaged is that, for a package to make it in, the formula must handle building the application from source. There are also some quality controls that are required also.

To get an idea of how to do with rust, I took quiet a bit of inspiration from ripgrep, which is already in homebrew-core. Rust programs can be a bit of a beast to get into a ports tree or package manager depending on the philosophy. For instance, I believe Debian and FreeBSD’s ports tree want the package definition to be able to build itself, but also all of its dependencies with their package definitions to build the dependencies locally. Ravenports sort of does to, but a special short cut has been cut out for Rust programs and Go programs (with go mod). So taking Comtrya as an example, the last number I remember was somewhere in the ballpark of 387 dependencies. This includes transitive dependencies. Needing to bring in 387 recipes or package definitions isn’t fun, long and grueling work. Luckily, Homebrew does not require this. I don’t need to first package each dependency and make sure the versions are compatible, we can just trust the maker (in this case me) and cargo to do the right thing.

class Comtrya < Formula
  desc "Configuration and dotfile management tool"
  homepage "https://comtrya.dev"
  url "https://github.com/comtrya/comtrya/archive/refs/tags/v0.9.0.tar.gz"
  sha256 "a5401004a92621057dab164db06ddf3ddb6a65f6cb2c7c4208a689decc404ad4"
  license "MIT"
  head "https://github.com/comtrya/comtrya.git", branch: "main"

  bottle do
	sha256 cellar: :any_skip_relocation, arm64_sequoia: "56bcd6407ac6f14a3ba79414c0651e52a2e262ce16b1148c70abc2ac1a121ead"
	sha256 cellar: :any_skip_relocation, arm64_sonoma:  "6686fa03d6d26a52beb6db4aa60d1dc51dfe34fda8e490d65c0ed96ee1adf883"
	sha256 cellar: :any_skip_relocation, arm64_ventura: "eaed784b320caf01dbf1130b956a34d5bf75d93c09555d9d5c3cdc799de13cad"
	sha256 cellar: :any_skip_relocation, sonoma:    	"846c88f71d195eb80fe7a33024cd985bcd023455a6d2e52582e66b6a40613adc"
	sha256 cellar: :any_skip_relocation, ventura:   	"ca956905d382263bc9ce55ddcda6f57612565322d33aa918621fe24e744f565e"
	sha256 cellar: :any_skip_relocation, x86_64_linux:  "635873d62afde5a0e0e100273ec87da7d4d6bc3ee74f59c894bf7e8d346b3b77"
  end

  depends_on "rust" => :build

  def install
	system "cargo", "install", *std_cargo_args(path: "./app")
  end

  test do
	assert_match "comtrya #{version}", shell_output("#{bin}/comtrya --version")

	resource "testmanifest" do
  	url "https://raw.githubusercontent.com/comtrya/comtrya/refs/heads/main/examples/onlyvariants/main.yaml"
  	sha256 "0715e12cbbb95c8d6c36bb02ae4b49f9fa479e2f28356b8c1f3b5adfb000b93f"
	end

	resource("testmanifest").stage do
  	system bin/"comtrya", "-d", "main.yaml", "apply"
	end
  end
end

Above is the formula that is now in homebrew-core. As mentioned, we can just trust the maker and cargo to do the right thing. Defining rust as a build dependency pulls down all the rust tooling, including cargo, to build the package. Then building the package is as simple as invoking cargo to install.

One area I had an issue with that referencing ripgrep wasn’t much of a help with is how to build Comtrya for homebrew with it having workspaces and how the workspace are set up. The binary application is the app. There is also a lib that is built for the library crate and jsonschema crate. I did have to tell cargo to build specifically the app to successfully compile Comtrya with homebrew from source. From there, Homebrew's tooling takes care of most of it, including placing the binary in the appropriate place on each system. Since it is built from source, this package should technically work on any platform that homebrew supports.

As mentioned, there is some quality control that is required here. That is the test section. Each package that is being introduced into homebrew has to have at least one test. The general rule of thumb is that the test needs to flex how the application is used and should not just be a version check.

In my test, I do run a version check. But I also pull down a resource, a test manifest and have Comtrya apply the manifest. The test passes so long as Comtrya doesn’t throw an error when running it.

And of course, now Comtrya is officially avaible in hombrew-core.

Interacting with the maintainers of Homebrew

I found them to be helpful and pretty welcoming. There were some issues I had to fix. First was styling. Homebrew does have a tool that will help fix the styling similar to how cargo’s fmt works. Also a little bit of guidance of what is expected with tests. It was also handy to look at other recently closed pull requests and pending pull requests to see if there was anything I was missing.

So, I decided to take a bit of a step back and focus on perhaps a simpler engine. One that is more like a Wolfenstien-esque style engine. So 2D that fakes 3D via ray tracing. Plus, there are tons of reference material and posts to read about why various design choices are made regarding a Wolfenstein style engine. And of course, I want to do it in Swift.

Initially my plan was to stick with UIKit or SwiftUI, but then I figured, well, why not just use SDL? Especially since SDL3 is sorta out right now. Well, looking at the repository, there are not official tags, but the 'main' branch is essentailly SDL3. Plus, it will simplify some things since I am not well versed in UIKit. Plus, SDL is also more cross platform. Perhaps getting back into dabbling with SDL, I can stick with SDL when I get back to Flatland to render using Metal. Or use a software renderer as a stepping stone for the design of the rendering engine with an Apple Metal backend. TBut the cross-platformness of SDL would be great because I would also be able to use this on Linux. And not going to lie, I am secrely hoping I wake up one day to find that there is some upstream support for FreeBSD/NetBSD for Swift.

However, this presents a little bit of a problem. The current libraries available via Swift Package Manager (SPM) are a mix of either out of date, or still only target SDL2. So, guess what? I guess I need to make my own package to wrap SDL3.

So first things first, how do we do this? Well, Swift does provide a guide, so lets follow along and see how it goes.

I create my folder.

mkdir SwiftDL3

Then time to navigate into it and initialize a new library package.

cd SwiftDL3
swift package init --type library --name SwiftDL3

Now, I have the skeleton for the project. A few more things to do before really digging in.

Unfortunately, it doesn't appear to initialize a git repositority for us and that will be important with as per the instructions, we need to use a git submodule. Or atleast, that is route I plan to go.

git init

Also I don't quiet like the SwiftDL2.swift file, so I want to get rid of that.

rm Sources/SwiftDL3/SwiftDL3.swift

Now, nagivate into the folder for the library and add our git submodule

cd Sources/SwiftDL3
git submodule add https://github.com/libsdl-org/SDL.git

Once that is done cloning, verify the .gitmodules file.

cat ../../.gitmodules
[submodule "Sources/SwiftDL3/SDL"]
	path = Sources/SwiftDL3/SDL
	url = https://github.com/libsdl-org/SDL.git

Looks good so far.

cd ../../

Let take a look at the current Package.Swift file.

// swift-tools-version: 5.10
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "SwiftDL3",
    products: [
        // Products define the executables and libraries a package produces, making them visible to other packages.
        .library(
            name: "SwiftDL3",
            targets: ["SwiftDL3"]),
    ],
    targets: [
        // Targets are the basic building blocks of a package, defining a module or a test suite.
        // Targets can depend on other targets in this package and products from dependencies.
        .target(
            name: "SwiftDL3"),
        .testTarget(
            name: "SwiftDL3Tests",
            dependencies: ["SwiftDL3"]),
    ]
)

Let try just running this.

swift build

Looks like I already hit an error.

error: 'swiftdl3': manifest property 'defaultLocalization' not set; it is required in the presence of localized resources

Doing a quick google search, I found a page that provided a problem. Lets just add this to the Package.swift.

defaultLocalization: "en",

Building now results in a different error.

warning: 'swiftdl3': 'SwiftDL3' was identified as an executable target given the presence of a 'main.swift' file. Starting with tools version 5.4.0 executable targets should be declared as 'executableTarget()'
error: 'swiftdl3': library product 'SwiftDL3' should not contain executable targets (it has 'SwiftDL3')

Seems a little odd that the simpiler is thinking it is an executable target and not a library. Especially since there is not a main.swift file.

Making some edits to the package file. It looks like I have some progress.

// swift-tools-version: 5.10
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  name: "SwiftDL3",
  defaultLocalization: "en",
    products: [
        // Products define the executables and libraries a package produces, making them visible to other packages.
        .library(
            name: "SwiftDL3",
            targets: ["SwiftDL3"]),
    ],
    targets: [
        .target(
          name: "SwiftDL3",
          dependencies: [],
          exclude: [],
          sources: [],
          cSettings: []
        ),
    ]
)

Now, I get the following error when building.

error: 'swiftdl3': public headers ("include") directory path for 'SwiftDL3' is invalid or not contained in the target

After reading some documentation and playing around, it looks like I've got something compiling. Lets take a look at the files.

// swift-tools-version: 5.10
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  name: "SwiftDL3",
  defaultLocalization: "en",
    products: [
        // Products define the executables and libraries a package produces, making them visible to other packages.
        .library(
            name: "SwiftDL3",
            targets: ["SwiftDL3"]),
    ],
    targets: [
        .target(
          name: "SwiftDL3",
          dependencies: [],
          exclude: [],
          sources: [],
          publicHeadersPath: "SDL/include/SDL3",
          cSettings: []
        ),
    ]
)

I also modified the .gitmodules file to the following.

[submodule "SDL"]
	path = Sources/SwiftDL3/SDL
	url = https://github.com/libsdl-org/SDL.git

Now for the moment of truth. To see if it can be using in an actual executable.

Naviagting out of the directory for this, I will create a new folder and project within it. Then I plan to map SwiftDL3 as a dependency on my local file system.

cd ../
mkdir SwiftDL3Test
cd SwiftDL3Test
swift package init --type executable --name SwiftDL3Test

About a little over a month ago, the video for DHH's keynote talk at the Ruby on Rails conference caught my eye. I don't really do a whole lot of web development. This blog I have been throwing together with static site generators and now the current iteration as of this writing is in the Astro framework. Ultimately, most of my 'web application' experience has been using static generators and a few tutorials every once in awhile when I get an itch with react. But DHH's talk caught my attention. First, I have always been a little curious of just seeing what Ruby on Rails is. I have heard it a lot, but have never really looked at the code. Second, it seems like a perfect match for a web development idiot like myself. I can learn web development, but I always run into an issue with, I read some documents and do some tutorials, but I never have a serious project to do with it.

Well, that is not entirely true. but for the most part it is. I technically did a little bit of a web development project at work where I had to modify an old ASP.NET MVC that probably had not been touched in 4 or 5 years to allow for a new feature. However, I did not have to do much with the UI, it was mostly adjusting the controllers and some of the logic within them. Still, I don't necessarily count that.

How I got here

As timing would have it, a project came along right around the time I listened to this talk. My father in law recently took over his dad's business doing carpet cleaning and with that, taking over the website and such. While out visiting, he said he had some struggles. He isn't very tech literate either. I told him I can take a look and see if I can help. After all, I am a software engineer. So he pointed me to it and well, it was Godaddy. By Godaddy, I mean the domain is registered through GoDaddy and his site was thrown together by another family member via their point and click UI to build a site.

Now, I am not a huge fan of those interfaces. Maybe, its because I write software. Maybe, it is because I have been a user of Linux and other Unix system since when you had to custom compile kernels if you wanted your WiFi to work. I am much more comfortable dealing with text and not dragging and clicking. Also, he was paying somewhere northwards of $400 a year for a domain, hosting a pretty simple site, and an email plan I guess he got suckered into that he never plans to use. So, I told him I could play around with some stuff, but if I am going to do any work on it, the drag and drop website builder has to go.

So, now I had a project, and I just recently learned about a new framework.

How it turned out

Before going too deep into details and talking about how I solved some problems, I will get to the conclusion on how this went. My father in law has a new website hosted on a server I rent for other projects and it does everything it does. The server I rent has way more capacity than needed, so it doesn't really cost me anything to host it for him. It also saves him some money. He offered, but as I explained to him, whether or not his site is on it, I'd be paying for it anyways. Plus, I considered his payment for my service being his giving me a problem and a project I have been on the look out for, for awhile.

Give me the dirty details on working with Ruby on Rails

So far, I feel like DHH makes a promise and that for the most part is true. That promise is a framework that makes it easy to work in once you get the hang of it. Also allowing a person to be a one person team. Which was perfect for this project. Instead of starting with 7.2, I started his website using 8.0.0-beta and living with it through upgrading it from 8.0.0-RC1 to 8.0.0-RC2 and recently upgrading it to 8.0.0.

Why start with Beta

The main attraction was the authentication generation. I didn't really want to have to deal with something like firebase's auth or an external auth and relying on a free teir plan. There is nothing wrong with utilizing the free tiers, but it is also nice that I never have to worry about a rug pull. Granted, for users, his site could have probably sat in a free teir for forever. That is because as of right now, the authentication just gives access to a dashboard with functionality for him and my mother in law. Also myself just to double check things in production. So, at most 3 users roughly?

The scripts for authentication were as good as promised I feel. It pretty much took care of all of that auth without me having to tear too much into implementation and RFCs if I were going to roll my own or learning how to work with an auth provider. In about 5 minutes, I had a working authentication system.

The only part of auth that took me a little bit of reading to work with was how to specify which pages don't require auth. Now, I am still not an expert, but from what I have seen, when you use the generate authentication system, it automatically assumes that every page, or at least pages produced by controllers, require a valid session token. To have a controller not require a session token, a declaration needs to be made after the class definition.

allow_unauthenticated_access

A design I was somewhat familiar with

Ruby on Rails makes use of the MVC (Model-View-Controller) pattern which I was already familiar with from a little bit of work I did on an ASP.NET project at work, it is the one mentioned at the beginning of this article.

Don't consider this an endorsement of MVC. I do not do enough web development to know if MVC is a superior patterns to other. I do know that Angular is based on an MVC pattern. In this case, it is just a pattern that I had seen before and technically worked with before when working on a website.

Mailers

This project was going to need some functionality with email. As of right now, there are three main use cases for working with email. First, supporting the 'forgot password' functionality in the authentication system. Luckily, if the email server settings are configured, the auth generation provided by rails pretty much does this for you. Nothing to do, it just rather works without a thought. Next, I built the ability for my father-in-law to have a sort of newsletter. This he can leverage pretty well. He lives pretty far north so for winter, the business shuts down because the equipment will freeze. At the very least, he can have a sort of newsletter to notify people when he will be closing down or opening up depending on the season. People can subscribe on the homepage of his site by inputting in their email. An email is fired off to confirm subscription. Then, from the dashboard, I built an area where he can input a subject and email contents to send out to everyone on the list. Right now, it is pretty bare bones, but it is a start. I need to guide him through, and make he knows, he can make requests and I will work on them. Or in other words, coming up with requirements that will help him better.

Mailers is probably a killer feature of Ruby on Rails. It just makes it easy. I have some experience of the hell with working with email from work. There is a lot to be said about SMTP, but I'll try not to air those grievances here. Like auth, rails can generate quiet a bit for you and also splits it into an MVC like pattern. A controller can control when and how emails are sent. Views are present that are the template for the email to be sent. Then configuring the email server is pretty straight forward from looking at the documentation. There is also a lot of stack overflow, blog posts, and other resources to help with this.

Conclusion

All around, I am pretty happy with it. For a solo developer working on a project and needing a simple authentication system and mailers, Ruby on Rails makes it easy and I would recommend it.

Fast forward to today. As mentioned, I've been playing around with game development. Starting today, I am doing my first game jam. If your unfamiliar with what that is, it is a competition where you implement a game within a set time period. That is at least the simple explanation, mile high view. However, I have a little twist on this. My son, who is 8, has been asking me to make a game with him. So I decided that we would try to do that during this game jam.

Today starts the 'So Bad It's Good' game jam. The rules are simple.

• Try to make something fun
• It can be original or based off an existing IP
• Use whatever you like, however many people
• Games must be made during the jam period

So, here is the plan of attack.

It is up to my son to design the high level parts of the game. This is the story line, game mechanics, rough idea of the assets, all of that. I will help some with narrowing his focus. I will take care of the programming and essentially everything that needs to be done on the computer. From there, we've got 8 days to slap something together that it hopefully fun.

For tech stack. I started working on my own library in Swift that uses Metal called 'Flatland.' However, due to some other side projects, I wasn't able to get it where I feel confident enough to live in it for 8 days. So over the last couple of day, I have pivoted on my tooling. My plan is to use a small project called AdaEngine to implement the game. The benefit is, AdaEngine appears to be architected in a way I was shooting for for Flatland. But also, it'll give me an idea of what kind of interfaces and such that I want to eventually bring into Flatland. So the tech stack is simple. Swift and Apple Metal using AdaEngine, targeting macOS.

My plan is to try to document my process and progress over the course of the game jam.

Terminal based UIs have always held a certain fascination with me. They can be incredibly functional while also, at least from looks, being incredibly minimal. There is also something beutiful about a simple terminal UI. In a previous article I played around with crossterm in Rust and recently thought, huh, wonder what it would be like with Swift. This also gave me the change to play with some lower level things in Swift that so far, most of my tinkering has not lead me to. This got me to look at pointers and some unicode encoding.

Unlike with Rust where I used crossterm, I decided not to use a library that abstracts all the nitty gritty details of the terminal. Instead, I will be placing the terminal into raw mode and drawing without too many abstractions on top. The place to begin, is by looking at termios. Termios, for those who are unaware, well, I will just copy and past it from the FreeBSD man pages.

This describes a general terminal line discipline that is supported on tty asynchronous communication ports.

This can be thought of as the low level settings for the terminal. Not things like fonts or colors, but instead how the terminal actually functions at a deeper level. In case your wondering why I pulled the FreeBSD man page for this, lots of userland utilities on macOS come from the BSDs. You can see this when you run 'man termios' in iterm or the macOS terminal and go down to the bottom. It pretty much is the FreeBSD man page. Also, termios is a pretty generic structure, as in, most unix-like systems all have pretty much the same struct with same settings. So, this code should not only work on macOS, but also Linux and the BSDs.

Here is what I get after running my code in the terminal. Only this.

┏━━━━━━━━━━━━━━━━━━━┓
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┃                   ┃
┗━━━━━━━━━━━━━━━━━━━┛

A simple box, but it takes a bit of code to get there, so lets jump in.

First things first, it is better to work off of the FreeBSD documentation or using the man page in macOS, which is essentially the FreeBSD man page. Online, the documentation apple gives is can be found here. It doesn't tell me too much other than the termios structure is rather accessible to me without any weird imports. Importing the Foundation should be good enough.

Main method

Next, take a look at the main method, it is fairly straight forward, from there, I will jump into the methods thar are called.

import Foundation

func main() {
  let fd = STDIN_FILENO
  var tio: termios = termios()
  enableRawMode(fd: fd, orig_termios: &tio)
  clearScreen(fd: fd)
  let box = Box(x: 1, y: 1, width: 20, height: 10)
  box.draw()
  while true {
    var buf: UInt8 = 0
    let readResult = read(fd, &buf, 1)
    if readResult < 0 {
      fatalError()
    } else if readResult == 0 {
      break
    } else {
      assert(readResult == 1)
      print(buf)
    }
    if buf == Character("q").asciiValue! {
      break
    }
  }
  disableRawMode(fd: fd, tio: &tio)
}

main()

The main.swift file serves as the main entry point and is written a little like a script this way. So my main method needs to be called. If we don't want to have to directly invoke main, you need to put the main method in a class or structure and use an attribute of @main to do it. I didn't feel it necessary to this here, at least not yet. In the main method, I get the file descripter for STDIN_FILENO, which is the terminal for our purposes. Creating an instance of the termios structure and placing it into a mutable variable named tio. Then, enable raw mode (will get to this later). After that, clear out the screen, make the box and draw it. From there, loop on input, the important part here is that this will infinitely loop unless the user presses the letter q, there is some error handling also. When q is typed, break the loop and disable raw mode. Now, lets get to the fun bits.

Enabling Raw Mode

func enableRawMode(fd: Int32, orig_termios: UnsafeMutablePointer<termios>) {
  guard isatty(fd) != 0 else { fatalError() }
  // get the original terminal settings
  guard tcgetattr(fd, &orig_termios.pointee) >= 0 else  {
    fatalError("Issue initializing termina")
  }
  var tio = orig_termios.pointee
  tio.c_iflag &= ~UInt(IXON | ICRNL | ISTRIP | BRKINT)
  tio.c_oflag &= ~UInt(OPOST)
  tio.c_cflag &= ~UInt(CS8)
  tio.c_lflag &= ~UInt(ICANON | ECHO | ISIG | IEXTEN)
  guard tcsetattr(fd, TCSAFLUSH, &tio) >= 0 else {
    fatalError("Issue initializing terminal")
  }
  tcflush(fd, TCIOFLUSH)
}

Enabling raw mode is one of the important functions at play here. We can consider when a terminal is initially launched, it is in 'cooked mode.' That is sort of the default. Raw mode entails disabling some processing and allowing us to pass input directly to the program running in the terminal rather allowing some default processing to happen. That is a quick birds eye view. These settings are changed by mutating the termios structure.

The arguments are an Int32 named fd (file descriptor) and a rather weird one, UnsafeMutablePointer of type termios named orig termios. File decsriptor is fairly straight forward, but the second one, not so much. Swift allows pointers and there are several kinds, and they are typed via generics. UnsafeMutablePointer is a generic that we can provide the unerlying type. The variable is named orig_termios since we are passing in the termios structure from main and this will be used to get and sort of stash the current settings the terminal operates on by default. This helps later when exiting raw mode and restoring back to where we were.

The first line calls a function in a guard statement to check if is atty. This function takes in a file descriptor and just checks if the file descripter points to a terminal. This is a guard so we don't try to pass in a filed descriptor for something like a simple text file named hello.txt. This should fail and throw the fatalError.

Following that is the tcgetattr function. This is how I get the original terminal settings. Or should I say, the termios structure that is tied to STDIN_FILENO tty. It works by passing in the file descriptor and a termios structure. I dereference the termios structurewith &orig termios.pointee. UnsafeMutablePointer is like a wrapper. To get to the value within, we must dereference it's pointee property within. Should this fall fail, a fatalError is thrown.

A new instance of a termios structure is created copying the data in the orig_termios. It is dereferenced via the UnsafeMutablePointer's pointee. Following that is to manipulate the data within the new instance of termios by setting the flags. Each of these modes are described in detail in the man pages. Quiet a few of them disable processing of things like hitting Ctrl + C. Some hvae to deal with echoing and more. The man page is an interesting read and I really recommend you giving it a read.

Then, we need to do something with tio. We need the terminal to now use it for it's tty settings. This is done with tcsetattr. This function takes our file descriptor for the terminal, an action, and the reference to the termios struct we want to put there. The action parameter determines when this change takes place. There are three options; TCSAFLUSH, TCSANOW, and TCSADRAIN. I opted for TCSAFLUSH which is described as

The change occurs after all output written to fd has been transmitted to the terminal. Additionally, any input that has been received but not read is discarded.

Finally, calling flush on the file descriptor with tcflush. Once this is done, the new terminal settings will take affect. This also takes an action, which is described in the man page as

Flush both data received but not read and data written but not transmitted.

Diabling Raw Mode

Jumping ahead, now lets look at disabling raw mode.

func disableRawMode(fd: Int32, tio: UnsafeMutablePointer<termios>) {
  guard tcsetattr(fd, TCSAFLUSH, &tio.pointee) >= 0 else {
    fatalError("Issue disabling raw mode")
  }
}

This is needed to get back to the original settings when the program is being exited. Here the UnsafeMutablePointer for the original termios structure reappears. Inside the function, like when setting the termios structure to disable settings, the termios restructure will be set back to the original settings we saved earlier. If you've got a grip on enabling raw mode, disabling it is easy and simple.

Box Structure

The box to draw is a simple swift structure. This is some of the code for it.

struct Box {
  var x: Int16
  var y: Int16
  var width: Int16
  var height: Int16

init(x: Int16, y: Int16, width: Int16, height: Int16) { self.x = x self.y = y self.width = width self.height = height } } This is the base of the structure. For now, I left out the drawing code just to give a demonstration of the data I am working with. This structure has an x and y as a starting point. This serves as the upper left hand corner of the box. I guess, technically rectangle since it's sides can be variable length. Then the box has a height and a width. An intializer (constructor in non swift languages) is provided just to initialze the box with its values.

Helper functions

Before drawing a box, it is good to talk about some helper functions.

import Foundation

func writeToTerminal(fd: Int32, message: String) {
  write(fd, message, message.utf8.count)
}

func jumpToPosition(fd: Int32, x: Int16, y: Int16) {
  writeToTerminal(fd: fd, message: "\u{1b}[\(x);\(y)H")
}

These are the helper functions for drawing. Two simple functions are needed; writing to terminal and jumping to position. Jumping to position is where we tell the cursor to go on the screen, then from there, we can write linearly along that row. Jump position is an abstraction over writing to the terminal since to do anything, we must write to the terminal. Jump to terminal just formats what we write as the escape sequence to jump the cursor. So instead of writing physical text on the screen, this can be seen as a command to the terminal or a function.

To break down the commands a little, since they look a little weird. Some excellent documentation can be found here. For jumping, a focus is on the function in the article described as 'Cursor Position'. The command written to the terminal looks like

\x1b[x;yH

Or using a point such as (1,1)

\x1b[1;1H

However, swift, I found to be a little funky here. I couldn't simple pass in 'x1b' because I kept getting errors related to an invalid escape sequence. What I found usefule is to use the unicode escape sequence, which luckily evaluates out to the same hex code. the x specifies that the input is hex and the actual escape code is #1B. So instead, using (1,1), for us it looks like

\u1b[1;1H

Writing to the terminal is simple, pass the file descriptor, message and the length of the message by calling on the message's utf8 count property.

Back to Main: ClearScreen

Now with that described, we can address the clearScreen method in main.

func clearScreen(fd: Int32) {
  writeToTerminal(fd: fd, message: "\u{1b}[2J")
}

I will leave it up to you to figure out what that command does using the documentation linked above. One hint.

\x1b[2J

Drawing the Box

Finally drawing the box, here is the complete code for the Box structure.

import Foundation

struct Box {
  var x: Int16
  var y: Int16
  var width: Int16
  var height: Int16
  init(x: Int16, y: Int16, width: Int16, height: Int16) {
    self.x = x
    self.y = y
    self.width = width
    self.height = height
  }
  func draw() {
    jumpToPosition(fd: STDIN_FILENO, x: self.x, y: self.y+1)
    for _ in x...x+width-1 {
      writeToTerminal(fd: STDIN_FILENO, message: "\u{2501}")
    } 
    jumpToPosition(fd: STDIN_FILENO, x: x + height, y: y)
    for _ in x...x+width-1 {
      writeToTerminal(fd: STDIN_FILENO, message: "\u{2501}")
    }
    jumpToPosition(fd: STDIN_FILENO, x: self.x, y: self.y + width)
    writeToTerminal(fd: STDIN_FILENO, message: "\u{2513}")
    jumpToPosition(fd: STDIN_FILENO, x: self.x, y: self.y)
    writeToTerminal(fd: STDIN_FILENO, message: "\u{250f}")
    for i in x+1...x+height-1 {
      jumpToPosition(fd: STDIN_FILENO, x: i, y: self.y)
      writeToTerminal(fd: STDIN_FILENO, message: "\u{2503}")
    }
    jumpToPosition(fd: STDIN_FILENO, x: self.x + height, y: self.y)
    writeToTerminal(fd: STDIN_FILENO, message: "\u{2517}")
    jumpToPosition(fd: STDIN_FILENO, x: self.x+height, y: self.y + width)
    writeToTerminal(fd: STDIN_FILENO, message: "\u{251b}")
    for i in x+1...x+height-1 {
      jumpToPosition(fd: STDIN_FILENO, x: i, y: self.y+width)
      writeToTerminal(fd: STDIN_FILENO, message: "\u{2503}")
    }
  }
}

The addition is the draw function which will render the box to the terminal, taking advanatage of the helper functions to jump to position and write. The algorithm is simple, draw a side and move to another side, occasionally jumping to corners of the box and drawing the corner.

Conclusion

That is the code to draw a box in the terminal in swift. Through it, the terminal was placed into raw mode, and drew the box. Input was polled on the q character, break from the polling and disable raw mode, returning the terminal back to it's original set up.

As seen from previous posts, I have taken to dabbling with Swift on my M1 MacBook Air running MacOS. Now, it is time to take a look at how swift does on Linux. I believe Swift is an interesting language that can bring a rather unique value proposition. As someone who has written Rust for open sourced projects and professionally (for a paycheck) C#, Swift strikes a really interesting balance. In Rust, I sometimes end up at a point where I am tackling a problem and I am thinking to myself, "if only I had X from C# to do this." And likewise, in C# (especailly when it comes to errors and enums), I hit a situation where I look at something and go, "if I only I had Y from Rust." Swift, seems to be able to strike that balance some. It has the features of C# I want while also have quiet a few (not all) of the features of Rust I want. So I tend to describe it as, it is a perfect middle ground (or at least the best middel ground present) between C# and Rust.

Creating an initial project on Linux

My main linux machine right now is running Fedora 37. Swift has been in the main repositories of Fedora for awhile. So getting Swift 5.8 was as simple as invoking the package manager.

sudo dnf install swift

Now, with the basic tool chain installed, it is time to get to work. I create a work space, which was just a folder called "Hello." Navigating inside of that folder, time to invoke swift to create the project essentially.

swift package init --type executable

This is just to create a simple executable package. Which gives me a little folder structure and a main.swift file.

// The Swift Programming Language
// https://docs.swift.org/swift-book

print("Hello, world!")

Just a simple hello world. First, to see if it actually works.

swift build

Okay, it compiles fine apparently. Now, how about running?

swift run

Look like it can at least run a hello world.

╭─todd@fedora ~/Learning/Swift/Hello 
╰─$ swift run
warning: 'hello': warning: direct reference to protected function `$sSJ12isWhitespaceSbvg' in `/usr/libexec/swift/5.8/bin/../lib/swift/linux/libswiftCore.so' may break pointer equality
Building for debugging...
Build complete! (0.08s)
Hello, world!

Looks like we have lift off.

Package.swift

Creating the project also gives us a Package.swift file. Which, at least shown what we are given, defines some simple things about the package. This is also, I believe, how 3rd party packages can be pulled in. From my understanding, you can do something like define dependencies by linking to their git repos and even specify a release from the repo and during the build phase, it will pull in the code and compile it with the application. Like with all good Linux applications, we need a command line interface, so I will use this as an opportunity to try this out.

There is a library, apparently from a google employee, that help provides a nice way to help build a command line driven program called CommandlineKit. Unfortunatley, the github repo also appears to make mention of Swift 5.5, but lets hope versioning is on my side here. The current version Fedora has is 5.8 (5.9 should be out with WWDC just happening). So, lets hope it is compatible.

// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  name: "Hello",
  dependencies: [
      .package(url: "https://github.com/jordanbaird/Prism", from: "0.1.2"),
  ],
  targets: [
      // Targets are the basic building blocks of a package, defining a module or a test suite.
      // Targets can depend on other targets in this package and products from dependencies.
      .executableTarget(
          name: "Hello",
          dependencies: ["Prism"],
          path: "Sources"),
  ]
)

Alright, so far, I am impressed. When I first looked at this file, I didn't pay much attention to it, but adding a dependency made me actually look at it and see something here. This file defines the package, duh. However, the package is just defined like a struct in Swift. I like this a lot. When the build system is essentially written in the language itself. This is something zig does with zig.build. Rust does have a build.rs but you still have a Cargo.toml file, which is good, but its not optimal. C# has solution and csproj files which are XML/XAML/XML-like (YUK!).

I think coloring can look pretty good for a command line utility, so Prism is a nice package that looks like it can give some coloring.

// The Swift Programming Language
// https://docs.swift.org/swift-book

import Prism

let text = Prism(spacing: .spaces) {
  ForegroundColor(.green, "This text's color is green")
}

print(text)

It does indeed print the text as green.

Now, lets get some text from the command line and run it.

// The Swift Programming Language
// https://docs.swift.org/swift-book

import Prism
import Foundation

if CommandLine.arguments.isEmpty {
  print(Prism(spacing: .spaces) {
      ForegroundColor(.red, "No input into program")
  })
}

for argument in CommandLine.arguments {
  print(Prism(spacing: .spaces) {
      ForegroundColor(.green, "Arg: \(argument)")
  })
}

╭─todd@fedora ~/Learning/Swift/Hello 
╰─$ ./.build/x86_64-unknown-linux-gnu/debug/Hello hello
Arg: ./.build/x86_64-unknown-linux-gnu/debug/Hello
Arg: hello

So, interestingly enough, there will always be atleast one argument. We also need to ensure we run the program from the debug folder. Using swift run and trying to pass in arguments doesnt work.

To tame, this a little more, there is a nice library that is available called Swift-CommandLineKit. This also introduces in how to do the package.swift file to entertain more than a single dependency.

// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
  name: "Hello",
  products: [
      .executable(name: "Hello", targets: ["Hello"])
  ],
  dependencies: [
    .package(url: "https://github.com/jordanbaird/Prism", from: "0.1.2"),
    .package(url: "https://github.com/objecthub/swift-commandlinekit", from: "0.3.5")
  ],
  targets: [
      // Targets are the basic building blocks of a package, defining a module or a test suite.
      // Targets can depend on other targets in this package and products from dependencies.
      .executableTarget(
          name: "Hello",
          dependencies: [
            .product(name: "Prism", package: "Prism"),
            .product(name: "CommandLineKit", package: "swift-commandlinekit")
          ],
          path: "Sources"),
  ]
)

Now that is sorted, how about something a little more proper?

// The Swift Programming Language
// https://docs.swift.org/swift-book

import CommandLineKit
import Foundation
import Prism

var flags = Flags()

let help = flags.option("h", "help", description: "Show description of usage.")

try flags.parse()

if help.wasSet {
  print(Prism(spacing: .spaces) {
            ForegroundColor(.red, "hello")
  })
}

Look like it works so far. However, I want to print the actual flag description. I will change out the string that is printed from ForegroundColor.

print(Prism(spacing: .spaces) {
  ForegroundColor(.red, "\(flags.usageDescription())")
})

Here is the output

╭─todd@fedora ~/Learning/Swift/Hello 
╰─$ ./.build/x86_64-unknown-linux-gnu/debug/Hello -h
USAGE: Hello [<option> ...] [--] [<arg> ...]
OPTIONS:
  -h, --help
    Show description of usage.

Alright, looks like I am getting somewhere. Now to do something a little useful. One thing I am excited to try out eventually is Vapor, however before going there, it would be a good idea to make sure any networking at all works as it should. I assume it does, but Swift is such an Apple focused language, there is a chance that perhaps things don't work exactly as they should. So, my plan is to add a REST API call to a free HTTP REST API for a deck of card. There will be a new flag which will be called 'new' that will request a new deck from the API. I am not going to worry about actually deserializing the returned JSON, just make the call and ensure that I get back a 200 OK response.

The following is the endpoint to hit.

https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1

Here is the code

// The Swift Programming Language
// https://docs.swift.org/swift-book

import CommandLineKit
import Foundation
import FoundationNetworking
import Prism

var flags = Flags()

let help = flags.option("h", "help", description: "Show description of usage.")

let newDeck = flags.option("n", "new", description: "Request a new deck.")

try flags.parse()

if help.wasSet {
  print(Prism(spacing: .spaces) {
            ForegroundColor(.yellow, "\(flags.usageDescription())")
        })
  exit(0);
}

if newDeck.wasSet {
  let semaphore = DispatchSemaphore(value: 0)
  
  guard let url = URL(string: "https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1") else {
      print(Prism(spacing: .spaces) {
                ForegroundColor(.red, "Error making url")
            })
      exit(0)
  }

let task = URLSession.shared.dataTask(with: url) {
    (data, response, error) in
    guard let data = data, error == nil else {
        fatalError(error!.localizedDescription)
    }
    print("Error: \(String(describing: response))")
    print("Fetched data size: \(data)")
    semaphore.signal()
}

task.resume() semaphore.wait() } Lets do a diff to see the difference.

diff main.swift.old main.swift > diff

Now the contents of the diff

--- main.swift.old	2023-06-07 21:34:11.054633442 -0700
+++ main.swift	2023-06-07 21:29:47.711075885 -0700
@@ -3,16 +3,45 @@
import CommandLineKit
import Foundation
+import FoundationNetworking
import Prism
var flags = Flags()
let help = flags.option("h", "help", description: "Show description of usage.")
+let newDeck = flags.option("n", "new", description: "Request a new deck.")
+
try flags.parse()
if help.wasSet {
     print(Prism(spacing: .spaces) {
-              ForegroundColor(.red, "\(flags.usageDescription)")
-    })
-}
\ No newline at end of file
+              ForegroundColor(.yellow, "\(flags.usageDescription())")
+          })
+    exit(0);
+}
+
+if newDeck.wasSet {
+    let semaphore = DispatchSemaphore(value: 0)
+    
+    guard let url = URL(string: "https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1") else {
+        print(Prism(spacing: .spaces) {
+                  ForegroundColor(.red, "Error making url")
+              })
+        exit(0)
+    }
+
+    let task = URLSession.shared.dataTask(with: url) {
+        (data, response, error) in
+        guard let data = data, error == nil else {
+            fatalError(error!.localizedDescription)
+        }
+
+        print("Response: \(String(describing: response))")
+        print("Fetched data size: \(data)")
+        semaphore.signal()
+    }
+
+    task.resume()
+    semaphore.wait()
+}

The first change is a little odd, or atleast, I have not seen it in swift projects on macOS. From what I have seen, you only need to import FoundationNetworking on linux and potentially other non-macOS operating systems such as Windows?

A new flag option is added for requesting a new deck.

The next biggest change is down towards the bottom where the program handles if an option is set for newDeck. A semaphore is needed to make the program wait for the task to finish as seen in the lower portion of the program. Otherwise, creat a URL object from a string representation of the URL, using a guard let for if for some reason that fails. Followed by creating a URLSession with a dataTask using the url. A closure takes in data, response, and error. If error is not nil, then perform a fatalError. Otherwise, print the response and the data. The data, with how it is being printed, will only print the length of the data. Signal the semaphore so that way we can resume and finish out the program,

╭─todd@fedora ~/Learning/Swift/Hello 
╰─$ ./.build/x86_64-unknown-linux-gnu/debug/Hello -n
Response: Optional(<HTTPURLResponse 0x00007f8f2c12f6d0> { URL: https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1 }{ status: 200, headers {
   "Access-Control-Allow-Origin" = *;
   "Alt-Svc" = h3=":443"; ma=86400;
   "Cf-Cache-Status" = DYNAMIC;
   "Cf-Ray" = 7d3e7e4f3ec5eb73-SEA;
   "Content-Encoding" = br;
   "Content-Type" = "application/json";
   "Date" = Thu, 08 Jun 2023 04:46:50 GMT;
   "Nel" = {"success_fraction":0,"report_to":"cf-nel","max_age":604800};
   "Referrer-Policy" = same-origin;
   "Report-To" = {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=29uaD8qnUgUPvB1r5yx0zVHRvkrKn%2BxmSIEJZre%2FcZmGzVhlcshKWNymfLhVxSdRi4pvg4pmMuMIHMbenKYeaYTU0Wo%2F66xNGTCCzFbaRa4pAOizwibFnSJPYw5%2FeivxrkKlYhY9hTJt00s1E5%2BlFZg%3D"}],"group":"cf-nel","max_age":604800};
   "Server" = cloudflare;
   "Vary" = Origin;
   "x-content-type-options" = nosniff;
   "x-frame-options" = DENY;
} })
Fetched data size: 79 bytes

Looking at the documentation, there are a number of endpoints we can hit on the device's HTTP REST server. The initial one we will target is the keypress, since this is probably the most basic thing we want to do. We want to be able to navigate the screen. In the table where it talks about the endpoint, we can also see there is a link which takes up to how we can specify the key.

A little bit below that on the page, it shows some examples using curl. While I did this for some initial playing, the main point of interest is to be able to control the thing via code written in swift.

import Foundation

let host = "192.168.0.14"
let port = 8060

let direction = "Right"

let url: URL? = URL(string: "http://\(host):\(port)/keypress/\(direction)")
var request: URLRequest = URLRequest(url: url!)
request.httpMethod = "POST"
print("Sending request")

let (data, response) = try await URLSession.shared.data(for: request)

print("Response: \(response)")

The code is simple. Just a quick script to run in Swift playgrounds. The request for a keypress must be sent as a POST request, so the method is set. Using string interpolation, we set the url. The full url looks like so

http://192.169.0.14:8060/keypress/Right

Using swift's async/await, make the request and print out the response. The following is the response we get back

<NSHTTPURLResponse: 0x1286d4790> { URL: http://192.168.0.14:8060/keypress/Left } { Status Code: 200, Headers {
  "Content-Length" =     (
      0
  );
  Server =     (
      "Roku/12.0.0 UPnP/1.0 Roku/12.0.0"
  );
} }

Not a whole lot of exciting data, the most important bit is the status code of 200 telling us everything went well.

The API provides a lot of different endpoints with my main focus being on keypress. It provides the usualy expected navigation such as left, right, up, and down. Along with an endpoint for home, back and several others.

Here recently, I have taken to dabble in swift a little bit. A little bit of a shout out to Hacking With Swift for some great tutorials to get started with swift. This came about with my recently acquiring an Apple watch SE. I figured, I had a M1 Macbook Air, I might as well play around in the ecosystem some. One thing I've ran into recently as a headache is dealing with my Roku. Great little devices, but with small kids, I always seem to permanently loose the Roku remote. So we started using the Roku app on our phones in lieu. However, the app is rather clunky and a pain to deal with. However, I found some neat documentation on how to interact with the Rokue with my own code.

Simple Service Discovery Protocol

First thing we may want to do is to be able to do is discover any roku devices on our network. Roku make their devices discoverable using SSDP (Simple Service Discovery Protocol). It is a simple protocol to be able to query on a network for any kind of devices and to get some information on them. In the context of a roku device, it will send us information on how to communicate further over TCP directly with the device. Lets take a look at the request and response in Wireshark.

Sending out the query for Devices

We can make thie query by sending a UDP packet to 239.255.255.250 on port 1900. All Roku devices listen on this. The packet we send is fairly simple.

M-SEARCH * HTTP/1.1
Host: 239.255.255.250:1900
Man: "ssdp:discover"
ST: roku:ecp

That goes into the body of the UDP packet being sent out. The bottom of the packet does require a carriage return line feed (rn). So it looks more like this

M-SEARCH * HTTP/1.1\r\n
Host: 239.255.255.250:1900\r\n
Man: "ssdp:discover"\r\n
ST: roku:ecp\r\n
\r\n

What we get in response

In response we get the following, at least for the details we care about.

Frame 5110: 268 bytes on wire (2144 bits), 268 bytes captured (2144 bits) on interface en0, id 0
Ethernet II, Src: Roku_b3:68:af (ac:ae:19:b3:68:af), Dst: Apple_46:9e:c8 (3c:a6:f6:46:9e:c8)
Internet Protocol Version 4, Src: 192.168.0.14, Dst: 192.168.0.88
User Datagram Protocol, Src Port: 1900, Dst Port: 57101
Simple Service Discovery Protocol
  HTTP/1.1 200 OK\r\n
  Cache-Control: max-age=3600\r\n
  ST: roku:ecp\r\n
  USN: uuid:roku:ecp:YH000T494575\r\n
  Ext: \r\n
  Server: Roku/12.0.0 UPnP/1.0 Roku/12.0.0\r\n
  LOCATION: http://192.168.0.14:8060/\r\n
  device-group.roku.com: 3022633342B2DCFCBCB2\r\n
  \r\n
  [HTTP response 1/1]

In the response, we get a HTTP 200 OK. The two important fields we care about are the USN and the LOCATION. The USN has a uuid which in the above is YH000T494575. This uniquely identifies an individual Roku on a network with several other Rokus. The location is going to tell us where it's webserver lives. All Roku webservers live on port 8060 according to the documentation. So we don't really need the query for that. What we care most about is the IP address tied to that specific Roku. With this, we can now use the REST API that each Roku runs in order to fully control it.

Code

The following is some simple code drafted up in a playground.

import Foundation
import Network

let hostUDP: NWEndpoint.Host = "239.255.255.250"
let portUDP: NWEndpoint.Port = 1900

let packet = "M-SEARCH * HTTP/1.1\r\nHost: \(hostUDP):\(portUDP)\r\nMan: \"ssdp:discover\"\r\nST: roku:ecp\r\n\r\n"

print("Packet to send:\n\(packet)")

let connection: NWConnection? = NWConnection(host: hostUDP, port: portUDP, using: .udp)

connection?.stateUpdateHandler = { (newState) in
  switch(newState) {
  case .ready:
    print("State: ready\n")
    let content = packet.data(using: String.Encoding.utf8)
    connection?.send(content: content, completion: NWConnection.SendCompletion.contentProcessed(({ (NWError) in
      if (NWError == nil) {
        print("Data was sent")
      } else {
        print("Error: \(String(describing: NWError))")
      }
    })))
  case .setup:
    print("Setup\n")
  case .cancelled:
    print("Cancelled\n")
  case .preparing:
    print("Preparing\n")
  default:
    print("State not defined\n")
  }
}

connection?.start(queue: .global())

while(true) { }

Here you will need to bear with me since its been awhile since I've done any programming with UDP and more specifically, my first time with Swift. The beginning of the code is faily simple, import some libraries and create some variables for the host and port. I also type out the search packet with string interpolation for the port and host. Next, using NWConnection, start creating the connection. After that is the handler. One thing of importance here is, the connection must be in the ready state in order to send or receive. In this program, receiving is not handled. I did the receiving in wireshark. At the bottom, start the connection on the global DispactchQueue and enter in an infinite while loop. This is just the keep the program running as the DispatchQueue works it's way through the various states in the UDP socket and sends our request packet.