Building From Source

There are three things you need to build Ods2Cascade: a C toolchain, OpenSSL, and Rust. You can run Cascade on any operating system and CPU architecture where you can fulfil these requirements.

Dependencies

To get started, you need a C toolchain and OpenSSL because the cryptographic primitives used by Ods2Cascade require it. You also need Rust, because that’s the programming language that Ods2Cascade has been written in. Additionally, you need a few tools used by Ods2Cascade. However, they are installed together with Ods2Cascade in the steps below.

C Toolchain

Some of the libraries Ods2Cascade depends on require a C toolchain to be present. Your system probably has some easy way to install the minimum set of packages to build from C sources. For example, this command will install everything you need on Debian/Ubuntu:

apt install build-essential

If you are unsure, try to run cc on a command line. If there is a complaint about missing input files, you are probably good to go.

OpenSSL

Your system will likely have a package manager that will allow you to install OpenSSL in a few easy steps. On Debian and Ubuntu this is usually libssl-dev. You will also need pkg-config for discovery of system libraries. On Red Hat Enterprise (RHEL) you will most likely need to install openssl-devel.

On Debian-like Linux distributions it should be as simple as running:

apt install libssl-dev pkg-config

Rust

The Rust compiler runs on, and compiles to, a great number of platforms, though not all of them are equally supported. The official Rust Platform Support page provides an overview of the various support levels.

While some system distributions include Rust as system packages, Ods2Cascade relies on a relatively new version of Rust, currently 1.88 or newer. We therefore suggest using the canonical Rust installation via a tool called rustup.

Assuming you already have curl installed, you can install rustup and Rust by simply entering:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Alternatively, visit the Rust website for other installation methods.

Tip

During installation rustup will attempt to configure the PATH. Modifications to PATH may not take effect until the console is restarted, or the user is logged out, or it may not succeed at all. If, after installation, running rustc --version in the console fails, this is the most likely reason.

Building

In Rust, a library or executable program such as Ods2Cascade is called a crate. Crates are published on crates.io, the Rust package registry. Cargo is the Rust package manager. It is a tool that allows Rust packages to declare their various dependencies and ensure that you’ll always get a repeatable build.

Cargo fetches and builds Ods2Cascade’s dependencies into an executable binary for your platform. By default, you install from crates.io, but you can for example also install from a specific Git URL, as explained below.

Installing the latest Ods2Cascade is as simple as running:

cargo install --locked --git https://github.com/nlnetlabs/ods2cascade

The command will build Ods2Cascade and install it in the same directory that Cargo itself lives in, likely $HOME/.cargo/bin. Ensure this directory is in your PATH so you can run Ods2Cascade immediately.

Updating

Tip

Read the general updating instructions first.

If you want to update to the latest version of Ods2Cascade, it’s recommended to update Rust itself as well, using:

rustup update

Use the --force option to overwrite an existing version with the latest Ods2Cascade release:

cargo install --locked --force --git https://github.com/nlnetlabs/ods2cascade

Installing Specific Versions

If you want to install a specific version of Ods2Cascade using Cargo, explicitly use the --version option. If needed, use the --force option to overwrite an existing version:

cargo install --locked --force --git https://github.com/nlnetlabs/ods2cascade --tag 0.1.0-alpha

All new features of Ods2Cascade are built on a branch and merged via a pull request, allowing you to easily try them out using Cargo. If you want to try a specific branch from the repository you can use the --git and --branch options:

cargo install --git https://github.com/NLnetLabs/ods2cascade.git --branch main