config 1.0

[Gankra]

Our config has matured enough that we now have a pretty good sense of how it should be shaped.

To be clear, if we do this:

• cargo dist init would automate the migration to this format
• it would all still be nestable in a Cargo.toml, so [build] would be [workspace.metadata.dist.build]

Here are some goals:

• prioritize the dist.toml format, as it will become more central the more we support not-cargo
• explicit hierarchy of config
  • replaces messy adhoc namespacing of config ("npm-scope" vs "tap")
  • makes it natural to express "publish preleases to crates.io but not npm"
  • can have further levels of inheritance ([installers.shell] inherits config from [installer])
• emphasize the "build, host, publish" phases

Note that the following examples assume we're still reading your Cargo.toml for the values that "belong" there like package name, version, etc.

Example: typical init

Here we have the typical minimal cargo-dist config:

• cargo-dist-version
• some targets
• github ci with plan prs
• shell and powershell installers

show example

```toml [workspace] cargo-dist-version = "0.11.0" # build settings [build] targets = ["aarch64-apple-darwin", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl", "x86_64-pc-windows-msvc"] # what ci to run builds on [ci.github] pr-run-mode = "plan" # what installers to make [installers.shell] [installers.powershell] # the above can potentially be sugarred to # installers = ["shell", "powershell"] # as before, but i won't use that in these examples ```

Example: oranda

Here is a translation of oranda's fairly power-user config:

show example

```toml [workspace] cargo-dist-version = "0.11.0" # build settings [build] targets = ["aarch64-apple-darwin", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl", "x86_64-pc-windows-msvc"] [build.cargo] features = ["build-with-tailwind"] [[build.extra]] artifacts = ["oranda-config-schema.json"] build = ["cargo", "run", "--", "config-schema", "--output=oranda-config-schema.json"] [[build.extra]] artifacts = ["oranda.css"] build = ["cargo", "run", "--", "generate-css", "--out-dir=./"] [build.archives] windows = ".tar.gz" unix = ".tar.gz" # where to host builds [host.github] [host.axodotdev] # where to publish releases [publish.homebrew] # what ci to run builds on [ci.github] pr-run-mode = "plan" # what installers to make [installers.shell] [installers.powershell] [installers.npm] scope = "@axodotdev" [installers.homebrew] tap = "axodotdev/homebrew-tap" ```

Example: maximalist nightmare

Here's me just trying to show every single config

show example

```toml # Sketch of the v1.0.0 dist.toml / dist-workspace.toml format [workspace] # usual suspects cargo-dist-version = "1.0.0" checksum = "sha256" dist = true # build settings [build] targets = ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu"] # cargo build settings [build.cargo] all-features = false default-features = true features = ["a", "b", "c"] precise-builds = false msvc-crt-static = true [build.archives] auto-includes = true include = ["a.txt", "b.txt"] unix = ".tar.gz" windows = ".zip" # extra builds [[build.extra]] artifacts = ["dist-manifest-schema.json"] build = ["cargo", "dist", "manifest-schema", "--output=dist-manifest-schema.json"] # sysdeps [dependencies.homebrew] cmake = '*' libcue = { stage = ["build", "run"] } [dependencies.apt] cmake = '*' libcue-dev = { version = "2.2.1-2" } [dependencies.chocolatey] lftp = '*' cmake = { version = '3.27.6', targets = ["aarch64-pc-windows-msvc"] } # host settings [host] # enabling a host is done by adding its [host.xyz] entry [host.github] create-release = true [host.axodotdev] # enabling a publish is done by adding its [publish.xyz] entry [publish] prereleases = false [publish.cargo] prereleases = false [publish.homebrew] prereleases = false [publish.npm] prereleases = false [ci] # enabling a ci is done by adding its [ci.xyz] entry [ci.github] pr-run-mode = "plan" tag-namespace = "" allow-dirty = false dispatch-releases = true fail-fast = true # custom jobs [ci.github.jobs] plan = [] build-local = [] build-global = [] host = [] publish = [] # add pre and post for everything? pre-announce = [] announce = [] post-announce = [] # custom runners [ci.github.runners] aarch64-unknown-linux-gnu = "buildjet-8vcpu-ubuntu-2204-arm" aarch64-unknown-linux-musl = "buildjet-8vcpu-ubuntu-2204-arm" # enabling an installer is done by adding its [installer.xyz] entry [installers] install-path = "~/CARGO_HOME" [installers.shell] install-path = "~/CARGO_HOME" [installers.powershell] install-path = "~/CARGO_HOME" [installers.homebrew] tap = "axodotdev/homebrew-tap" formula = "" [installers.npm] scope = "@axodotdev" [installers.msi] allow-dirty = false ```

[Gankra]

[installers] could be [build.installers]... they're so central that they feel like they should be top-level but shrug

[ashleygwilliams]

one q: i like the ability to configure things per item (e.g. installer or target) but we should offer sugar for setting that config for all of a certain class of things

another thing- just using the square brackets as "data entry" doesn't feel right- this may be me just not liking toml is there an alt config for that if you don't want to furhter config individual items?

[Gankra]

if you set [publish] prereleases=true it will get "inherited" to all the [publish.xyz] entries. similarly for [installers] and [ci] and [host]

we can support a sugar of host = ["github", "axodotdev"] for [host.github] [host.axodotdev], I was avoiding showing it to see how we felt about the verbose form.

[Gankra]

A subtle virtue of the [installer.homebrew] form is that i can just tell you

paste this into your config

[installers.homebrew]
tap = "axodotdev/homebrew-tap"

whereas right now i need to say

paste this into your config (BUT LIKE, MERGE THE INSTALLERS FIELD OK?)

installers = ["homebrew"]
tap = "axodotdev/homebrew-tap"

[ashleygwilliams]

so for a verbose form where people want a lot of bespoke config, i think it's great. i think my biggest hesitation is making sure it also works equally great for the "little to no" config person and the transition between the two 😅

this is certainly an improvement over what we currently have!

random thought: is any of this config per target or is it always per installer/dist mechanism

[Gankra]

notes about some capricious changes made here:

• allow-dirty has been smashed up from an array to a series of allow-dirty=true flags nested under the relevant sections
• publish-jobs = ["homebrew"], which would have become [ci.github.jobs] publish = ["homebrew"] has been moved to [publish.homebrew] -- that is to say, builtin and custom publishes are now in different config universes.
• build-local = false (the astral hack to allow maturin to replace local builds) is not featured here, i'm still mulling over how it should be expressed.

[Gankra]

random thought: is any of this config per target or is it always per installer/dist mechanism

yeah it's an open question to me if/how that would be supported. [build.target."x86_64-pc-windows.msvc".cargo] ... could be allowed for... but that's genuinely getting deep in the weeds I don't want to deal with unless someone Demands it.

[Gankra]

Biggest first step is pulling axoproject in-tree so it's easy to work on config and no need for fake separations of concern.

[Gankra]

TODO: write an example TOC of the new config