Rust | Ivan Carvalho

Shipping My Rust CLI to Windows: Lessons Learned (feat. Windows 98 and APE Bonus)

Sun, 15 Feb 2026 10:00:00 -0500

Have you ever been curious about shipping Rust software to Windows users? Did you ever want to create a binary that works on Windows 98 through Windows 11? Or one binary that runs on six different systems? No? Well, I did.

In this post, I will discuss:

Packaging for Scoop, Chocolatey, and Winget
Multi-platform support with Mise
Time-traveling to Windows 98 with retro-compatible builds
Actually Portable Executables that run on any platform

As a reminder, this is a series of posts I made about packaging my Rust CLI:

Part 1: PyPI, NPM, and GitHub Actions
Part 2: Linux and macOS
Part 3: FreeBSD, Nix, Guix
Part 4: Windows and multi-platform (this post)

One of the reasons why I wrote this post was to share what I learned writing celq. It is a small tool that can query JSON, TOML, and YAML from the command line. Go check it out!

Scoop

Let’s start with Scoop because, in my opinion, it is one of the most flexible distribution channels. Although the implementations are completely different, Scoop shares many positive aspects with Homebrew discussed in part 2.

Scoop has the concept of buckets. Buckets are Git repos that are a collection of apps. To add a bucket, I instruct my users to run:

scoop bucket add get-celq https://github.com/get-celq/scoop-bucket

Inside the Git repository, there are app manifests in the buckets/ folder. The manifests are in JSON format. To install my CLI, users need to run:

scoop install get-celq/celq

There is a main bucket that ships by default with Scoop, so running things like scoop install main/uv works with less friction. Naturally, the bar for submitting apps to the main bucket is higher. For me, a third-party bucket controlled by myself was sufficient.

Having established what buckets are, let’s investigate the manifest. You can take a look at an example such as celq.json. Scoop manifests will generally point to GitHub releases.

Keeping a Scoop bucket up-to-date looks like this:

Download the Windows binary from GitHub releases
Calculate the SHA256 checksum for the release
Fill in the template of the JSON manifest with the hash and the version
Make a commit with the updated version

A fun fact about celq is the dogfooding: I generate celq’s manifest with celq. Take a look at celq.json.cel if you are curious.

Mise

Moving on to Mise. This is a multi-platform solution that perhaps should have been covered in part 1. It wasn’t, so now is the second-best moment.

Mise is a polyglot tool manager. It has the concept of mise.toml, which makes it easy to share the environment. It also has the concept of backends: Mise can fetch tools from multiple ecosystems.

For most Rust projects, I believe that the cargo and github backends would be freebies. If you publish to crates.io or to GitHub releases, that should get you covered for commands like mise use -g cargo:celq.

Mise can be interesting when you have Windows developers because it would allow a shared configuration across operating systems. I do not know how well that fares in practice, but conceptually that can avoid duplicating work (e.g., setting up a separate script for configuring a Windows environment).

Chocolatey

Next, we are back to a Windows-specific package manager: Chocolatey. Among the three package managers for Windows that we discuss today, Chocolatey is the oldest. It also comes pre-installed on all Windows GitHub runners, which can be handy.

Chocolatey is built on top of NuGet. Generally, it will have the following format:

awesomepackage/
├── awesomepackage.nuspec
└── tools/
    ├── awesomepackage.exe
    ├── LICENSE.txt
    ├── VERIFICATION.txt
    └── chocolateyInstall.ps1

The .nuspec file is an XML manifest. You can take a look at celq.nuspec to see roughly what it looks like. Perhaps the most important section of the manifest is where <files> is defined, in our case pointing to tools.

For celq, I bundled the binary with the file I uploaded to Chocolatey. It is possible to include scripts for pre-install and post-install steps like chocolateyInstall. The scripts can range from downloading the binary from GitHub releases to creating default configuration files and folders. Because my CLI was simple, I didn’t include a script and simply shipped celq.exe.

Lastly, about VERIFICATION.txt: Chocolatey has a manual verification process! I was not aware of that when I first uploaded my package, but everything gets reviewed by a human. Due to that, it’s not uncommon for Chocolatey packages to lag a bit behind other repositories. But at least there is more oversight compared with, say, NPM.

The file includes instructions for the Chocolatey admins to verify your upload. I got it wrong the first time, so here is my suggestion based on what got accepted without pushback:

VERIFICATION.txt that gets accepted

VERIFICATION

This package is built from source and published by the maintainers.

Generated by `CertUtil -hashfile awesomepackage.exe SHA256`:

SHA256_EXE

---

To verify the binary, confirm that awesomepackage.exe's SHA256 matches
the SHA256 reported at the attestation URL:
https://github.com/user/awesomepackage/attestations/FILL_ME


Alternatively, this can be done via the command line:

0. If you do not have the GitHub CLI installed:
   choco install gh

1. Authenticate the GitHub CLI, if you haven't done so:
   gh auth login

2. Verify the attestation of awesomepackage.exe:

   gh attestation verify awesomepackage.exe --repo user/awesomepackage

A summary of my tip is:

Package the same .exe from GitHub Releases for Windows. Do not run cargo build multiple times, as builds are not guaranteed to be deterministic (i.e., the checksum can change).
Include the SHA256 of the .exe
Generate a GitHub Attestation that we discussed in part 2

Deterministic builds are possible, but that is out-of-scope for this post.

WinGet

WinGet is Windows Package Manager, backed by Microsoft itself. It is newer than Chocolatey, but has seen increasing adoption. It comes pre-installed on consumer editions of Windows 11. Windows Server is not guaranteed to have it, but the GitHub Actions runners do, too.

WinGet uses YAML manifests and has the default source set to winget-pkgs, a GitHub repository maintained by Microsoft. It is possible to add other sources, and some solutions like winget.pro offer ready-made private setups, but I will not discuss those.

I recommend using one of the following two tools to generate the manifests:

I originally used winget-create because it was made by Microsoft, but komac might be more convenient as you can run it on Linux, which can be handy for CI/CD and folks that cross-compile.

When running winget-create/komac, the tools will ask you questions to help fill the metadata of the manifest. The most important one is the Installer URL question. You can make it point to GitHub Releases. Once it has the GitHub URL, it even generates the SHA256 checksum for you in the YAML file.

Updating WinGet packages consists of creating an automation to open pull requests to Microsoft’s repository. winget-releaser seems to be a popular option. Similarly to Chocolatey, WinGet packages can lag behind slightly because the PRs need to be reviewed by a human.

Windows 98 and Retro Computing

Moving to the most fun but least practical part of the blog post: Windows 98. I am happy to share that I have managed to run celq on an operating system that is 25+ years old.

This is anachronistic. Even though JavaScript was around in 1998, JSON was not formalized until the early 2000s, so the usefulness of a JSON query tool is dubious. The binary size of 5 MB would be considered bloated for the time. Rust only ever supported Windows XP, and that support was removed in 2021. Despite all of that, it was still tempting to see how far back I could go.

To support old versions of Windows, I chose the WASM route. I already had implemented an interactive playground for celq, so this was a natural next step. There are other ways of tackling this problem that I will not discuss (e.g., Rust9X, KernelEx, no_std).

From WASM to C to Windows 98

My initial strategy was to use w2c2. w2c2 is a neat tool written by Bastian Müller that transpiles WASM to C89. w2c2 also supports WASI, so I could compile my binary with the wasm32-wasip1 target and go from there.

w2c2 is handy in this context because it splits the problem in two parts. The first one is compiling to WASM: if your Rust code can be compiled to WASM, you are 50% of your way there. There can be some friction in this part, as some of your code or dependencies might not support WASM. For example, the allocator I used (mimalloc) didn’t, and I had to disable it for the WASM build. But overall, Rust still has excellent WASM support.

The second part is finding a C compiler supporting C89. And this is where the w2c2 author intentionally gifted the retro-computing community. C89 is such an old standard that it acts as a common denominator for many systems. There are C89 compilers for IBM’s OS/2, Apple’s Classic Mac OS, Windows 3.1, early versions of Sun’s Solaris, and so on.

The transpiled code from w2c2 is available at celq-retro. Initially, I tested the C output with a recent gcc version installed on my system:

gcc -Os -std=gnu90 \
   -D_GNU_SOURCE -DHAS_UNISTD=1 -DHAS_TIMESPEC=1 \
    -DHAS_SYSUIO=1 -I./vendor \
    main.c celq.c vendor/wasi.c -o celq -lm

Not only did it compile, but the smoke tests passed with the transpiled version. That was promising. My next move was to find a C89 compiler that could target Windows 98.

My recommendation for anyone attempting the same for a CLI is: DJGPP. I learned that there is a port of GCC that targets DOS. andrewwutw/build-djgpp had releases from 2023 that ran on modern Linux environments, which was quite handy. I compiled the code with:

i586-pc-msdosdjgpp-gcc \
    -o celq.exe \
    -O2 \
    -I./vendor \
    -DHAS_UNISTD=1 \
    -DHAS_TIMESPEC=0 \
    main.c celq.c vendor/wasi.c

It generated a 5 MB binary. The binary would have been too big to fit on a floppy disk, but I suppose it could be distributed via CDs. I am aware that it is not a native Win32 binary and that it runs on a DOS extender. Nevertheless, for my CLI it worked flawlessly.

OpenWATCOM and supporting many Windows versions

There is a missing part of the previous section that I did not tell you: DJGPP was not the first compiler I tried. It was the second one. The first one I tried was OpenWATCOM.

OpenWATCOM is the successor of the WATCOM C/C++ compiler, based on the source code that was made available in the early 2000s. Originally, the compiler was proprietary. Among its many claims to fame, WATCOM was used to compile DOOM for the game’s original release. With such a reputation, I had to try OpenWATCOM.

To my surprise, the modern version of OpenWATCOM runs on 64-bit operating systems. There is even a GitHub Action to set it up, called setup-watcom. I am amazed at how easy it was setting things up. I swear cross-compiling for Windows 98 was easier than cross-compiling for modern macOS.

There was one major problem, however. w2c2’s wasi/win32.h header contains a conflicting definition of dirent with Watcom’s vendored dirent.h. I ultimately gave up on solving the conflict and simply stubbed the problematic functions with #ifdef __WATCOMC__ statements. I think the conflicts are fixable and could be upstreamed to w2c2. But given that DJGPP worked right away, I was not motivated to pursue that.

With the stubbed functions in place (throwing an error), I compiled the binary with:

wcl386 -l=nt -os -i=./vendor \
   -d__inline__= \
   -d_WIN32 \
   -d_X86_ \
   -d_MSC_VER=1000 \
   -dHAS_UNISTD=0 \
   -dHAS_TIMESPEC=1 \
   -bm \
   main.c celq.c vendor/wasi.c vendor/win32.c -fe=celq.exe

OpenWATCOM took longer to compile than DJGPP and produced a bigger binary (8 MB). Nonetheless, it was a true Win32 binary. I tested it on Windows 98; it worked. I tested it on Windows XP; it worked as well. I tested it on Wine; it also worked. I tested it on Windows 11; it still worked.

It is a shame that I had to stub the WASI functions, because that blocked access to the file system. The binary produced by OpenWATCOM had the quality of running on Windows versions spanning three decades. That was remarkable.

Time traveling

In the earlier sections, I was fortunate enough to find recent compilers targeting vintage systems. I wanted to also test the time travel route: get my hands on a contemporary C89 compiler for the target system and compile from there.

For Windows 98, this is generally the time when you would summon Borland C++ 5.02 or Visual C++ 6.0. Together with WATCOM, I believe those were the most accurate tools for the period.

For this blog, I decided not to go the abandonware route and stuck with open-source software: MinGW was my compiler of choice. For personal use, I think abandonware is fine, but sharing it is more of a grey area. The advantage of MinGW is that I can easily share the setup.

My first task was to get my hands on the oldest MinGW version I could find. Ideally, I wanted it to be compiled to avoid having to build the toolchain. To my surprise, https://archive.debian.org/ still hosts the original MinGW binary uploads. Thanks, Debian.

I built two Docker images: ghcr.io/celq-playground/celq-retro/debian-etch-mingw with MinGW 3.4.5 from the Debian 4.0 release; and ghcr.io/celq-playground/celq-retro/debian-woody-mingw with MinGW 2.95 from the Debian 3.0 release. The compiler is available through the i586-mingw32msvc-gcc command.

There are older versions of MinGW, but I settled for the very first version uploaded to Debian. I could not find anything earlier than 2.95 on SourceForge either. Some early versions of Dev C++ might have bundled even earlier editions of MinGW, though.

build-oldest-mingw.yml has the workflow and incantation that makes compilation work. I can attest that it produces valid binaries: the executable passes the smoke tests on Windows 11.

I tested celq.exe on Windows 98 and, unfortunately, it crashed at runtime. celq.exe --version and celq.exe --help did work, but anything doing computations failed. On a more positive note, the binary worked on Windows ME and Windows XP, so I was still happy with the result.

Actually Portable Executable

Last but not least, Actually Portable Executables (APEs). I had always thought about chaining Cosmopolitan with w2c2, so this was my chance to do it.

For those unfamiliar with Cosmopolitan, it is a tool that makes C/C++ run anywhere. cosmocc can create “fat” polyglot binaries that run on Linux, macOS, Windows, FreeBSD, NetBSD, and OpenBSD. It feels like magic, to be honest.

I replaced gcc with cosmocc from the command in the earlier sections and things just worked. The binary from cosmocc was the largest at 9.5 MB, which is almost twice the size of platform-specific binaries.

I can attest that the strategy works: the binary did run on Linux, macOS, Windows, and FreeBSD. For some reason, the smoke tests failed on Windows, but I am still in awe it ran on four OSes and passed on three of them.

So I will put it out there: if you want to make a polyglot Rust CLI, wasm32-wasip1 + w2c2 + cosmocc works.

Topics not covered

Rust9x

I want to highlight Rust9x by Dennis Duda. This is another sensible way of targeting Windows 95 and Windows 98. There is a Rust toolchain targeting Windows versions as early as Windows 95. I did not test Rust9x, but it was my backup plan if w2c2 failed.

Signing binaries

I did not sign my binaries. The reason was mostly centered on cost: generally you need to pay for code signing. If you are a legitimate open-source project, check out the SignPath foundation because that was one possible route. SignPath provides free code signing for reputable projects.

Anti-virus misclassifications

I did not run into this problem with celq, but there is a non-zero chance Rust binaries get classified as viruses by accident. This affects some libraries more than others; see Tauri, for example. While browsing Chocolatey, I noticed that even ripgrep sometimes got classified as malware. I wish I had more actionable advice.

wasm3

For the APE section, I believe wasm3 can achieve a similar effect. The idea is to compile a WASM interpreter with Cosmopolitan and then ship the interpreter plus the WASM file. The same applies for retro-computing, but wasm3 targets C99 which is more recent than C89.

Trying to support FreeBSD and Nix for my Rust CLI: Lessons Learned

Mon, 09 Feb 2026 10:00:00 -0500

Have you ever been curious about how Rust software is packaged with Nix? Did you ever want to ship binaries for FreeBSD? No? Well, I did.

In this post, bear with me as we explore:

Building from source for FreeBSD, OpenBSD, and NetBSD
Cross-compiling for FreeBSD x86-64 and aarch64
Ways of writing Nix derivations for Rust
Generating a Guix package from crates.io

As a reminder, this is a series of posts I made about packaging my Rust CLI:

Part 2: Linux and macOS
Part 3: FreeBSD, Nix, Guix (this post)
Part 4: Windows and multi-platform

There is also a Part 1, but let’s put it this way: it was written for another audience. If you are a Nix or BSD user, you might find it vile.

One of the reasons why I wrote this post was to share what I learned writing celq. It is a small tool that can query JSON, TOML, and YAML from the command line. Go check it out!

Disclaimers

Firstly, I have titled this post with the word “trying” because I did not have much of a clue of what I was doing before I tried doing it. If you find issues, reach out and I will try to fix them.

Secondly, this post focuses on self-distribution. Do not immediately submit ports to FreeBSD Ports or packages to Nixpkgs just because you can. There is a cost for the maintainers to keep the builds running. Let things happen organically: if users like your software, they will send a recipe themselves. As long as you make the software easy to build, you did your part.

FreeBSD from Source

I have always been fond of FreeBSD, so I wanted my code to support it. It might seem obvious, but the first step for supporting a new platform is to test your code there! It can be as simple as:

Install Rust and other dependencies/toolchains
Run cargo build
Run cargo test

There are two ways of doing the first step. One can install Rust from the FreeBSD packages with pkg install rust or rust-nightly. The alternative is installing rustup-init from the repository and then downloading the rest of the toolchain with rustup, as is usually done on other platforms.

Afterward, the second step is to verify the code builds. In general, this step will go smoothly for Rust code, but there could be some friction, especially with system libraries or libraries that make low-level syscalls specific to Linux. This step is either trivial or requires investigation when the build fails.

Lastly, tests. This is similar to the previous step in the sense that tests either pass smoothly or identify problems that require manual fixes. Running tests can catch assumptions on Linux runtime behavior that don’t transfer to FreeBSD.

These steps need to run somewhere, so a few options for CI are:

Cirrus CI
GitHub Actions with virtualization
Self-hosted runners with FreeBSD

I ended up using Cirrus CI as they offered first-class FreeBSD support. Their free tier was sufficient for my project, but their pay-as-you-go model seemed reasonable. I set it up to only run full builds on commits to main that change Rust files to help lower the resource usage. GitHub Actions do not support native FreeBSD runners, but there are many actions wrapping QEMU around. I use those for smaller tasks we will discuss later on.

Following these steps ensures that your project plays nicely with the Rust section of the Porter’s handbook. It will simplify the life of any future port maintainer.

Cross-compiling FreeBSD binaries

Next, let’s talk about pre-built binaries. FreeBSD users can always install from source as discussed previously, but for convenience, it is still interesting to provide binaries.

Even if you are not keen on keeping a FreeBSD CI, cross-compilation to FreeBSD from Linux has become easier recently. cargo-zigbuild, which we discussed during Part 1, has reduced the friction.

The idea behind cargo-zigbuild is as follows: Zig has a great linker and it ships with the FreeBSD libc headers. That would be handy for cross-compilation! Indeed, take a look at this command:

cargo zigbuild --locked --release --target x86_64-unknown-freebsd

Because Linux runners are more abundant, I found it easier to set up Zig and cargo-zigbuild with the x86_64-unknown-freebsd target than spinning up QEMU in GitHub Actions.

For aarch64 binaries, the story is slightly different as aarch64-unknown-freebsd is a tier 3 target. If you just copy the setup from x86-64, you will end up with an error message like this:

error: component 'rust-std' for target 'aarch64-unknown-freebsd' is unavailable for download for channel '1.89.0'

The easiest solution for cross-compilation is to switch to Rust nightly and use the unstable build-std feature:

cargo +nightly zigbuild \
  --target aarch64-unknown-freebsd \
  -Z build-std=std,panic_abort \
  -Z build-std-features=panic_immediate_abort

The above command requires the rust-src component from rustup and takes longer as it needs to compile std. But it gets the job done.

OpenBSD and NetBSD

I will briefly discuss OpenBSD and NetBSD, but I will disclose I have never used them on a daily basis.

If you want to support these systems, I strongly recommend following the build-from-source approach discussed previously. Install Rust with the package manager, run cargo build/cargo test to catch bugs, and act accordingly to close bugs.

I was not convinced pre-built binaries would add much value for these platforms. Nevertheless, testing OpenBSD/NetBSD in CI via virtualization goes a long way toward preventing regressions for future port maintainers.

Nix from your repository

NixOS is one Linux distribution that is different from others. Nix can also be used outside of NixOS like in Home Manager. For those not familiar with it, Nix uses a declarative build system with a functional programming language.

In contrast to the previous blog post where we shipped pre-built binaries for Linux, Nix users expect a Nix derivation. The derivations make the system state reproducible and easier to inspect.

There are multiple ways of writing Rust derivations for Nix. At the time of writing, I learned that the NixOS wiki listed seven different methods. I used the built-in buildRustPackage, although crane seems to be a popular option as well.

For me, the best way to learn the derivation was to go check how other Rust CLIs did it in Nixpkgs. I looked at jaq’s entry, because celq was inspired by jaq.

The tweaks I made were:

Automatically reading the version

Nix can read your Cargo.toml! You can write the file once and forget it, there is no risk that the version will get out of sync.

let
  cargoToml = builtins.fromTOML (builtins.readFile Cargo.toml);
in

rustPlatform.buildRustPackage (finalAttrs: {
  pname = "celq";
  version = cargoToml.package.version;
}

Referring to the local source

It is possible to refer to the source of your library without fetchFromGitHub or fetchCrate. That minimizes the burden of updating sha256 checksum field during updates.

src = lib.cleanSource ./.;

Avoiding cargoHash

The concept of having Cargo.lock published with your crate fits nicely with the idea of reproducible builds for Nix. If you specify:

cargoLock = {
    lockFile = ./Cargo.lock;
    allowBuiltinFetchGit = true;
  };

You avoid the need to update cargoHash each time you modify your dependencies.

In practice

You can take a look at celq_dev.nix and flake.nix to see the end result, but I managed to achieve this:

nix run github:IvanIsCoding/celq#dev -- --version

My dev derivation runs the code from the latest commit from main. It also doesn’t need to be updated, which makes it low-maintenance.

Nix from crates.io

Now that we’ve discussed the first derivation, let’s dive into the second derivation, which was the one I wrote first.. I talked with some Nix users and the previous one is the more idiomatic one.

With that being said, I found this derivation useful as it can be tweaked to package any tool published in crates.io. Mentally, it was also comforting to have a derivation pinned to a published, stable version in case I messed up the state of the main during development.

You can see the derivation in celq.nix. It “undoes” some of the conveniences we discussed previously:

version needs to be manually specified
sha256 for the source from crates.io needs to be specified
cargoHash needs to be specified and updated for each version

Keeping these three fields up-to-date can be slightly annoying, in particular cargoHash as it is kind of hard to calculate the hash without running nix first. Nevertheless, the code runs with nix run github:IvanIsCoding/celq and it will not break as long as I point it to a stable crates.io release.

Guix

Last but not least, Guix. This is another package manager based in functional programming. The language though is different: Guix uses Guile.

I must say that Guix does have excellent documentation. To package celq for Guix, I followed the steps from the cookbook:

guix import crate celq
guix import --insert=packages/celq.scm \
      crate --lockfile=../celq-repo/Cargo.lock celq

This generated celq.scm, which can conveniently be distributed on a custom Guix channel.

I found the Guix tooling interesting because the file did convert Cargo.lock ahead of time, so there were many statements like this:

(define rust-cel-0.11.6
  (crate-source "cel" "0.11.6"
                "0pyrqas0r64wykydfmgqfjyb1c14x4w07mafk6fmakzvhb8b7plf"))

Unfortunately, the Rust version that shipped with Guix was not recent enough to compile my dependencies. This was fixable with some interesting tricks. Guix can patch Cargo.toml, so naturally I tried to lower the MSRV:

substitute* "Cargo.toml"
                ;; Patch rust-version
                (("rust-version = \"[^\"]+\"")
                 "rust-version = \"1.85\"")

I applied the same strategy to downgrade the dependencies, reran guix import crate based on a Cargo.lock with downgraded dependencies, and kept going. Eventually, things compiled after a couple of attempts.

I do not plan to keep my Guix channel up-to-date, as I have not found a programmatic way of applying the patches after updates. Nevertheless, I enjoyed going through the process and getting a successful build.

What’s Next

The last post of this series will cover Windows. It will also discuss multi-platform tools I have not got a chance to cover such as Mise. In addition to some practical topics like Scoop, I will also cover less practical experiments like targeting MS-DOS and Windows 98. Stay tuned.

Homebrew and One-Line Installers for My Rust CLI: Lessons Learned

Mon, 02 Feb 2026 10:00:00 -0500

Have you ever run brew install sometool or curl https://sometool.dev | bash to install software? Did you ever want to set up one for your own software? Yes? If so, you are in the right spot.

Throughout this article, I will share how I set up a Homebrew tap and a curl|bash installer for my Rust project. Along with this will also be the closely related topics of:

GitHub releases
cargo binstall and its GitHub Actions applications
GitHub attestations

As a reminder, this is a series of posts I made about packaging my Rust CLI:

One of the reasons why I wrote this post was to share what I learned writing celq. It is a small tool that can query JSON, TOML, and YAML from the command-line. Go check it out!

GitHub Releases

Before we dive into setting up a Homebrew tap and the installer script, we need to talk about the prerequisite: hosting the pre-built binaries.

For this blog post, I will use GitHub releases to host the binaries. This is mostly out of convenience. GitHub offers a very generous limits of free bandwidth for downloading binaries hosted with them. Feel free to host your binaries elsewhere (e.g. GitLab, S3). As long as you have a predictable URL based on the version of your asset, you should be fine.

To generate the pre-built binaries for a Rust CLI, a high-level overview is:

Install the Rust toolchain for the target
Run cargo build --release
Possibly compress and rename the binary from step 2
Run gh release upload $version $asset

The steps can vary depending on your project. For example, you might need to install additional tools for step 1. You can also choose to not compress the binary in step 3.

With regards to compression, it is fairly standard to compress Linux and macOS binaries with .tar.gz and Windows binaries with .zip. Nothing is stopping you from using other compression schemes like zstd if you want, but from looking around most people try to stick with what is already available in systems by default.

For celq, I used GitHub Actions to perform steps 1 to 4. You can check release_github.yml if you are curious. This is again mostly out of convenience. GitHub Actions was the easiest way for me to get a Windows machine.

cargo binstall

Before we jump into Homebrew, let’s collect a freebie: cargo binstall. It lets users install celq with cargo binstall celq.

I found this method valuable for the particular reason: combined with install-action, it makes it trivial to use Rust CLIs on GitHub Actions! Look at this:

- uses: taiki-e/install-action@v2
  with:
    tool: celq

cargo binstall works in this clever way. First, it queries crates.io to get metadata about your crate. Then, it infers the download link for the pre-built binary and downloads it. Afterward, it puts the binary in $HOME/.cargo/bin which should be in the PATH if users have cargo installed.

You can refer to cargo binstall’s documentation for tweaking your crate if the defaults don’t work. I needed to use overrides for celq because I customized the asset names. In general, configuration was straightforward and it just required a [package.metadata.binstall] section in Cargo.toml.

Homebrew

I think a responsible thing to say for this section is: check the dist tool documentation after reading the blog post. There is prior art to this, dist is the most mindless way of setting things up.

With that being said, I did not use dist because I wanted to know how things worked. This made me learn about some limitations from dist that I will share with you, such as installing from source.

Setting up Homebrew starts with setting up a Homebrew tap. A tap is just a GitHub repository with the homebrew- prefix. For example, get-celq/homebrew-tap is the tap I set up.

When installing things from it, the commands look like:

brew install get-celq/tap/celq

If the repository name was homebrew-rustcli, the command would use get-celq/rustcli/$formula instead. It is possible to host taps outside of GitHub by telling users to run brew tap $repo $url first.

It is also possible to distribute your binary through homebrew-core. That is the default channel when running brew install $formula, but the bar for submitting software there is of course higher. Overall, I appreciate Homebrew’s support for third-party channels.

Inside the tap, there are formulas in the Formula folder. Formulas are written in Ruby, so for celq there is Formula/celq.rb. Apart from metadata, I think I can split the formula into three parts: URL to assets, installation step, and tests.

Tying this back to the GitHub releases section, the formulas contain link to assets and the SHA256 checksum. To support multiple architectures and OSes, formulas use the OS.linux/OS.mac and Hardware::CPU.arm/Hardware::CPU.intel variables combined with Ruby if statements:

if OS.mac?
    if Hardware::CPU.arm?
      url "$GITHUB_REPO_URL/releases/download/$VERSION/$asset"
      sha256 "$HASH"
    end
end

To automate Homebrew releases, I simply fill in a formula template with the version and hashes. Afterward, I make a commit to the tap Git repository. You can check update-homebrew-formula.sh for the script that does it.

The rest of the formula is fixed. There’s the install section, which for me was quite simple:

def install
    bin.install "celq"
end

Still, you could leverage Ruby to write more complicated actions such as executing post-installation scripts.

Lastly, Homebrew also lets us run tests post installation. This is not a requirement, but I found it nice to be able to write a smoke test with test do to confirm that things work at runtime.

Homebrew from source plus bottles

One intriguing limitation from dist for me was that it didn’t support creating formulas that build from source. But what did that entail?

Upon looking at other formulas in homebrew-core for Rust CLIs such as the one for just, the answer became clearer.

If you list Rust as a build dependency, Homebrew can delegate the work to Cargo and install the binary in the right spot:

depends_on "rust" => :build

def install
  system "cargo", "install", "--locked", "--root", prefix, "--path", "."
end

For crates that don’t want to host pre-built binaries or crates that depend on system libraries, that option can be interesting.

Another thing I learned about while setting up the installation from source were Homebrew bottles. It turns out that homebrew-core handles pre-built binaries differently from how we discussed in the previous section!

Instead of modifying the url field based on the platform, formulas with bottles keep the source code in the url field and then generate binaries with brew bottle $formula. It looks like this:

bottle do
  root_url "$GITHUB_REPO_URL"
  rebuild 0
  sha256 cellar: :any, arm64_tahoe:   "$hash1"
  sha256 cellar: :any, arm64_sequoia: "$hash2"
  sha256 cellar: :any, x86_64_linux:  "$hash4"
end

I assume that dist chose the style without bottles because of simplicity. Formulas with bottles are a two-step process. First, you need to update the formula. Then, you need to run brew bottle after the formula is in the tap.

It’s easier to automate the case without bottles. Nevertheless, bottles unlock the benefits of pre-built binaries with the flexibility of allowing users to pass --build-from-source when required.

Making an installer script can be quite hard

Next, to install scripts. My original goal was to have one of those one-liners:

curl --proto '=https' --tlsv1.2 -sSf https://get-celq.github.io/install.sh | bash

Before I wrote my own script, I looked at uv’s script from their GitHub release. uv uses dist to generate their script.

To my surprise, I found around 2,000 lines of shell script. I can summarize my learnings as: it is more complicated than it looks! There are lots of details to think about. To list a few:

Detecting glibc vs musl can be a lot of work
Adding your binary to the $PATH is also a lot of work
Handling shadowed bins, updaters, and more
sh is barebones, you’ll need shellcheck to make sure you didn’t use a feature that is not portable

Even though I like uv and dist, I discarded the idea of re-implementing their strategy.

Copying a good existing script

My next best strategy was to research other Rust software that didn’t use dist and shipped with a script. I found two good candidates: just and cargo-binstall.

I learned some useful tricks by looking at their work. cargo-binstall had the benefit of being an installer, so of course its script uses cargo-binstall to install itself. I guess one way of writing an installer is downloading cargo-binstall and calling it! Although I chose not to take that option.

I ended up basing celq’s installer on the one written by Casey Rodarmor for just. Just’s script was considerably shorter. At 180 lines, it makes a few compromises. It does less things than the script generated by dist, but it still gets the job done.

The first compromise is perhaps the most controversial. How does just’s installer detect glibc or musl’s version? The answer is: it doesn’t! I did not realize that was an option, but if you browse just’s release page you will see that indeed they only ship musl binaries.

Choosing only musl binaries has some consequences, as the binaries compiled with x86_64-unknown-linux-gnu are smaller than the ones for x86_64-unknown-linux-musl. There are also other differences such as the musl vs glibc allocators, if you don’t use a custom allocator. But the amount of complexity avoided by only using musl in the installer made me adopt the same strategy.

The other simplification was with regards to modifying the $PATH environment variable. The just installer avoids this problem by requiring a --to argument. If you pass a location that is in the $PATH, good for you! Otherwise the installer will not intervene. This again cuts many lines of code.

I diverged a bit from just’s behavior by guessing default destinations that are generally in $PATH, although the --to option was still available. If the guessed location is not in the path, I just print a warning.

Again, all these small optimizations from Casey compound and make the just installer be less complex.

Attestations and checksums

To wrap things up, let’s discuss two small additions I made to celq’s installer compared to just’s. I saw uv using GitHub attestations and I wanted to play with them.

The first modification was a --verify-checksum flag:

curl --proto '=https' --tlsv1.2 -sSf https://get-celq.github.io/install.sh | \
    bash -s -- --verify-checksum

The concept is simple; I embedded the SHA256 checksums in the installer. It is a simpler check than attestations, but at least it helps with integrity checks to make sure the download was not corrupted. You can see template_install.sh at the repository, it was fairly easy to implement.

The second modification was the --verify-attestation flag. That flag relies on the GitHub CLI (gh). I thought about it because I saw some discussion online about how insecure curl|bash one-liners were. The idea behind it is to mitigate some of those concerns with attestations:

curl --proto '=https' --tlsv1.2 -sSf https://get-celq.github.io/install.sh > install.sh
gh attestation verify install.sh --repo IvanIsCoding/celq
bash install.sh --verify-attestation

Instead of directly piping the script to bash, we save the script to a file. Then, we use gh to verify that the script was indeed generated by me in a GitHub action. Once we establish that the installer is legitimate and from my repository, we run it with the --verify-attestation that applies the same logic to the pre-built binaries. If there is an issue checking that the binaries are from any place other than the ones built by my GitHub Actions, the script fails.

My release process was very similar to Homebrew’s: template the shell script and then make a commit to the GitHub pages repository to publish the script. release_github.yml contains the templating and the attestation generation.

What’s Next

If you found this blog post interesting, stay tuned for the next one. It will cover FreeBSD, Nix, and Guix. There’s cross-compiling Rust binaries to FreeBSD, writing Nix with two kinds of derivations, patching my crate to compile on Guix’s older Rust version, and more.

I packaged my Rust CLI to too many places, here's what I learned

Sun, 25 Jan 2026 13:00:00 -0800

Have you ever had the urge to make your software available in all distribution channels? Did you ever create over 10 different installation methods for a tool no one uses (yet)? No? Well I did.

If you stick around until the end, you will learn how I packaged my Rust CLI to an obnoxious number of places. This is the first post of a series about packaging my Rust CLI. I am planning to split it into four parts:

Part 1: PyPI, NPM, and GitHub Actions (this post)
Part 2: Linux and macOS
Part 3: FreeBSD, Nix, Guix
Part 4: Windows and multi-platform

One of the reasons I am writing this post is to promote celq. It’s a tool that can query JSON, YAML, and TOML. The quickest way to describe it is: it’s like if jq met CEL. Go check it out!

Even if you don’t want to install celq, you can try the playground on your browser!

To get things started, I’ll start with the most “exotic” options: the Python Package Index (PyPI) and NPM. I will also cover GitHub Actions, which will tie with the NPM section.

PyPI and NPM can be puzzling choices for some readers. After all, there’s not a single line of Python or JavaScript code in my binary. Nevertheless, the CLI is available for Python and JavaScript developers.

Why?

You might be asking: why is this piece of software available in so many distribution channels? At this point, the answer is for the sake of it. I wanted to push the number to the limit. I have not yet reached the limit, but I am at a point where the ROI for each additional channel is fairly small.

Nevertheless, there is a reason for distributing pre-built binaries. Users don’t want to spend time compiling your code. Especially in CI where they do it hundreds of times a day! In addition, sometimes users won’t even have the compiler for your language installed.

Another way of putting it is: convenience. Users want a convenient way to download your binary, they don’t want friction. This is where Python and JavaScript come in.

As of 2025, JavaScript and Python topped nearly all programming language ranks. It is reasonable to assume that Python and JS developers would have some of the following tools already installed:

uv
pip or pipx
npm and npx (it comes with Node.js after all)
pnpm
yarn

If you package your Rust CLI for PyPI and NPM, you will unblock an almost frictionless way for users to run your tool. uvx celq and npx celq should just download the binary somewhere and run it.

yarn install celq and pip install celq might require a few extra steps, but overall it is still a simple way of installing software. I am not saying it is the best way of installing software (it isn’t). But it gets the job done.

Also, in my defense: celq is tangentially useful for Python and JavaScript developers.

Have you ever wondered what versions uv resolves for a project? Well, celq can query it. Let’s take for example jupyter related packages:

uvx celq --from-toml -p 'this.package.filter(p, p.name.contains("jupyter"))' < uv.lock

uv.lock is a TOML file, celq can process TOML. The same argument applies for package-lock.json!

Now that the motivation is clearer, let’s see what the process entails.

Python

To publish binaries for PyPI, we will use many tools written in Rust. The first one is uv which we discussed previously. More specifically, we’ll be interested in the uv publish subcommand of uv.

The other immediate tool is maturin. Maturin is mostly known for building Python extensions in Rust. But it works for Rust binaries as well.

The only thing you will need is a pyproject.toml file. You need to put it somewhere. For my project, I made a pypi folder and put it in pypi/pyproject.toml. But putting it at the root of your repository works too.

There are lots of metadata in the file, but the core of it is:

[project]
name = "placeholder"
requires-python = ">=3.10"
description = "TODO"
readme = {file = "README.md", content-type = "text/markdown"}
license-files = ["FILLME"]
dynamic = ["version"]

[build-system]
requires = ["maturin>=1.9,<2"]
build-backend = "maturin"

[tool.maturin]
bindings = "bin"
manifest-path = "../Cargo.toml"
module-name = "placeholder"
locked = true

That is it. Compared to NPM, this one is fairly simple. Of course your Cargo.toml might be in a different path or your workspace might have multiple binaries. Mine didn’t so I didn’t have to take care of it. But if you have to, just check maturin’s documentation because they support it all.

After all is setup, you can build a Python wheel locally. Just run this command in the same directory as your pyproject.toml:

uv build --wheel

Under the hood, uv will end up calling maturin and give you a .whl file somewhere. Assuming you have a PyPI API token, you can upload the wheel with:

uv publish  some/path/placeholder.whl

I could tell you that is all there is to it. If you are on macOS, Windows, or Alpine Linux the above command works. But that would be a lie.

If you are running a moderately recent Linux distribution that doesn’t use musl, you’ll get the following error:

Binary wheel 'placeholder-0.0.1-py3-none-linux_x86_64.whl' has an unsupported platform tag 'linux_x86_64'.

This comes from the thoughtful decision of the PyPI maintainers to make binaries published in PyPI compatible with older Linux distributions. The TL;DR for folks that just want to publish software is: if you build on a Linux distro that is too new, it might include newer libc symbols. If you try to execute the binary on an older distro, things could break!

One solution for that problem is cibuildwheel. The summary of it is that the Python Packaging Authoritry (PyPA) curates a Docker image that will for sure have an older libc version. You build inside of it, your wheel gets a manylinux_2_28 or equivalent suffix instead of linux_x86_64, everyone is happy. But that is not what I did!

Instead, I chose to use cargo-zigbuild. Why? Because Zig is cool and I wanted to try it. But I also found it more lightweight than cibuildwheel. The reasoning behind cargo-zigbuild is as follows: Zig has a great linker, it ships with libc headers, why not use it? You get easier cross-compilation as a bonus as well.

If you thought that it was unusual for celq to be in PyPI, wait until you discover that both the Zig compiler and cargo-zigbuild are there. All these together allows us to conjure a single uv command to compile the binary:

uvx --from maturin==1.11.5 \
    --with ziglang==0.15.1 \
    --with cargo-zigbuild==0.21.1 \
    maturin build --release --target x86_64-unknown-linux-gnu \
    --zig --compatibility manylinux_2_28

That command creates an environment with maturin, Zig, cargo-zigbuild, and tells maturin to use Zig targeting glibc 2.28. That solves our problem.

If you want to see the complete picture, check release_pypi.yml for the complete setup with GitHub actions and trusted publishers. The file covers aarch64 and musl that I skipped for brevity, but overall uv build and the Zig incantation are enough.

NPM

Compared to PyPI, NPM has even less restrictions. It is kind of the wild west, as long as you comply with the ToS you can probably upload any package to NPM.

There is prior art: firstly the dist tool. I ended up not choosing dist because I wanted to understand how things worked. But it is the most mindless way to get your Rust binary in NPM. The tool should do nearly everything for you.

Secondly, there is orhun’s blog. It is the best blog on the subject in my opinion. If I rewrote it I would be doing a disservice, so if you are interested go read the original. What I will focus on is explaining how the trick works.

Orhun’s strategy for git-cliff was as follows:

Create platform specific packages e.g. @namespace/placeholder-linux-x64 or @namespace/placeholder-darwin-arm64
Create a @namespace/placeholder package glueing it all together

The code for @namespace/placeholder is a thin JavaScript shim. The JS code will essentially find your binary in node_modules from the platform specific package (e.g. @namespace/placeholder-linux-x64) and forward the arguments to the binary. That is it.

You can take a look at index.ts for the shim code and release_npm.yml for the GitHub Actions.

I will disclaim that I modified Orhun’s code slightly to make celq dogfood celq. Yes, I use my own CLI tool to fill in a package.json template of sorts. See package.json.cel if you are curious.

Another thing I learned is: the optionalDependencies fields controls the platform-specific binaries. If you ever need to delete macOS x64 or add a future platform like Linux loong64, that is the place to do it.

GitHub Actions

Last but not least, let’s cover GitHub Actions. It is a popular CI/CD option, so again you might be interested in making your software available in that kind of environment.

The ultimate goal for celq was to have this kind of Action:

- name: Example Celq Action
  id: exampleID
  uses: get-celq/celq-action@main
  with:
    cmd: celq 'this.exampleID' < example.json

The action runs a one-off command and it stores the result in a variable (steps.exampleID.outputs.result). For permanently installing a binary, we’ll cover cargo binstall + install-action in the next blog post.

There are two ways of writing GitHub Actions. The first one is with Docker. Perhaps it would have been a more natural way of doing this, but this is not how things happened.

The second way is to write JavaScript. Don’t ask me why, but GitHub Actions are all Node.js based. This is how the NPM section discussed previously comes into play. My strategy was:

Make a Node.js action
Inside the Node.js action, call npx -y @namespace/placeholder $COMMAND
Profit

It turns out that strategy works. I asked Gemini to vibe-code it for me, index.js came out, it works.

Also, you did not ask but: I wrote this blog and celq’s documentation by hand. This was more of a vibe engineered project, it’s not a Level 8 fully autonomous thing. At least I tested the binary and deferred most logic to established libraries (i.e. serde_json, cel-rust).

What’s Next

If you found this blog post interesting, stay tuned for the next one. It will cover Linux and macOS. There’s GitHub releases, there’s bash scripts that are piped to curl, there’s Homebrew, how cargo binstall leads to another GitHub Actions integration, and more.