Archives

Archives are the primary output of dist: a single file (zip or tarball) containing prebuilt executables/binaries for an app, along with additional static files like READMEs, LICENSEs, and CHANGELOGs. The docs previously referred to these as "executable-zips", so if you ever see that term floating around, this is what's being talked about.

When you tell us to build an app for a platform we will always make an archive for it.

Fetching installers will fetch and unpack archives from wherever you uploaded them. Bundling installers will use an exact copy of the binary stored in the archive, but may differ on other included files.

Auto-Detected Files

We will always auto-detect READMEs, LICENSES, and CHANGELOGs with the following logic (described more below):

"Find XYZ*" means we will look for a file whose name starts with "XYZ" in the same directory as the Cargo.toml for a package that defines the app. If no such file is found, we will also search for it in the same directory as the workspace's Cargo.toml (so packages "inherit" these files from the workspace).

It is generally assumed that a directory only contains one of each kind of file. If multiple possible matches are in the same directory we will arbitrarily pick the first one we saw, so don't rely on that.

Auto-detected files are first and foremost auto-included into the archive, however they can also be used for other things. For instance, the autodetected CHANGELOG is fed into our CHANGELOG features.

Archive Contents

The "root" of an archive is either the actual root directory of the archive (zips); or a directory with the same name as the archive, but without the extension (tarballs). This difference is for compatibility/legacy reasons, and can be smoothed away by unpacking tarballs with tar's --strip-components=1.

An app's archive always includes its binaries at the root.

By default auto-detected files for a package are auto-included into its archives at the root of the package. The auto-includes config controls this behaviour.

The include can be used to manually add specific files/directories to the root of the archive.

Archive Formats

Archives can be zips or tarballs (gz, xz, or zstd).

By default we make .zip on windows and .tar.xz elsewhere, but this can be configured with windows-archive and unix-archive features.

Build Flags

We currently always build with --profile=dist

By default we build with --workspace to keep things consistent, but this can be configured with the precise-builds config (see those docs for details on when precise-builds will be force-enabled).

By default we build your packages with default features, but this can be configured with the features, default-features, and all-features configs.

When targeting windows-msvc we will unconditionally append "-Ctarget-feature=+crt-static" to your RUSTFLAGS, which should just be the default for rustc but isn't for legacy reasons.

We don't really support cross-compilation, but we'll faithfully attempt the compile by telling rustup to install the toolchain and passing --target to cargo as instructed -- it will probably just fail. On macOS cross-compiles between Intel and Apple Silicon will work. linux-musl is slated for a future version.

Code Signing

"Code Signing" is a very overloaded term, with wildly varying implementations that accomplish different goals. For instance, Linux users are currently very big on sigstore as a fairly turn-key code signing solution, but neither Windows nor macOS acknowledge its existence (and likely never will, as the benefits of sigstore completely defeat the stated purpose of code signing requirements on those platforms).

Roughly speaking, codesigning can be broken up into "Is this app made by the developer?" and "Can I trust apps made by this developer?". Tools like sigstore are focused on the former, while Windows/macOS only care about the latter. They want you to pay some money and jump through administrative hoops. They also expect you to pay completely different groups and go through completely different hoops, so each platform requires a completely different solution.