repository·main·Indexed 21 days ago
https://github.com/facebook/dotslashA command-line tool for simplified executable deployment that replaces platform-specific binaries with lightweight text files. It fetches, caches, and verifies binaries on-demand, allowing developers to vendor toolchains into source control efficiently. Available as a CLI, an npm package (fb-dotslash), a Python library, and a Dev Container Feature.
DotSlash (dotslash) is a command-line tool designed to fetch, verify, and run executables. It maintains a local cache of fetched executables to ensure that subsequent invocations are fast.
It is primarily used to keep heavyweight binaries out of version control repositories while ensuring developers have access to consistent, platform-specific tools for hermetic builds.
DotSlash (dotslash) is a command-line tool designed for simplified executable deployment. It allows you to replace platform-specific, heavyweight binaries and complex shell scripts with a single, lightweight, human-readable text file (typically JSON or JSONC).
Instead of storing large binaries directly in source control, you define the metadata for various platforms in a DotSlash file. When the file is executed, DotSlash automatically fetches, decompresses, and verifies the correct binary for the host environment. This approach facilitates reproducible builds by allowing toolchains to be checked into a repository without significantly increasing its size.
When you invoke a DotSlash file (e.g., ./scripts/node --version), DotSlash acts as a transparent wrapper that manages the lifecycle of the underlying executable. On macOS and Linux, the process follows these steps:
dotslash binary with the target file as an argument.exec invocation.exec the artifact from the $DOTSLASH_CACHE.ENOENT), DotSlash acquires a file lock for that specific artifact to prevent race conditions.providers defined within the DotSlash file to fetch the artifact, then verifies its size and hash.mv) to its final destination in the cache.exec, replacing the dotslash process with the actual target executable../scripts/node --versionDotSlash files can be managed via policies that determine when they should be automatically regenerated. Common criteria for regeneration include:
cron).When a policy is satisfied, a script generates build jobs. Each job produces a compressed artifact (using zstd) which is uploaded to a blobstore. The resulting DotSlash file aggregates the metadata (URL, BLAKE3 hash, and file size) for all platforms.
The path identifies the file to execute within the unpacked artifact's directory.
Strict Requirements:
\) are allowed, even on Windows./usr/bin/foo)../foo or ../foo).foo/).Behavior based on format:
path is the relative path within the unpacked directory.path is the relative path where the file is written inside a new, empty directory in the cache.DotSlash is an ad-hoc distribution mechanism for tools, designed to allow executables to be updated atomically with code. Instead of distributing large binaries directly, DotSlash uses small (kilobyte-sized) files that lazily fetch the actual artifacts (which can be megabytes or gigabytes) only when executed.
Key Benefits:
DotSlash is designed exclusively for fetching and running executable files. It is not intended as a general-purpose file distribution mechanism.
If you need to distribute data via DotSlash, the recommended pattern is to create an executable that, when run, writes the specific data payload to a designated output folder.
A DotSlash file is a specialized configuration file used to define executable deployment across multiple platforms.
#!/usr/bin/env dotslash followed immediately by a newline (\n or \r\n).// and /* */ style comments.The root JSON object must contain:
name (string): The name of the executable.platforms (map): A map where keys are platform identifiers and values are platform entries.Platform keys follow a format inspired by Clang triples. Supported keys are:
linux-aarch64linux-x86_64macos-aarch64macos-x86_64windows-aarch64windows-x86_64When running a DotSlash file, it only executes the entry corresponding to the current target platform.
#!/usr/bin/env dotslash
{
"name": "hermes",
"platforms": {
"linux-x86_64": {
"size": 47099598,
"hash": "blake3",
"digest": "8d2c1bcefc2ce6e278167495810c2437e8050780ebb4da567811f1d754ad198c",
"format": "tar.gz",
"path": "hermes",
"providers": [
{
"url": "https://example.com/hermes.tar.gz"
}
]
}
}
}When using DotSlash, be aware of two technical trade-offs:
A provider is a JSON object in the providers list that tells DotSlash how to fetch an artifact. DotSlash tries providers in the order they are listed until one succeeds. If you want to randomize the order (e.g., to use mirrors), add providers_order: "weighted-random" to the artifact entry. You can use a weight (integer $\ge 1$, defaults to $1$) to bias the selection.
Currently supported providers:
curl to fetch via a URL. Requires the url field.gh) to fetch from a repository. Requires type, repo, tag, and name. This is useful for private repositories if gh is authenticated.aws CLI to fetch from S3 or compatible stores. Requires type, repo (the bucket), key, and optionally region.{
"format": "tar.gz",
"path": "hermes",
"providers": [
{"url": "https://primary.example.com/hermes.tar.gz", "weight": 3},
{"url": "https://mirror1.example.com/hermes.tar.gz", "weight": 1},
{"url": "https://mirror2.example.com/hermes.tar.gz", "weight": 1},
{"url": "https://mirror3.example.com/hermes.tar.gz", "weight": 1}
],
"providers_order": "weighted-random"
}DotSlash is not a full-featured package manager like RPM or APT. When deciding if DotSlash is right for your project, consider these functional differences:
$PATH. The dependency is only fetched when the specific DotSlash file for that dependency is executed./etc/bash_completion.d or /usr/share/man) during installation.Workaround for completions: If your tool requires shell completions, you should implement a subcommand within your CLI (similar to rustup completions) that allows users to generate these files manually.
Because Windows does not support shebangs and relies on file extensions for executability, you can use the DotSlash Windows Shim to run DotSlash files.
To use it, place the shim executable in the same directory as your DotSlash file, renaming the shim to match the DotSlash file's name plus the .exe extension. When the .exe is executed, it automatically invokes dotslash with the sibling DotSlash file and forwards all arguments and I/O streams.
Example:
If your DotSlash file is named node, copy the shim executable to that directory and rename it to node.exe. Running node.exe will execute dotslash node with your provided arguments.
# Example setup
# If you have a file named 'node' (the DotSlash file)
# Copy the shim to the same directory and rename it to 'node.exe'