# cargo-parcel metadata reference

A simple application crate's `Cargo.toml` may look like this:

```toml
[package]
name = "hello-world"
version = "0.0.1"
authors = ["Alice Hacker <alice@example.org>"]
edition = "2018"

[dependencies]

[package.metadata.parcel]
cargo-binaries = ["hello-world"]
man-pages = ["hello-world.1.md"]
pkg-data = ["data/*"]
```

This will install the `hello-world` binary in *prefix*`/bin`, and
the result of rendering `hello-world.1.md` with `pandoc` to
*prefix*`/share/man/man1/hello-world.1`. All files and directories
under `data` will be installed to *prefix*`/share/hello-world/`.

## Settings

Inside the `package.metadata.parcel` table, the following keys can be
used to describe the parcel's contents:

- `cargo-binaries`

  A list of filenames, referring to the filenames of binaries output
  by `cargo build`. Note that *only* these binaries will be included,
  so if you do not specify this, `cargo parcel install` will not
  install any binaries, which is probably not what you want.

- `man-pages`

  A list of manual page files, either verbatim or as Markdown
  source. The file names must start conform to the pattern
  "*name*.*section*" or "*name*.*section*.md", where *name* may be
  arbitrary, but *section* must start with a number from 1 up to and
  including 8, which will be used to place them in the proper
  directory upon installation.

  When a Markdown source is used, [`pandoc`] is used to render it to
  [troff] format before installation.

- `pkg-data`

  A list of glob patterns. The files and directories matched by the
  patterns will be installed into a directory with a package-specific
  name. Note that only the last component of the matched files is used
  as at the destination name.

  The destination directory is currently
  *`prefix`*`/share/`*`pkg-name`* on all platforms, but that will
  probably change for Windows, should `cargo-parcel` ever be adapted
  to support its conventions.

- `pkg-name`

   A string. Can be used to override the crate name. This is helpful
   for crates name *foo*-cli or similar. Such crates names are a
   common occurrence, as the "actual" crate name, *foo* will be
   preferably given to the accompanying library crate, if one exists.

[`pandoc`]: https://pandoc.org/
[troff]: https://en.wikipedia.org/wiki/Troff