This commit supports the following format: ```toml [dependencies.hamcrest] version = "1.0" git = "http://github.com/carllerche/hamcrest-rust" ```
4.8 KiB
The manifest file (Cargo.toml
) is still under active development. This document captures the current thinking on the design.
Sections
The Cargo.toml
file contains several top-level sections:
[project]
: project-specific details, such as name, version and author[[lib]]
: information about the main library file, if one exists. By default, the main library file issrc/<package-name>.rs
[[executable]]
: optionally repeated information about executables that the project is generating. This can both be used for projects that primarily build executables, as well as projects that contain utility executables (such as an HTTP library that comes with a web server executable).
Extensibility
In general, any unknown attributes are ignored for future extensibility. Future plugins may also use this capability.
The project uses the Decoder
in rust-toml
to decode the manifest
into Rust structs that are used throughout the built-in commands.
The [project]
Section
name
: the name of the project (String
)version
: the version of the project, (String
that can be parsed viasemver::parse
)readme
: a Markdown-formatted file in the project that can be used as a description of the document in indexes (Option<Path>
, relative to the project root, defaults to "./README.md", if found).tags
: an array of tags that can be used in indexes (Vec<String>
)authors
: a list of authors inname <email>
format (Vec<String>
). At least oneauthor
with email will probably be required to submit to the Cargo repository.src
: the root directory containing source files (Option<Path>
, relative to the project root, defaults tosrc
)
The [[lib]]
Section
At the moment, Cargo only supports a single lib per package. We use the array format for future extensibility.
We only plan to support a single lib at the moment because if you have multiple libs, you would want projects to be able to depend on them separately. If you don't care about that, why do you have separate libs?
name
: the name of the library (String
,hammer
would create alibhammer
)path
: the location of the main crate file (Option<Path>
, defaults tosrc/<name>.rs
)
Note that we plan to support multiple Cargo.toml
files in Cargo's git
support, so you don't have to have a separate git repository per
library.
The [[executable]]
Section
The executable
section is optionally repeated. It is designed for
projects whose main raison d'être is a single executable, or for projects
that want to provide utility executables alongside a primary library.
If an executable has a different set of flags or dependencies from the main library, it should be shipped as a separate package with a dependency on the main library to keep the usage requirements of the standalone library limited to the bare minimum requirements.
name
: the name of the executable (String
,hammer
would create ahammer
executable)path
: the location of the main crate file for the executable (Option<Path>
, defaults tosrc/<name>.rs
if the project has only an executable,src/bin/<name>.rs
if the project has both a lib and executable, see below)
The [dependencies]
Section
[dependencies]
rust-http = "1.x"
hammer = ["> 1.2", "< 1.3.5"]
[dependencies.hamcrest]
version = "1.2.x"
git = "http://github.com/carllerche/hamcrest"
Projects Containing Both lib
and executable
Most projects will primarily produce either a library or an executable.
Such projects should name the main crate file <projectname>.rs
and
omit the optional path
from the lib
or executable
sections.
Projects that contain both a library and one or more executables should
generally use <projectname>.rs
for their library, and bin/*.rs
for the executables.
These rules are also the default behavior if path
is left off of lib
or executable
sections.
Example Manifests
Simple lib
:
[project]
name = "hammer"
version = "0.1.0"
readme = "README.md"
authors = ["Yehuda Katz <wycats@gmail.com>"]
[[lib]]
name = "hammer"
Simple executable
:
[project]
name = "skylight"
version = "0.5.0"
authors = ["Tom Dale <tom@tomdale.net>", "Carl Lerche <me@carllerche.com>"]
tags = ["performance", "profiling"]
[[executable]]
name = "skylight"
path = "bin/skylight.rs" # supports existing project structures
A project with both a lib and an executable
:
[project]
name = "skylight"
version = "0.5.0"
authors = ["Tom Dale <tom@tomdale.net>", "Carl Lerche <me@carllerche.com>"]
tags = ["performance", "profiling"]
[[lib]]
name = "skylight" # path defaults to src/skylight.rs
[[executable]]
name = "skylight" # path defaults to src/bin/skylight.rs
[[executable]]
name = "skylight-setup" # path defaults to src/bin/skylight-setup.rs