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

[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

[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

# 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