From e2074dfb41537872d64b833533b8823666327e89 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 16 Dec 2018 10:05:52 -0800 Subject: [PATCH] Document `name` and `authors` in [package] --- src/doc/src/reference/manifest.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index f01a03d0620..8dd39b521a0 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -14,7 +14,20 @@ version = "0.1.0" # the current version, obeying semver authors = ["Alice ", "Bob "] ``` -All three of these fields are mandatory. +#### 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 not be empty, use only [alphanumeric] characters or `-` or `_`. +Note that `cargo new` and `cargo init` impose some additional restrictions on +the package name, such as enforcing that it is a valid Rust identifier and not +a keyword. [crates.io][cratesio] imposes even more restrictions, such as +enforcing only ASCII characters, not a reserved name, not a special Windows +name such as "nul", is not too long, etc. + +[alphanumeric]: https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric #### The `version` field @@ -31,6 +44,15 @@ Versioning](http://semver.org/), so make sure you follow some basic rules: traits, fields, types, functions, methods or anything else. * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0. +#### The `authors` field (optional) + +The `authors` field lists 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. These names will be listed on the crate's page on +[crates.io][cratesio]. An optional email address may be included within angled +brackets at the end of each author. + #### The `edition` field (optional) You can opt in to a specific Rust Edition for your package with the