ahornby / dotslash

Simplified executable deployment

DotSlash: simplified executable deployment

DotSlash (dotslash) is a command-line tool that lets you represent a set of platform-specific, heavyweight executables with an equivalent small, easy-to-read text file. In turn, this makes it efficient to store executables in source control without hurting repository size. This paves the way for checking build toolchains and other tools directly into the repo, reducing dependencies on the host environment and thereby facilitating reproducible builds.

We will illustrate this with an example taken from the DotSlash website. Traditionally, if you want to vendor a specific version of Node.js into your project and you want to support both macOS and Linux, you likely need at least two binaries (one for macOS and one for Linux) as well as a shell script like this:

#!/bin/bash

# Copied from https://stackoverflow.com/a/246128.
DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"

if [ "$(uname)" == "Darwin" ]; then
  # In this example, assume node-mac-v18.16.0 is a universal macOS binary.
  "$DIR/node-mac-v18.16.0" "$@"
else
  "$DIR/node-linux-v18.16.0" "$@"
fi

exit $?

With DotSlash, the shell script and the binaries can be replaced with a single file named node:

#!/usr/bin/env dotslash

// The URLs in this file were taken from https://nodejs.org/dist/v18.19.0/

{
  "name": "node-v18.19.0",
  "platforms": {
    "macos-aarch64": {
      "size": 40660307,
      "hash": "blake3",
      "digest": "6e2ca33951e586e7670016dd9e503d028454bf9249d5ff556347c3d98c347c34",
      "format": "tar.gz",
      "path": "node-v18.19.0-darwin-arm64/bin/node",
      "providers": [
        {
          "url": "https://nodejs.org/dist/v18.19.0/node-v18.19.0-darwin-arm64.tar.gz"
        }
      ]
    },
    // Note that with DotSlash, it is straightforward to specify separate
    // binaries for different platforms, such as x86 vs. arm64 on macOS.
    "macos-x86_64": {
      "size": 42202872,
      "hash": "blake3",
      "digest": "37521058114e7f71e0de3fe8042c8fa7908305e9115488c6c29b514f9cd2a24c",
      "format": "tar.gz",
      "path": "node-v18.19.0-darwin-x64/bin/node",
      "providers": [
        {
          "url": "https://nodejs.org/dist/v18.19.0/node-v18.19.0-darwin-x64.tar.gz"
        }
      ]
    },
    "linux-x86_64": {
      "size": 44694523,
      "hash": "blake3",
      "digest": "72b81fc3a30b7bedc1a09a3fafc4478a1b02e5ebf0ad04ea15d23b3e9dc89212",
      "format": "tar.gz",
      "path": "node-v18.19.0-linux-x64/bin/node",
      "providers": [
        {
          "url": "https://nodejs.org/dist/v18.19.0/node-v18.19.0-linux-x64.tar.gz"
        }
      ]
    }
  }
}

Assuming dotslash is on your $PATH and you remembered to chmod +x node to mark it as executable, you can now run your Node.js wrapper exactly as you did before:

$ ./node --version
v18.16.0

The first time you run ./node --version, you will likely experience a small delay while DotSlash fetches, decompresses, and verifies the appropriate .tar.gz, but subsequent invocations should be instantaneous.

To understand what is happening under the hood, read the article on how DotSlash works.

Installing DotSlash

See the installation instructions on the DotSlash website.

License

DotSlash is licensed under both the MIT license and Apache-2.0 license; the exact terms can be found in the LICENSE-MIT and LICENSE-APACHE files, respectively.