src/doc/style-guide/src/cargo.md

   1 # Cargo.toml conventions
   2
   3 ## Formatting conventions
   4
   5 Use the same line width and indentation as Rust code.
   6
   7 Put a blank line between the last key-value pair in a section and the header of
   8 the next section. Do not place a blank line between section headers and the
   9 key-value pairs in that section, or between key-value pairs in a section.
  10
  11 Sort key names alphabetically within each section, with the exception of the
  12 `[package]` section. Put the `[package]` section at the top of the file; put
  13 the `name` and `version` keys in that order at the top of that section,
  14 followed by the remaining keys other than `description` in alphabetical order,
  15 followed by the `description` at the end of that section.
  16
  17 Don't use quotes around any standard key names; use bare keys. Only use quoted
  18 keys for non-standard keys whose names require them, and avoid introducing such
  19 key names when possible.  See the [TOML
  20 specification](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md#table)
  21 for details.
  22
  23 Put a single space both before and after the `=` between a key and value. Do
  24 not indent any key names; start all key names at the start of a line.
  25
  26 Use multi-line strings (rather than newline escape sequences) for any string
  27 values that include multiple lines, such as the crate description.
  28
  29 For array values, such as a list of authors, put the entire list on the same
  30 line as the key, if it fits. Otherwise, use block indentation: put a newline
  31 after the opening square bracket, indent each item by one indentation level,
  32 put a comma after each item (including the last), and put the closing square
  33 bracket at the start of a line by itself after the last item.
  34
  35 ```rust
  36 authors = [
  37     "A Uthor <a.uthor@example.org>",
  38     "Another Author <author@example.net>",
  39 ]
  40 ```
  41
  42 For table values, such as a crate dependency with a path, write the entire
  43 table using curly braces and commas on the same line as the key if it fits. If
  44 the entire table does not fit on the same line as the key, separate it out into
  45 a separate section with key-value pairs:
  46
  47 ```toml
  48 [dependencies]
  49 crate1 = { path = "crate1", version = "1.2.3" }
  50
  51 [dependencies.extremely_long_crate_name_goes_here]
  52 path = "extremely_long_path_name_goes_right_here"
  53 version = "4.5.6"
  54 ```
  55
  56 ## Metadata conventions
  57
  58 The authors list should consist of strings that each contain an author name
  59 followed by an email address in angle brackets: `Full Name <email@address>`.
  60 It should not contain bare email addresses, or names without email addresses.
  61 (The authors list may also include a mailing list address without an associated
  62 name.)
  63
  64 The license field must contain a valid [SPDX
  65 expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60),
  66 using valid [SPDX license names](https://spdx.org/licenses/). (As an exception,
  67 by widespread convention, the license field may use `/` in place of ` OR `; for
  68 example, `MIT/Apache-2.0`.)
  69
  70 The homepage field, if present, must consist of a single URL, including the
  71 scheme (e.g. `https://example.org/`, not just `example.org`.)
  72
  73 Within the description field, wrap text at 80 columns. Don't start the
  74 description field with the name of the crate (e.g. "cratename is a ..."); just
  75 describe the crate itself. If providing a multi-sentence description, the first
  76 sentence should go on a line by itself and summarize the crate, like the
  77 subject of an email or commit message; subsequent sentences can then describe
  78 the crate in more detail.