Install¶
Versions
Prebuilt binaries start with v0.0.1. The commands on this page use 0.1.3 as the
example version; the releases
list the latest.
ods is a single binary with no runtime dependencies. Every channel below installs the
same build, for:
| Platform | Archive target |
|---|---|
| Linux x86_64 | x86_64-unknown-linux-musl (static, any distribution) |
| Linux arm64 | aarch64-unknown-linux-musl (static, any distribution) |
| macOS Intel | x86_64-apple-darwin |
| macOS Apple silicon | aarch64-apple-darwin |
| Windows x86_64 | x86_64-pc-windows-msvc |
pip, next to dbt¶
If you install dbt with pip, install ODS the same way, in the same environment:
pip install opendatasuite
ods version
The package contains only the ods executable (like ruff and uv), so there is no
Python import and nothing else to configure. To keep it apart from your project's
environment instead:
pipx install opendatasuite # or: uv tool install opendatasuite
Wheels exist for the platforms above, and for Linux with glibc 2.17 or newer on x86_64 and arm64.
Homebrew (macOS and Linux)¶
brew install buchochelliq-labs/tap/ods
ods version
The formula, in the buchochelliq-labs/homebrew-tap
tap, installs the prebuilt binary from the GitHub release for macOS and Linux, arm64
and x86_64, and checks it against the release's checksums. brew upgrade ods moves to
a new release once its formula is in the tap.
Chocolatey (Windows): under review¶
The opendatasuite package
has been submitted to Chocolatey and is waiting for its moderators to approve the first
version, which can take a couple of weeks. Until it is approved, use pip,
cargo binstall or a direct download. Once it is listed:
choco install opendatasuite
ods version
The package downloads the release's Windows archive, checks its sha256 and puts ods
on your PATH. choco upgrade opendatasuite moves to a new release once Chocolatey has
approved it, usually within a day of the release.
cargo-binstall¶
With cargo-binstall, Rust users get the prebuilt binary instead of compiling:
cargo binstall ods-cli
The crates are on crates.io from 0.1.3. For earlier
releases, name the repository:
cargo binstall --git https://github.com/buchochelliq-labs/open-data-suite ods-cli.
Direct download¶
Each GitHub release
has an archive per platform, named ods-v<version>-<target>.tar.gz (.zip on Windows).
It contains ods, LICENSE, README.md, CHANGELOG.md and THIRD-PARTY-LICENSES.html,
the licences of the open-source software built into ods.
version=0.1.3 target=x86_64-unknown-linux-musl
base=https://github.com/buchochelliq-labs/open-data-suite/releases/download/v$version
curl -LO "$base/ods-v$version-$target.tar.gz" -LO "$base/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf "ods-v$version-$target.tar.gz"
install "ods-v$version-$target/ods" ~/.local/bin/
version=0.1.3 target=aarch64-apple-darwin # x86_64-apple-darwin on Intel
base=https://github.com/buchochelliq-labs/open-data-suite/releases/download/v$version
curl -LO "$base/ods-v$version-$target.tar.gz" -LO "$base/SHA256SUMS"
shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf "ods-v$version-$target.tar.gz"
install "ods-v$version-$target/ods" /usr/local/bin/
$version = "0.1.3"; $name = "ods-v$version-x86_64-pc-windows-msvc"
$base = "https://github.com/buchochelliq-labs/open-data-suite/releases/download/v$version"
Invoke-WebRequest "$base/$name.zip" -OutFile "$name.zip"
Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMS
$expected = (Select-String -Path SHA256SUMS -Pattern " $name.zip$").Line.Split(" ")[0]
if ((Get-FileHash "$name.zip" -Algorithm SHA256).Hash -ne $expected) { throw "checksum mismatch" }
Expand-Archive "$name.zip" -DestinationPath .
.\$name\ods.exe version
Then move ods.exe to a folder on your PATH.
Verify where a file came from¶
Every archive, SHA256SUMS and ods.rb on a GitHub release has a
build provenance attestation:
a signed statement that the release workflow built it from the tagged commit. (Releases
up to 0.1.1 also attached the wheels; from 0.1.3, wheels are on PyPI only, with
PyPI's own attestations.) With the GitHub CLI:
gh attestation verify ods-v0.1.3-x86_64-unknown-linux-musl.tar.gz \
--repo buchochelliq-labs/open-data-suite
From source¶
With Rust 1.90 or newer (rustup.rs):
cargo install --locked ods-cli
Or the latest main:
cargo install --locked --git https://github.com/buchochelliq-labs/open-data-suite ods-cli.
Versions and upgrades¶
ods version prints the ODS version and the versions of the interfaces other tools rely
on (the plugin SDK and the JSON output). Before 1.0, a minor release may include breaking
changes and migrate the state store, so read the changelog before upgrading; a patch
release (0.1.1 → 0.1.3) never does. In the 0.0.x series every release could, even
though 0.0.1 → 0.0.2 looks like a patch. Each break is listed under Breaking in the
changelog,
with what to do. The release notes of each version are its changelog section.
ADR-0019 has the full policy.
For maintainers¶
Releases use rab, the Release Asset Bundle (ADR-0019):
rab.yml lists every channel, .github/rab/ is the installed kit, and
.github/workflows/release.yml runs it. Everything is released together at the
workspace version.
- The release PR bumps
workspace.package.versionand the internal crates'version = "X.Y.Z"requirements inCargo.toml(ADR-0035), moves[Unreleased]inCHANGELOG.mdunder the new version, and runspython3 .github/rab/scripts/release.py syncto copy the version intorab.yml. CI'srelease.py checkfails until they agree. - Once it is merged, on an up-to-date
main:python3 .github/rab/scripts/release.py tag. It pushes an annotated record tag per package that is due (ods-core-vX.Y.Z, …,vX.Y.Zfor the GitHub release,opendatasuite-vX.Y.Zfor PyPI), thenrelease-X.Y.Z, which starts the release run, and waits for it.release.py statusshows what is published. - The release run:
- checks the tag once and runs CI (
ci.yml) on the tagged commit; - builds the archives (static musl on Linux) and the wheels, each with the licence
notices (
scripts/release-notices.sh), and tests each where its runner can run it (scripts/release-test-archive.sh,scripts/release-test-wheel.sh); - publishes the crates to crates.io, in dependency order (ADR-0035);
- creates the GitHub release on
vX.Y.Z: the archives,SHA256SUMSand build provenance attestations, with the version's changelog section as notes (scripts/release-notes.sh; the run fails if the section is missing); - publishes the wheels to PyPI, then installs the version from PyPI;
- renders the Homebrew formula (
packaging/homebrew/ods.rb.tmpl) from the release's checksums, attests it, attachesods.rbto the release and opens a pull request on the tap (not for prereleases); - renders the Chocolatey package (
packaging/chocolatey/), packs it, installs it on Windows from the release's archive, checksods version, and pushes it.
- checks the tag once and runs CI (
Homebrew and Chocolatey are rab's homebrew and chocolatey settings on
the ods package in rab.yml.
4. A failed release is finished by running release.py tag again: it publishes
only what is still due, including a Homebrew pull request or a Chocolatey push that
failed after the GitHub release was out. A Chocolatey version that was rejected is
final: publish a new version. Each run also leaves a release-record artifact
saying what was published. See rab's
recovery guide.
Pull requests that change packaging files run the Packaging workflow, which runs the
same notices, wheel test and notes scripts, and renders the formula and the Chocolatey
package as a release would (release.py render).
One-time setup, by a repository, crates.io and PyPI admin. Every environment below must
allow release-* tags, which is what starts the run:
- crates.io. Create the
crates-ioenvironment with aCARGO_REGISTRY_TOKENsecret: a crates.io API token with thepublish-newandpublish-updatescopes. It publishes each crate's first version (crates.io offers Trusted Publishing only for a crate that exists). crates.io allows a burst of new crates and then one every few minutes, so the first release of all 18 crates takes about two hours; rab waits it out. After that release, add a Trusted Publisher to each crate (repositorybuchochelliq-labs/open-data-suite, workflowrelease.yml, environmentcrates-io), and the token is only used for new crates. - PyPI. The
opendatasuiteproject's trusted publisher: ownerbuchochelliq-labs, repositoryopen-data-suite, workflowrelease.yml, environmentpypi. No API token is stored. - The
pypienvironment, with required reviewers so each upload waits for approval. - Tag protection. A ruleset for
release-*andv*tags (and the crates' record tags,ods-*-v*andopendatasuite-v*) so only maintainers can create them. - Homebrew tap. The public repository
buchochelliq-labs/homebrew-tapholds the formula. The release opens a pull request there with the newFormula/ods.rb; merging it publishes the release tobrew upgrade. For that, create a fine-grained personal access token with access tobuchochelliq-labs/homebrew-taponly and the Contents and Pull requests permissions set to read and write. Then create thehomebrewenvironment with the token as itsHOMEBREW_TAP_TOKENsecret. Without the secret the release'spublish-homebrewjob only prints a notice, and you copy the release'sods.rbasset toFormula/ods.rbin the tap by hand. When the token expires, the job fails: renew it and runrelease.py tagagain. - Chocolatey. Create the
chocolateyenvironment with aCHOCOLATEY_API_KEYsecret (the API key of the chocolatey.org account that ownsopendatasuite) and required reviewers, likepypi. Each push goes through Chocolatey's automated checks, and the package's first version through human moderation, before it is listed. While a version is still in moderation, Chocolatey refuses newer ones with 403 Forbidden, so the release'spublish-chocolateyjob fails until the earlier version is approved. Then runrelease.py tagagain, which pushes it (v0.0.2 waited this way for v0.0.1). - Checks. The
Packagingworkflow runs only on pull requests that change packaging files, so don't make its jobs required checks: a required check that never starts blocks every other pull request. Review its result on the pull requests where it runs, or drop itspathsfilter first if it should be required.