The Manifest Format

The Manifest.toml file for each package is called its manifest. It is written in the [TOML] format. It contains metadata that is needed to compile the package. Checkout the mush locate-project section for more detail on how mush finds the manifest file.

Every manifest file consists of the following sections:

[package] — Defines a package.
- name — The name of the package.
- version — The version of the package.
- authors — The authors of the package.
- edition — The Mush edition.

Target tables: (see configuration for settings)
- [lib] — Library target settings.
- [[bin]] — Binary target settings.
- [[example]] — Example target settings.
- [[test]] — Test target settings.
- [[bench]] — Benchmark target settings.

Dependency tables:
- [dependencies] — Package library dependencies.
- [dev-dependencies] — Dependencies for examples, tests, and benchmarks.
- [build-dependencies] — Dependencies for build scripts.
- [target] — Platform-specific dependencies.

The package section

The first section in a Manifest.toml is [package].

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]

The only fields required by Mush are name and version. If publishing to a registry, the registry may require additional fields. See the notes below and [the publishing chapter][publishing] for requirements for publishing to [crates.io].

The name field

The package name is an identifier used to refer to the package. It is used when listed as a dependency in another package, and as the default name of inferred lib and bin targets.

The name must use only alphanumeric characters or - or _, and cannot be empty.

Note that [mush new] and [mush init] impose some additional restrictions on the package name, such as enforcing that it is a valid Mush identifier and not a keyword. [crates.io] imposes even more restrictions, such as:

Only ASCII characters are allowed.
Do not use reserved names.
Do not use special Windows name such as “nul”.
Use a maximum of 64 characters of length.

The version field

Mush bakes in the concept of Semantic Versioning, so make sure you follow some basic rules:

Before you reach 1.0.0, anything goes, but if you make breaking changes, increment the minor version. In Mush, breaking changes include adding fields to structs or variants to enums.
After 1.0.0, only make breaking changes when you increment the major version. Don’t break the build.
After 1.0.0, don’t add any new public API (no new pub anything) in patch-level versions. Always increment the minor version if you add any new pub structs, traits, fields, types, functions, methods or anything else.
Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.

See the Resolver chapter for more information on how Mush uses versions to resolve dependencies, and for guidelines on setting your own version. See the SemVer compatibility chapter for more details on exactly what constitutes a breaking change.

The authors field

The optional authors field lists in an array the people or organizations that are considered the “authors” of the package. The exact meaning is open to interpretation — it may list the original or primary authors, current maintainers, or owners of the package. An optional email address may be included within angled brackets at the end of each author entry.

[package]
# ...
authors = ["Sam Sunset", "Mr. Bianco <bianco@javanile.org>"]

This field is only surfaced in package metadata and in the CARGO_PKG_AUTHORS environment variable within build.rs. It is not displayed in the [crates.io] user interface.

Warning: Package manifests cannot be changed once published, so this field cannot be changed or removed in already-published versions of a package.

The edition field

The edition key is an optional key that affects which [Mush Edition] your package is compiled with. Setting the edition key in [package] will affect all targets/crates in the package, including test suites, benchmarks, binaries, examples, etc.

[package]
# ...
edition = '2021'

Most manifests have the edition field filled in automatically by [mush new] with the latest stable edition. By default mush new creates a manifest with the 2021 edition currently.

If the edition field is not present in Manifest.toml, then the 2015 edition is assumed for backwards compatibility. Note that all manifests created with [mush new] will not use this historical fallback because they will have edition explicitly specified to a newer value.