Quick Start

rmqa checks a software release before you publish it. This page takes you from nothing to a checked release in a few minutes. The examples use a made-up command-line tool called tidy, built for five platforms.

1. Get the rmqa Command

Download the archive for your system from the download page, unpack it and put rmqa somewhere on your PATH. Check it works:

rmqa version

2. Write the Manifest From a Good Release

The manifest says what every release must contain. You can write it by hand, but the quick way is to point rmqa init at a release you know is good, such as the last one you published:

rmqa init dist --version 2.3.0 -o rmqa.toml

rmqa opens every archive, finds the programs inside, works out which operating system and processor each one is built for, and spots the version and the platform names in the file names. For tidy it wrote this:

project = "tidy"
# The version can also come from --version, RMQA_VERSION or version_file = "VERSION".
version = "2.3.0"

[[platform]]
os = "darwin"
arch = "amd64"

[[platform]]
os = "darwin"
arch = "arm64"

[[platform]]
os = "linux"
arch = "amd64"

[[platform]]
os = "linux"
arch = "arm64"

[[platform]]
os = "windows"
arch = "amd64"

[[artifact]]
name = "tidy_{os}_{arch}.{archive}"
binaries = ["tidy{exe}"]
files = ["LICENSE", "README.md"]

[[artifact]]
name = "SHA256SUMS"
checksums = "sha256"

{os}, {arch}, {archive} and {exe} are filled in for each platform, so the one [[artifact]] stands for five downloads. {archive} is zip on Windows and tar.gz elsewhere, and {exe} is .exe on Windows and empty elsewhere.

Two small edits are worth making. Add run = ["version"] (or whatever makes your program print its version) under the archive artifact, so rmqa runs the build for its own machine and reads the version back. And replace version = "2.3.0" with version_file = "VERSION" if your project keeps its version in a file. Then commit rmqa.toml next to your code.

3. Check the Next Release

rmqa check dist --version 2.3.0

When everything is right, rmqa says so and exits with status 0:

Checking dist for tidy 2.3.0

  ok    tidy_darwin_amd64.tar.gz  darwin/amd64
  ok    tidy_darwin_arm64.tar.gz  darwin/arm64
  ok    tidy_linux_amd64.tar.gz   linux/amd64
  ok    tidy_linux_arm64.tar.gz   linux/arm64
  ok    tidy_windows_amd64.zip    windows/amd64
  ok    SHA256SUMS

Ready to publish: 0 errors, 0 warnings in 6 files.

When something is wrong, it says what and where, and exits with status 1. Here the arm64 archive got the amd64 build and the Intel Mac archive still holds the previous version:

Checking dist for tidy 2.3.0

  FAIL  tidy_darwin_amd64.tar.gz  darwin/amd64
          tidy: doesn't contain the version string 2.3.0; it may be an old build [version-missing]
  ok    tidy_darwin_arm64.tar.gz  darwin/arm64
  FAIL  tidy_linux_amd64.tar.gz   linux/amd64
          tidy: is byte-for-byte the same program as tidy_linux_arm64.tar.gz:tidy, which is meant for a different platform [duplicate-binary]
  FAIL  tidy_linux_arm64.tar.gz   linux/arm64
          tidy: is built for linux/amd64, but this download is for linux/arm64 [wrong-arch]
          tidy: is byte-for-byte the same program as tidy_linux_amd64.tar.gz:tidy, which is meant for a different platform [duplicate-binary]
  ok    tidy_windows_amd64.zip    windows/amd64
  ok    SHA256SUMS

Not ready: 4 errors, 0 warnings in 6 files.

Every finding ends with a code in brackets, such as [wrong-arch]. The manifest reference lists them all.

4. Make It a Gate in CI

Because the exit status says it all, any CI system can stop a bad release:

rmqa check dist --format github

--format github turns each problem into an annotation on the GitHub Actions run. In GitHub Actions you can use the ready-made action instead of downloading rmqa yourself:

- uses: softdevstudio/[email protected]
  with:
    dir: dist
    version: ${{ github.ref_name }}

Put the step after the build and before the step that publishes. The GitHub Action page has a full workflow.

5. Look Inside a Single File

When something looks odd, rmqa inspect shows what an archive holds, with permissions, sizes and the platform of every program:

$ rmqa inspect tidy_linux_arm64.tar.gz
tidy_linux_arm64.tar.gz  637106 bytes  sha256 1494df09e5149fea9934adc20f97a8670bab2bd7e9dd76352a6b5258004a6f2c
  -rwxr-xr-x  tidy  1429688 bytes  ELF linux/amd64
  -rw-r--r--  LICENSE  541 bytes
  -rw-r--r--  README.md  7 bytes

That’s the whole tool. The manifest reference covers every setting, and the use cases show rmqa on releases laid out the way real projects lay them out.