script:
- cargo test
- cargo doc --no-deps
- - sh src/ci/dox.sh
- after_success: |
- [ $TRAVIS_BRANCH = master ] &&
- [ $TRAVIS_PULL_REQUEST = false ] &&
- [ $(uname -s) = Linux ] &&
- pip install ghp-import --user &&
- $HOME/.local/bin/ghp-import -n target/doc &&
- git push -qf https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages 2>&1 >/dev/null
+ - (cd src/doc && mdbook build --no-create --dest-dir ../../target/doc)
exclude:
- rust: stable
script:
- cargo test
-env:
- global:
- - secure: "hWheSLilMM4DXChfSy2XsDlLw338X2o+fw8bE590xxU2TzngFW8GUfq7lGfZEp/l4SNNIS6ROU/igyttCZtxZMANZ4aMQZR5E8Fp4yPOyE1pZLDH/LdQVXnROsfburQJeq+GIYIbZ01Abzh5ClpgLg5KX0H627uj063zZ7Ljo/w="
-
notifications:
email:
on_success: never
+
addons:
apt:
packages:
+++ /dev/null
-set -ex
-
-DOCS="index faq config guide manifest build-script pkgid-spec crates-io \
- environment-variables specifying-dependencies source-replacement \
- external-tools"
-ASSETS="CNAME images/noise.png images/forkme.png images/Cargo-Logo-Small.png \
- stylesheets/all.css stylesheets/normalize.css javascripts/prism.js \
- javascripts/all.js stylesheets/prism.css images/circle-with-i.png \
- images/search.png images/org-level-acl.png images/auth-level-acl.png \
- favicon.ico policies.html"
-
-for asset in $ASSETS; do
- mkdir -p `dirname target/doc/$asset`
- cp src/doc/$asset target/doc/$asset
-done
-
-for doc in $DOCS; do
- rustdoc \
- --markdown-no-toc \
- --markdown-css stylesheets/normalize.css \
- --markdown-css stylesheets/all.css \
- --markdown-css stylesheets/prism.css \
- --html-in-header src/doc/html-headers.html \
- --html-before-content src/doc/header.html \
- --html-after-content src/doc/footer.html \
- -o target/doc \
- src/doc/$doc.md
-done
-
-# Temporary preview for mdBook docs
-cd src/doc/book
-$HOME/.cargo/bin/mdbook build --no-create --dest-dir ../../../target/doc/book
-cd ../../../
+++ /dev/null
-doc.crates.io
+++ /dev/null
-index.md book/src/index.md book/src/getting-started/index.md book/src/getting-started/*.md
-guide.md book/src/guide/index.md book/src/guide/*.md
-build-script.md book/src/reference/build-scripts.md
-config.md book/src/reference/config.md
-crates-io.md book/src/reference/publishing.md
-environment-variables.md book/src/reference/environment-variables.md
-external-tools.md book/src/reference/external-tools.md
-manifest.md book/src/reference/manifest.md
-pkgid-spec.md book/src/reference/pkgid-spec.md
-source-replacement.md book/src/reference/source-replacement.md
-specifying-dependencies.md book/src/reference/specifying-dependencies.md
-faq.md book/src/faq.md
-# Cargo Documentation
+# The Cargo Book
-NOTE: Cargo documentation is under migration to mdBook-based structure. All the
-`*.md` files here shall be kept in sync with the `*.md` files under `book/src/`.
-See `MIGRATION_MAP` file here and <https://github.com/rust-lang/cargo/pull/4453>
-for details.
+
+### Requirements
+
+Building the book requires [mdBook]. To get it:
+
+[mdBook]: https://github.com/azerupi/mdBook
+
+```shell
+$ cargo install mdbook
+```
+
+### Building
+
+To build the book:
+
+```shell
+$ mdbook build
+```
+
+The output will be in the `book` subdirectory. To check it out, open it in
+your web browser.
+
+_Firefox:_
+```shell
+$ firefox book/index.html # Linux
+$ open -a "Firefox" book/index.html # OS X
+$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
+$ start firefox.exe .\book\index.html # Windows (Cmd)
+```
+
+_Chrome:_
+```shell
+$ google-chrome book/index.html # Linux
+$ open -a "Google Chrome" book/index.html # OS X
+$ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell)
+$ start chrome.exe .\book\index.html # Windows (Cmd)
+```
+
+
+## Contributing
+
+Given that the book is still in a draft state, we'd love your help! Please feel free to open
+issues about anything, and send in PRs for things you'd like to fix or change. If your change is
+large, please open an issue first, so we can make sure that it's something we'd accept before you
+go through the work of getting a PR together.
--- /dev/null
+title = "The Cargo Book"
+author = "Alex Crichton, Steve Klabnik and Carol Nichols, with Contributions from the Rust Community"
+++ /dev/null
-# The Cargo Book
-
-
-### Requirements
-
-Building the book requires [mdBook]. To get it:
-
-[mdBook]: https://github.com/azerupi/mdBook
-
-```shell
-$ cargo install mdbook
-```
-
-### Building
-
-To build the book:
-
-```shell
-$ mdbook build
-```
-
-The output will be in the `book` subdirectory. To check it out, open it in
-your web browser.
-
-_Firefox:_
-```shell
-$ firefox book/index.html # Linux
-$ open -a "Firefox" book/index.html # OS X
-$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
-$ start firefox.exe .\book\index.html # Windows (Cmd)
-```
-
-_Chrome:_
-```shell
-$ google-chrome book/index.html # Linux
-$ open -a "Google Chrome" book/index.html # OS X
-$ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell)
-$ start chrome.exe .\book\index.html # Windows (Cmd)
-```
-
-
-## Contributing
-
-Given that the book is still in a draft state, we'd love your help! Please feel free to open
-issues about anything, and send in PRs for things you'd like to fix or change. If your change is
-large, please open an issue first, so we can make sure that it's something we'd accept before you
-go through the work of getting a PR together.
+++ /dev/null
-title = "The Cargo Book"
-author = "Alex Crichton, Steve Klabnik and Carol Nichols, with Contributions from the Rust Community"
+++ /dev/null
-# Summary
-
-[Introduction](index.md)
-
-* [Getting Started](getting-started/index.md)
- * [Installation](getting-started/installation.md)
- * [First Steps with Cargo](getting-started/first-steps.md)
-
-* [Cargo Guide](guide/index.md)
- * [Why Cargo Exists](guide/why-cargo-exists.md)
- * [Creating a New Project](guide/creating-a-new-project.md)
- * [Working on an Existing Project](guide/working-on-an-existing-project.md)
- * [Dependencies](guide/dependencies.md)
- * [Project Layout](guide/project-layout.md)
- * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md)
- * [Tests](guide/tests.md)
- * [Continuous Integration](guide/continuous-integration.md)
-
-* [Cargo Reference](reference/index.md)
- * [Specifying Dependencies](reference/specifying-dependencies.md)
- * [The Manifest Format](reference/manifest.md)
- * [Configuration](reference/config.md)
- * [Environment Variables](reference/environment-variables.md)
- * [Build Scripts](reference/build-scripts.md)
- * [Publishing on crates.io](reference/publishing.md)
- * [Package ID Specifications](reference/pkgid-spec.md)
- * [Source Replacement](reference/source-replacement.md)
- * [External Tools](reference/external-tools.md)
-
-* [FAQ](faq.md)
+++ /dev/null
-## Frequently Asked Questions
-
-### Is the plan to use GitHub as a package repository?
-
-No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with
-npmjs.org and rubygems.org.
-
-We plan to support git repositories as a source of packages forever,
-because they can be used for early development and temporary patches,
-even when people use the registry as the primary source of packages.
-
-### Why build crates.io rather than use GitHub as a registry?
-
-We think that it’s very important to support multiple ways to download
-packages, including downloading from GitHub and copying packages into
-your project itself.
-
-That said, we think that [crates.io] offers a number of important benefits, and
-will likely become the primary way that people download packages in Cargo.
-
-For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a
-central registry model as well as a Git-based model, and most packages
-are downloaded through the registry in those ecosystems, with an
-important minority of packages making use of git-based packages.
-
-[1]: https://www.npmjs.org
-[2]: https://bundler.io
-
-Some of the advantages that make a central registry popular in other
-languages include:
-
-* **Discoverability**. A central registry provides an easy place to look
- for existing packages. Combined with tagging, this also makes it
- possible for a registry to provide ecosystem-wide information, such as a
- list of the most popular or most-depended-on packages.
-* **Speed**. A central registry makes it possible to easily fetch just
- the metadata for packages quickly and efficiently, and then to
- efficiently download just the published package, and not other bloat
- that happens to exist in the repository. This adds up to a significant
- improvement in the speed of dependency resolution and fetching. As
- dependency graphs scale up, downloading all of the git repositories bogs
- down fast. Also remember that not everybody has a high-speed,
- low-latency Internet connection.
-
-### Will Cargo work with C code (or other languages)?
-
-Yes!
-
-Cargo handles compiling Rust code, but we know that many Rust projects
-link against C code. We also know that there are decades of tooling
-built up around compiling languages other than Rust.
-
-Our solution: Cargo allows a package to [specify a script](reference/build-scripts.html)
-(written in Rust) to run before invoking `rustc`. Rust is leveraged to
-implement platform-specific configuration and refactor out common build
-functionality among packages.
-
-### Can Cargo be used inside of `make` (or `ninja`, or ...)
-
-Indeed. While we intend Cargo to be useful as a standalone way to
-compile Rust projects at the top-level, we know that some people will
-want to invoke Cargo from other build tools.
-
-We have designed Cargo to work well in those contexts, paying attention
-to things like error codes and machine-readable output modes. We still
-have some work to do on those fronts, but using Cargo in the context of
-conventional scripts is something we designed for from the beginning and
-will continue to prioritize.
-
-### Does Cargo handle multi-platform projects or cross-compilation?
-
-Rust itself provides facilities for configuring sections of code based
-on the platform. Cargo also supports [platform-specific
-dependencies][target-deps], and we plan to support more per-platform
-configuration in `Cargo.toml` in the future.
-
-[target-deps]: reference/specifying-dependencies.html#platform-specific-dependencies
-
-In the longer-term, we’re looking at ways to conveniently cross-compile
-projects using Cargo.
-
-### Does Cargo support environments, like `production` or `test`?
-
-We support environments through the use of [profiles][profile] to support:
-
-[profile]: reference/manifest.html#the-profile-sections
-
-* environment-specific flags (like `-g --opt-level=0` for development
- and `--opt-level=3` for production).
-* environment-specific dependencies (like `hamcrest` for test assertions).
-* environment-specific `#[cfg]`
-* a `cargo test` command
-
-### Does Cargo work on Windows?
-
-Yes!
-
-All commits to Cargo are required to pass the local test suite on Windows.
-If, however, you find a Windows issue, we consider it a bug, so [please file an
-issue][3].
-
-[3]: https://github.com/rust-lang/cargo/issues
-
-### Why do binaries have `Cargo.lock` in version control, but not libraries?
-
-The purpose of a `Cargo.lock` is to describe the state of the world at the time
-of a successful build. It is then used to provide deterministic builds across
-whatever machine is building the project by ensuring that the exact same
-dependencies are being compiled.
-
-This property is most desirable from applications and projects which are at the
-very end of the dependency chain (binaries). As a result, it is recommended that
-all binaries check in their `Cargo.lock`.
-
-For libraries the situation is somewhat different. A library is not only used by
-the library developers, but also any downstream consumers of the library. Users
-dependent on the library will not inspect the library’s `Cargo.lock` (even if it
-exists). This is precisely because a library should **not** be deterministically
-recompiled for all users of the library.
-
-If a library ends up being used transitively by several dependencies, it’s
-likely that just a single copy of the library is desired (based on semver
-compatibility). If all libraries were to check in their `Cargo.lock`, then
-multiple copies of the library would be used, and perhaps even a version
-conflict.
-
-In other words, libraries specify semver requirements for their dependencies but
-cannot see the full picture. Only end products like binaries have a full
-picture to decide what versions of dependencies should be used.
-
-### Can libraries use `*` as a version for their dependencies?
-
-**As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries)
-with wildcard dependency constraints.**
-
-While libraries _can_, strictly speaking, they should not. A version requirement
-of `*` says “This will work with every version ever,” which is never going
-to be true. Libraries should always specify the range that they do work with,
-even if it’s something as general as “every 1.x.y version.”
-
-### Why `Cargo.toml`?
-
-As one of the most frequent interactions with Cargo, the question of why the
-configuration file is named `Cargo.toml` arises from time to time. The leading
-capital-`C` was chosen to ensure that the manifest was grouped with other
-similar configuration files in directory listings. Sorting files often puts
-capital letters before lowercase letters, ensuring files like `Makefile` and
-`Cargo.toml` are placed together. The trailing `.toml` was chosen to emphasize
-the fact that the file is in the [TOML configuration
-format](https://github.com/toml-lang/toml).
-
-Cargo does not allow other names such as `cargo.toml` or `Cargofile` to
-emphasize the ease of how a Cargo repository can be identified. An option of
-many possible names has historically led to confusion where one case was handled
-but others were accidentally forgotten.
-
-[crates.io]: https://crates.io/
-
-### How can Cargo work offline?
-
-Cargo is often used in situations with limited or no network access such as
-airplanes, CI environments, or embedded in large production deployments. Users
-are often surprised when Cargo attempts to fetch resources from the network, and
-hence the request for Cargo to work offline comes up frequently.
-
-Cargo, at its heart, will not attempt to access the network unless told to do
-so. That is, if no crates comes from crates.io, a git repository, or some other
-network location, Cargo will never attempt to make a network connection. As a
-result, if Cargo attempts to touch the network, then it's because it needs to
-fetch a required resource.
-
-Cargo is also quite aggressive about caching information to minimize the amount
-of network activity. It will guarantee, for example, that if `cargo build` (or
-an equivalent) is run to completion then the next `cargo build` is guaranteed to
-not touch the network so long as `Cargo.toml` has not been modified in the
-meantime. This avoidance of the network boils down to a `Cargo.lock` existing
-and a populated cache of the crates reflected in the lock file. If either of
-these components are missing, then they're required for the build to succeed and
-must be fetched remotely.
-
-As of Rust 1.11.0 Cargo understands a new flag, `--frozen`, which is an
-assertion that it shouldn't touch the network. When passed, Cargo will
-immediately return an error if it would otherwise attempt a network request.
-The error should include contextual information about why the network request is
-being made in the first place to help debug as well. Note that this flag *does
-not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch
-the network as a previous command has been run to ensure that network activity
-shouldn't be necessary.
-
-For more information about vendoring, see documentation on [source
-replacement][replace].
-
-[replace]: reference/source-replacement.html
+++ /dev/null
-## First Steps with Cargo
-
-To start a new project with Cargo, use `cargo new`:
-
-```shell
-$ cargo new hello_world --bin
-```
-
-We’re passing `--bin` because we’re making a binary program: if we
-were making a library, we’d leave it off.
-
-Let’s check out what Cargo has generated for us:
-
-```shell
-$ cd hello_world
-$ tree .
-.
-├── Cargo.toml
-└── src
- └── main.rs
-
-1 directory, 2 files
-```
-
-This is all we need to get started. First, let’s check out `Cargo.toml`:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-```
-
-This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
-
-Here’s what’s in `src/main.rs`:
-
-```rust
-fn main() {
- println!("Hello, world!");
-}
-```
-
-Cargo generated a “hello world” for us. Let’s compile it:
-
-```shell
-$ cargo build
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-And then run it:
-
-```shell
-$ ./target/debug/hello_world
-Hello, world!
-```
-
-We can also use `cargo run` to compile and then run it, all in one step:
-
-```shell
-$ cargo run
- Fresh hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running `target/hello_world`
-Hello, world!
-```
-
-### Going further
-
-For more details on using Cargo, check out the [Cargo Guide](guide/index.html)
+++ /dev/null
-## Getting Started
-
-To get started with Cargo, install Cargo (and Rust) and set up your first crate.
-
-* [Installation](getting-started/installation.html)
-* [First steps with Cargo](getting-started/first-steps.html)
+++ /dev/null
-## Installation
-
-### Install Stable Rust and Cargo
-
-The easiest way to get Cargo is to get the current stable release of [Rust] by
-using the `rustup` script:
-
-```shell
-$ curl -sSf https://static.rust-lang.org/rustup.sh | sh
-```
-
-After this, you can use the `rustup` command to also install `beta` or `nightly`
-channels for Rust and Cargo.
-
-### Install Nightly Cargo
-
-To install just Cargo, the current recommended installation method is through
-the official nightly builds. Note that Cargo will also require that [Rust] is
-already installed on the system.
-
-| Platform | 64-bit | 32-bit |
-|------------------|-------------------|-------------------|
-| Linux binaries | [tar.gz][linux64] | [tar.gz][linux32] |
-| MacOS binaries | [tar.gz][mac64] | [tar.gz][mac32] |
-| Windows binaries | [tar.gz][win64] | [tar.gz][win32] |
-
-### Build and Install Cargo from Source
-
-Alternatively, you can [build Cargo from source][compiling-from-source].
-
-[rust]: https://www.rust-lang.org/
-[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz
-[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz
-[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz
-[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz
-[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz
-[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz
-[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source
+++ /dev/null
-## Cargo.toml vs Cargo.lock
-
-`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
-about them, here’s a summary:
-
-* `Cargo.toml` is about describing your dependencies in a broad sense, and is
- written by you.
-* `Cargo.lock` contains exact information about your dependencies. It is
- maintained by Cargo and should not be manually edited.
-
-If you’re building a library that other projects will depend on, put
-`Cargo.lock` in your `.gitignore`. If you’re building an executable like a
-command-line tool or an application, check `Cargo.lock` into `git`. If you're
-curious about why that is, see ["Why do binaries have `Cargo.lock` in version
-control, but not libraries?" in the
-FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
-
-Let’s dig in a little bit more.
-
-`Cargo.toml` is a **manifest** file in which we can specify a bunch of
-different metadata about our project. For example, we can say that we depend
-on another project:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-This project has a single dependency, on the `rand` library. We’ve stated in
-this case that we’re relying on a particular Git repository that lives on
-GitHub. Since we haven’t specified any other information, Cargo assumes that
-we intend to use the latest commit on the `master` branch to build our project.
-
-Sound good? Well, there’s one problem: If you build this project today, and
-then you send a copy to me, and I build this project tomorrow, something bad
-could happen. There could be more commits to `rand` in the meantime, and my
-build would include new commits while yours would not. Therefore, we would
-get different builds. This would be bad because we want reproducible builds.
-
-We could fix this problem by putting a `rev` line in our `Cargo.toml`:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
-```
-
-Now our builds will be the same. But there’s a big drawback: now we have to
-manually think about SHA-1s every time we want to update our library. This is
-both tedious and error prone.
-
-Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
-keep track of the exact revisions: Cargo will do it for us. When we have a
-manifest like this:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-Cargo will take the latest commit and write that information out into our
-`Cargo.lock` when we build for the first time. That file will look like this:
-
-```toml
-[[package]]
-name = "hello_world"
-version = "0.1.0"
-dependencies = [
- "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)",
-]
-
-[[package]]
-name = "rand"
-version = "0.1.0"
-source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-```
-
-You can see that there’s a lot more information here, including the exact
-revision we used to build. Now when you give your project to someone else,
-they’ll use the exact same SHA, even though we didn’t specify it in our
-`Cargo.toml`.
-
-When we’re ready to opt in to a new version of the library, Cargo can
-re-calculate the dependencies and update things for us:
-
-```shell
-$ cargo update # updates all dependencies
-$ cargo update -p rand # updates just “rand”
-```
-
-This will write out a new `Cargo.lock` with the new version information. Note
-that the argument to `cargo update` is actually a
-[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
-specification.
+++ /dev/null
-## Continuous Integration
-
-### Travis CI
-
-To test your project on Travis CI, here is a sample `.travis.yml` file:
-
-```yaml
-language: rust
-rust:
- - stable
- - beta
- - nightly
-matrix:
- allow_failures:
- - rust: nightly
-```
-
-This will test all three release channels, but any breakage in nightly
-will not fail your overall build. Please see the [Travis CI Rust
-documentation](https://docs.travis-ci.com/user/languages/rust/) for more
-information.
+++ /dev/null
-## Creating a New Project
-
-To start a new project with Cargo, use `cargo new`:
-
-```shell
-$ cargo new hello_world --bin
-```
-
-We’re passing `--bin` because we’re making a binary program: if we
-were making a library, we’d leave it off. This also initializes a new `git`
-repository by default. If you don't want it to do that, pass `--vcs none`.
-
-Let’s check out what Cargo has generated for us:
-
-```shell
-$ cd hello_world
-$ tree .
-.
-├── Cargo.toml
-└── src
- └── main.rs
-
-1 directory, 2 files
-```
-
-If we had just used `cargo new hello_world` without the `--bin` flag, then
-we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
-we need to get started. First, let’s check out `Cargo.toml`:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-```
-
-This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
-
-Here’s what’s in `src/main.rs`:
-
-```rust
-fn main() {
- println!("Hello, world!");
-}
-```
-
-Cargo generated a “hello world” for us. Let’s compile it:
-
-```shell
-$ cargo build
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-And then run it:
-
-```shell
-$ ./target/debug/hello_world
-Hello, world!
-```
-
-We can also use `cargo run` to compile and then run it, all in one step (You
-won't see the `Compiling` line if you have not made any changes since you last
-compiled):
-
-```shell
-$ cargo run
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running `target/debug/hello_world`
-Hello, world!
-```
-
-You’ll now notice a new file, `Cargo.lock`. It contains information about our
-dependencies. Since we don’t have any yet, it’s not very interesting.
-
-Once you’re ready for release, you can use `cargo build --release` to compile
-your files with optimizations turned on:
-
-```shell
-$ cargo build --release
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-`cargo build --release` puts the resulting binary in `target/release` instead of
-`target/debug`.
-
-Compiling in debug mode is the default for development-- compilation time is
-shorter since the compiler doesn't do optimizations, but the code will run
-slower. Release mode takes longer to compile, but the code will run faster.
+++ /dev/null
-## Dependencies
-
-[crates.io] is the Rust community's central package registry that serves as a
-location to discover and download packages. `cargo` is configured to use it by
-default to find requested packages.
-
-To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.
-
-[crates.io]: https://crates.io/
-
-### Adding a dependency
-
-If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
-then list the crate name and version that you would like to use. This example
-adds a dependency of the `time` crate:
-
-```toml
-[dependencies]
-time = "0.1.12"
-```
-
-The version string is a [semver] version requirement. The [specifying
-dependencies](reference/specifying-dependencies.html) docs have more information about
-the options you have here.
-
-[semver]: https://github.com/steveklabnik/semver#requirements
-
-If we also wanted to add a dependency on the `regex` crate, we would not need
-to add `[dependencies]` for each crate listed. Here's what your whole
-`Cargo.toml` file would look like with dependencies on the `time` and `regex`
-crates:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-time = "0.1.12"
-regex = "0.1.41"
-```
-
-Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
-their dependencies, compile them all, and update the `Cargo.lock`:
-
-```shell
-$ cargo build
- Updating registry `https://github.com/rust-lang/crates.io-index`
- Downloading memchr v0.1.5
- Downloading libc v0.1.10
- Downloading regex-syntax v0.2.1
- Downloading memchr v0.1.5
- Downloading aho-corasick v0.3.0
- Downloading regex v0.1.41
- Compiling memchr v0.1.5
- Compiling libc v0.1.10
- Compiling regex-syntax v0.2.1
- Compiling memchr v0.1.5
- Compiling aho-corasick v0.3.0
- Compiling regex v0.1.41
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-Our `Cargo.lock` contains the exact information about which revision of all of
-these dependencies we used.
-
-Now, if `regex` gets updated, we will still build with the same revision until
-we choose to `cargo update`.
-
-You can now use the `regex` library using `extern crate` in `main.rs`.
-
-```
-extern crate regex;
-
-use regex::Regex;
-
-fn main() {
- let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
- println!("Did our date match? {}", re.is_match("2014-01-01"));
-}
-```
-
-Running it will show:
-
-```shell
-$ cargo run
- Running `target/hello_world`
-Did our date match? true
-```
+++ /dev/null
-## Cargo Guide
-
-This guide will give you all that you need to know about how to use Cargo to
-develop Rust projects.
-
-* [Why Cargo Exists](guide/why-cargo-exists.html)
-* [Creating a New Project](guide/creating-a-new-project.html)
-* [Working on an Existing Cargo Project](guide/working-on-an-existing-project.html)
-* [Dependencies](guide/dependencies.html)
-* [Project Layout](guide/project-layout.html)
-* [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
-* [Tests](guide/tests.html)
-* [Continuous Integration](guide/continuous-integration.html)
+++ /dev/null
-## Project Layout
-
-Cargo uses conventions for file placement to make it easy to dive into a new
-Cargo project:
-
-```shell
-.
-├── Cargo.lock
-├── Cargo.toml
-├── benches
-│ └── large-input.rs
-├── examples
-│ └── simple.rs
-├── src
-│ ├── bin
-│ │ └── another_executable.rs
-│ ├── lib.rs
-│ └── main.rs
-└── tests
- └── some-integration-tests.rs
-```
-
-* `Cargo.toml` and `Cargo.lock` are stored in the root of your project (*package
- root*).
-* Source code goes in the `src` directory.
-* The default library file is `src/lib.rs`.
-* The default executable file is `src/main.rs`.
-* Other executables can be placed in `src/bin/*.rs`.
-* Integration tests go in the `tests` directory (unit tests go in each file
- they're testing).
-* Examples go in the `examples` directory.
-* Benchmarks go in the `benches` directory.
-
-These are explained in more detail in the [manifest
-description](reference/manifest.html#the-project-layout).
+++ /dev/null
-## Tests
-
-Cargo can run your tests with the `cargo test` command. Cargo looks for tests
-to run in two places: in each of your `src` files and any tests in `tests/`.
-Tests in your `src` files should be unit tests, and tests in `tests/` should be
-integration-style tests. As such, you’ll need to import your crates into
-the files in `tests`.
-
-Here's an example of running `cargo test` in our project, which currently has
-no tests:
-
-```shell
-$ cargo test
- Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running target/test/hello_world-9c2b65bbb79eabce
-
-running 0 tests
-
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
-```
-
-If our project had tests, we would see more output with the correct number of
-tests.
-
-You can also run a specific test by passing a filter:
-
-```shell
-$ cargo test foo
-```
-
-This will run any test with `foo` in its name.
-
-`cargo test` runs additional checks as well. For example, it will compile any
-examples you’ve included and will also test the examples in your
-documentation. Please see the [testing guide][testing] in the Rust
-documentation for more details.
-
-[testing]: https://doc.rust-lang.org/book/testing.html
+++ /dev/null
-## Why Cargo Exists
-
-Cargo is a tool that allows Rust projects to declare their various
-dependencies and ensure that you’ll always get a repeatable build.
-
-To accomplish this goal, Cargo does four things:
-
-* Introduces two metadata files with various bits of project information.
-* Fetches and builds your project’s dependencies.
-* Invokes `rustc` or another build tool with the correct parameters to build
- your project.
-* Introduces conventions to make working with Rust projects easier.
+++ /dev/null
-## Working on an Existing Cargo Project
-
-If you download an existing project that uses Cargo, it’s really easy
-to get going.
-
-First, get the project from somewhere. In this example, we’ll use `rand`
-cloned from its repository on GitHub:
-
-```shell
-$ git clone https://github.com/rust-lang-nursery/rand.git
-$ cd rand
-```
-
-To build, use `cargo build`:
-
-```shell
-$ cargo build
- Compiling rand v0.1.0 (file:///path/to/project/rand)
-```
-
-This will fetch all of the dependencies and then build them, along with the
-project.
+++ /dev/null
-# The Cargo Book
-
-
-
-Cargo is the [Rust] *package manager*. Cargo downloads your Rust project’s
-dependencies, compiles your project, makes packages, and upload them to
-[crates.io], the Rust community’s *package registry*.
-
-
-### Sections
-
-**[Getting Started](getting-started/index.html)**
-
-To get started with Cargo, install Cargo (and Rust) and set up your first crate.
-
-**[Cargo Guide](guide/index.html)**
-
-The guide will give you all you need to know about how to use Cargo to develop
-Rust projects.
-
-**[Cargo Reference](reference/index.html)**
-
-The reference covers the details of various areas of Cargo.
-
-**[Frequently Asked Questions](faq.html)**
-
-[rust]: https://www.rust-lang.org/
-[crates.io]: https://crates.io/
+++ /dev/null
-## Build Scripts
-
-Some packages need to compile third-party non-Rust code, for example C
-libraries. Other packages need to link to C libraries which can either be
-located on the system or possibly need to be built from source. Others still
-need facilities for functionality such as code generation before building (think
-parser generators).
-
-Cargo does not aim to replace other tools that are well-optimized for
-these tasks, but it does integrate with them with the `build` configuration
-option.
-
-```toml
-[package]
-# ...
-build = "build.rs"
-```
-
-The Rust file designated by the `build` command (relative to the package root)
-will be compiled and invoked before anything else is compiled in the package,
-allowing your Rust code to depend on the built or generated artifacts.
-By default Cargo looks up for `"build.rs"` file in a package root (even if you
-do not specify a value for `build`). Use `build = "custom_build_name.rs"` to specify
-a custom build name or `build = false` to disable automatic detection of the build script.
-
-Some example use cases of the build command are:
-
-* Building a bundled C library.
-* Finding a C library on the host system.
-* Generating a Rust module from a specification.
-* Performing any platform-specific configuration needed for the crate.
-
-Each of these use cases will be detailed in full below to give examples of how
-the build command works.
-
-### Inputs to the Build Script
-
-When the build script is run, there are a number of inputs to the build script,
-all passed in the form of [environment variables][env].
-
-In addition to environment variables, the build script’s current directory is
-the source directory of the build script’s package.
-
-[env]: reference/environment-variables.html
-
-### Outputs of the Build Script
-
-All the lines printed to stdout by a build script are written to a file like
-`target/debug/build/<pkg>/output` (the precise location may depend on your
-configuration). Any line that starts with `cargo:` is interpreted directly by
-Cargo. This line must be of the form `cargo:key=value`, like the examples below:
-
-```shell
-# specially recognized by Cargo
-cargo:rustc-link-lib=static=foo
-cargo:rustc-link-search=native=/path/to/foo
-cargo:rustc-cfg=foo
-cargo:rustc-env=FOO=bar
-# arbitrary user-defined metadata
-cargo:root=/path/to/foo
-cargo:libdir=/path/to/foo/lib
-cargo:include=/path/to/foo/include
-```
-
-On the other hand, lines printed to stderr are written to a file like
-`target/debug/build/<pkg>/stderr` but are not interpreted by cargo.
-
-There are a few special keys that Cargo recognizes, some affecting how the
-crate is built:
-
-* `rustc-link-lib=[KIND=]NAME` indicates that the specified value is a library
- name and should be passed to the compiler as a `-l` flag. The optional `KIND`
- can be one of `static`, `dylib` (the default), or `framework`, see
- `rustc --help` for more details.
-* `rustc-link-search=[KIND=]PATH` indicates the specified value is a library
- search path and should be passed to the compiler as a `-L` flag. The optional
- `KIND` can be one of `dependency`, `crate`, `native`, `framework` or `all`
- (the default), see `rustc --help` for more details.
-* `rustc-flags=FLAGS` is a set of flags passed to the compiler, only `-l` and
- `-L` flags are supported.
-* `rustc-cfg=FEATURE` indicates that the specified feature will be passed as a
- `--cfg` flag to the compiler. This is often useful for performing compile-time
- detection of various features.
-* `rustc-env=VAR=VALUE` indicates that the specified environment variable
- will be added to the environment which the compiler is run within.
- The value can be then retrieved by the `env!` macro in the compiled crate.
- This is useful for embedding additional metadata in crate's code,
- such as the hash of Git HEAD or the unique identifier of a continuous
- integration server.
-* `rerun-if-changed=PATH` is a path to a file or directory which indicates that
- the build script should be re-run if it changes (detected by a more-recent
- last-modified timestamp on the file). Normally build scripts are re-run if
- any file inside the crate root changes, but this can be used to scope changes
- to just a small set of files. (If this path points to a directory the entire
- directory will not be traversed for changes -- only changes to the timestamp
- of the directory itself (which corresponds to some types of changes within the
- directory, depending on platform) will trigger a rebuild. To request a re-run
- on any changes within an entire directory, print a line for the directory and
- another line for everything inside it, recursively.)
- Note that if the build script itself (or one of its dependencies) changes,
- then it's rebuilt and rerun unconditionally, so
- `cargo:rerun-if-changed=build.rs` is almost always redundant (unless you
- want to ignore changes in all other files except for `build.rs`).
-* `rerun-if-env-changed=VAR` is the name of an environment variable which
- indicates that if the environment variable's value changes the build script
- should be rerun. This basically behaves the same as `rerun-if-changed` except
- that it works with environment variables instead. Note that the environment
- variables here are intended for global environment variables like `CC` and
- such, it's not necessary to use this for env vars like `TARGET` that Cargo
- sets. Also note that if `rerun-if-env-changed` is printed out then Cargo will
- *only* rerun the build script if those environment variables change or if
- files printed out by `rerun-if-changed` change.
-
-* `warning=MESSAGE` is a message that will be printed to the main console after
- a build script has finished running. Warnings are only shown for path
- dependencies (that is, those you're working on locally), so for example
- warnings printed out in crates.io crates are not emitted by default.
-
-Any other element is a user-defined metadata that will be passed to
-dependents. More information about this can be found in the [`links`][links]
-section.
-
-[links]: #the-links-manifest-key
-
-### Build Dependencies
-
-Build scripts are also allowed to have dependencies on other Cargo-based crates.
-Dependencies are declared through the `build-dependencies` section of the
-manifest.
-
-```toml
-[build-dependencies]
-foo = { git = "https://github.com/your-packages/foo" }
-```
-
-The build script **does not** have access to the dependencies listed in the
-`dependencies` or `dev-dependencies` section (they’re not built yet!). All build
-dependencies will also not be available to the package itself unless explicitly
-stated as so.
-
-### The `links` Manifest Key
-
-In addition to the manifest key `build`, Cargo also supports a `links` manifest
-key to declare the name of a native library that is being linked to:
-
-```toml
-[package]
-# ...
-links = "foo"
-build = "build.rs"
-```
-
-This manifest states that the package links to the `libfoo` native library, and
-it also has a build script for locating and/or building the library. Cargo
-requires that a `build` command is specified if a `links` entry is also
-specified.
-
-The purpose of this manifest key is to give Cargo an understanding about the set
-of native dependencies that a package has, as well as providing a principled
-system of passing metadata between package build scripts.
-
-Primarily, Cargo requires that there is at most one package per `links` value.
-In other words, it’s forbidden to have two packages link to the same native
-library. Note, however, that there are [conventions in place][star-sys] to
-alleviate this.
-
-[star-sys]: #-sys-packages
-
-As mentioned above in the output format, each build script can generate an
-arbitrary set of metadata in the form of key-value pairs. This metadata is
-passed to the build scripts of **dependent** packages. For example, if `libbar`
-depends on `libfoo`, then if `libfoo` generates `key=value` as part of its
-metadata, then the build script of `libbar` will have the environment variables
-`DEP_FOO_KEY=value`.
-
-Note that metadata is only passed to immediate dependents, not transitive
-dependents. The motivation for this metadata passing is outlined in the linking
-to system libraries case study below.
-
-### Overriding Build Scripts
-
-If a manifest contains a `links` key, then Cargo supports overriding the build
-script specified with a custom library. The purpose of this functionality is to
-prevent running the build script in question altogether and instead supply the
-metadata ahead of time.
-
-To override a build script, place the following configuration in any acceptable
-Cargo [configuration location](reference/config.html).
-
-```toml
-[target.x86_64-unknown-linux-gnu.foo]
-rustc-link-search = ["/path/to/foo"]
-rustc-link-lib = ["foo"]
-root = "/path/to/foo"
-key = "value"
-```
-
-This section states that for the target `x86_64-unknown-linux-gnu` the library
-named `foo` has the metadata specified. This metadata is the same as the
-metadata generated as if the build script had run, providing a number of
-key/value pairs where the `rustc-flags`, `rustc-link-search`, and
-`rustc-link-lib` keys are slightly special.
-
-With this configuration, if a package declares that it links to `foo` then the
-build script will **not** be compiled or run, and the metadata specified will
-instead be used.
-
-### Case study: Code generation
-
-Some Cargo packages need to have code generated just before they are compiled
-for various reasons. Here we’ll walk through a simple example which generates a
-library call as part of the build script.
-
-First, let’s take a look at the directory structure of this package:
-
-```shell
-.
-├── Cargo.toml
-├── build.rs
-└── src
- └── main.rs
-
-1 directory, 3 files
-```
-
-Here we can see that we have a `build.rs` build script and our binary in
-`main.rs`. Next, let’s take a look at the manifest:
-
-```toml
-# Cargo.toml
-
-[package]
-name = "hello-from-generated-code"
-version = "0.1.0"
-authors = ["you@example.com"]
-build = "build.rs"
-```
-
-Here we can see we’ve got a build script specified which we’ll use to generate
-some code. Let’s see what’s inside the build script:
-
-```rust,no_run
-// build.rs
-
-use std::env;
-use std::fs::File;
-use std::io::Write;
-use std::path::Path;
-
-fn main() {
- let out_dir = env::var("OUT_DIR").unwrap();
- let dest_path = Path::new(&out_dir).join("hello.rs");
- let mut f = File::create(&dest_path).unwrap();
-
- f.write_all(b"
- pub fn message() -> &'static str {
- \"Hello, World!\"
- }
- ").unwrap();
-}
-```
-
-There’s a couple of points of note here:
-
-* The script uses the `OUT_DIR` environment variable to discover where the
- output files should be located. It can use the process’ current working
- directory to find where the input files should be located, but in this case we
- don’t have any input files.
-* This script is relatively simple as it just writes out a small generated file.
- One could imagine that other more fanciful operations could take place such as
- generating a Rust module from a C header file or another language definition,
- for example.
-
-Next, let’s peek at the library itself:
-
-```rust,ignore
-// src/main.rs
-
-include!(concat!(env!("OUT_DIR"), "/hello.rs"));
-
-fn main() {
- println!("{}", message());
-}
-```
-
-This is where the real magic happens. The library is using the rustc-defined
-`include!` macro in combination with the `concat!` and `env!` macros to include
-the generated file (`hello.rs`) into the crate’s compilation.
-
-Using the structure shown here, crates can include any number of generated files
-from the build script itself.
-
-### Case study: Building some native code
-
-Sometimes it’s necessary to build some native C or C++ code as part of a
-package. This is another excellent use case of leveraging the build script to
-build a native library before the Rust crate itself. As an example, we’ll create
-a Rust library which calls into C to print “Hello, World!”.
-
-Like above, let’s first take a look at the project layout:
-
-```shell
-.
-├── Cargo.toml
-├── build.rs
-└── src
- ├── hello.c
- └── main.rs
-
-1 directory, 4 files
-```
-
-Pretty similar to before! Next, the manifest:
-
-```toml
-# Cargo.toml
-
-[package]
-name = "hello-world-from-c"
-version = "0.1.0"
-authors = ["you@example.com"]
-build = "build.rs"
-```
-
-For now we’re not going to use any build dependencies, so let’s take a look at
-the build script now:
-
-```rust,no_run
-// build.rs
-
-use std::process::Command;
-use std::env;
-use std::path::Path;
-
-fn main() {
- let out_dir = env::var("OUT_DIR").unwrap();
-
- // note that there are a number of downsides to this approach, the comments
- // below detail how to improve the portability of these commands.
- Command::new("gcc").args(&["src/hello.c", "-c", "-fPIC", "-o"])
- .arg(&format!("{}/hello.o", out_dir))
- .status().unwrap();
- Command::new("ar").args(&["crus", "libhello.a", "hello.o"])
- .current_dir(&Path::new(&out_dir))
- .status().unwrap();
-
- println!("cargo:rustc-link-search=native={}", out_dir);
- println!("cargo:rustc-link-lib=static=hello");
-}
-```
-
-This build script starts out by compiling our C file into an object file (by
-invoking `gcc`) and then converting this object file into a static library (by
-invoking `ar`). The final step is feedback to Cargo itself to say that our
-output was in `out_dir` and the compiler should link the crate to `libhello.a`
-statically via the `-l static=hello` flag.
-
-Note that there are a number of drawbacks to this hardcoded approach:
-
-* The `gcc` command itself is not portable across platforms. For example it’s
- unlikely that Windows platforms have `gcc`, and not even all Unix platforms
- may have `gcc`. The `ar` command is also in a similar situation.
-* These commands do not take cross-compilation into account. If we’re cross
- compiling for a platform such as Android it’s unlikely that `gcc` will produce
- an ARM executable.
-
-Not to fear, though, this is where a `build-dependencies` entry would help! The
-Cargo ecosystem has a number of packages to make this sort of task much easier,
-portable, and standardized. For example, the build script could be written as:
-
-```rust,ignore
-// build.rs
-
-// Bring in a dependency on an externally maintained `gcc` package which manages
-// invoking the C compiler.
-extern crate gcc;
-
-fn main() {
- gcc::compile_library("libhello.a", &["src/hello.c"]);
-}
-```
-
-Add a build time dependency on the `gcc` crate with the following addition to
-your `Cargo.toml`:
-
-```toml
-[build-dependencies]
-gcc = "0.3"
-```
-
-The [`gcc` crate](https://crates.io/crates/gcc) abstracts a range of build
-script requirements for C code:
-
-* It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc`
- for Unix platforms, etc.).
-* It takes the `TARGET` variable into account by passing appropriate flags to
- the compiler being used.
-* Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all
- handled automatically.
-* The stdout output and `OUT_DIR` locations are also handled by the `gcc`
- library.
-
-Here we can start to see some of the major benefits of farming as much
-functionality as possible out to common build dependencies rather than
-duplicating logic across all build scripts!
-
-Back to the case study though, let’s take a quick look at the contents of the
-`src` directory:
-
-```c
-// src/hello.c
-
-#include <stdio.h>
-
-void hello() {
- printf("Hello, World!\n");
-}
-```
-
-```rust,ignore
-// src/main.rs
-
-// Note the lack of the `#[link]` attribute. We’re delegating the responsibility
-// of selecting what to link to over to the build script rather than hardcoding
-// it in the source file.
-extern { fn hello(); }
-
-fn main() {
- unsafe { hello(); }
-}
-```
-
-And there we go! This should complete our example of building some C code from a
-Cargo package using the build script itself. This also shows why using a build
-dependency can be crucial in many situations and even much more concise!
-
-We’ve also seen a brief example of how a build script can use a crate as a
-dependency purely for the build process and not for the crate itself at runtime.
-
-### Case study: Linking to system libraries
-
-The final case study here will be investigating how a Cargo library links to a
-system library and how the build script is leveraged to support this use case.
-
-Quite frequently a Rust crate wants to link to a native library often provided
-on the system to bind its functionality or just use it as part of an
-implementation detail. This is quite a nuanced problem when it comes to
-performing this in a platform-agnostic fashion, and the purpose of a build
-script is again to farm out as much of this as possible to make this as easy as
-possible for consumers.
-
-As an example to follow, let’s take a look at one of [Cargo’s own
-dependencies][git2-rs], [libgit2][libgit2]. The C library has a number of
-constraints:
-
-[git2-rs]: https://github.com/alexcrichton/git2-rs/tree/master/libgit2-sys
-[libgit2]: https://github.com/libgit2/libgit2
-
-* It has an optional dependency on OpenSSL on Unix to implement the https
- transport.
-* It has an optional dependency on libssh2 on all platforms to implement the ssh
- transport.
-* It is often not installed on all systems by default.
-* It can be built from source using `cmake`.
-
-To visualize what’s going on here, let’s take a look at the manifest for the
-relevant Cargo package that links to the native C library.
-
-```toml
-[package]
-name = "libgit2-sys"
-version = "0.1.0"
-authors = ["..."]
-links = "git2"
-build = "build.rs"
-
-[dependencies]
-libssh2-sys = { git = "https://github.com/alexcrichton/ssh2-rs" }
-
-[target.'cfg(unix)'.dependencies]
-openssl-sys = { git = "https://github.com/alexcrichton/openssl-sys" }
-
-# ...
-```
-
-As the above manifests show, we’ve got a `build` script specified, but it’s
-worth noting that this example has a `links` entry which indicates that the
-crate (`libgit2-sys`) links to the `git2` native library.
-
-Here we also see that we chose to have the Rust crate have an unconditional
-dependency on `libssh2` via the `libssh2-sys` crate, as well as a
-platform-specific dependency on `openssl-sys` for \*nix (other variants elided
-for now). It may seem a little counterintuitive to express *C dependencies* in
-the *Cargo manifest*, but this is actually using one of Cargo’s conventions in
-this space.
-
-### `*-sys` Packages
-
-To alleviate linking to system libraries, Cargo has a *convention* of package
-naming and functionality. Any package named `foo-sys` will provide two major
-pieces of functionality:
-
-* The library crate will link to the native library `libfoo`. This will often
- probe the current system for `libfoo` before resorting to building from
- source.
-* The library crate will provide **declarations** for functions in `libfoo`,
- but it does **not** provide bindings or higher-level abstractions.
-
-The set of `*-sys` packages provides a common set of dependencies for linking
-to native libraries. There are a number of benefits earned from having this
-convention of native-library-related packages:
-
-* Common dependencies on `foo-sys` alleviates the above rule about one package
- per value of `links`.
-* A common dependency allows centralizing logic on discovering `libfoo` itself
- (or building it from source).
-* These dependencies are easily overridable.
-
-### Building libgit2
-
-Now that we’ve got libgit2’s dependencies sorted out, we need to actually write
-the build script. We’re not going to look at specific snippets of code here and
-instead only take a look at the high-level details of the build script of
-`libgit2-sys`. This is not recommending all packages follow this strategy, but
-rather just outlining one specific strategy.
-
-The first step of the build script should do is to query whether libgit2 is
-already installed on the host system. To do this we’ll leverage the preexisting
-tool `pkg-config` (when its available). We’ll also use a `build-dependencies`
-section to refactor out all the `pkg-config` related code (or someone’s already
-done that!).
-
-If `pkg-config` failed to find libgit2, or if `pkg-config` just wasn’t
-installed, the next step is to build libgit2 from bundled source code
-(distributed as part of `libgit2-sys` itself). There are a few nuances when
-doing so that we need to take into account, however:
-
-* The build system of libgit2, `cmake`, needs to be able to find libgit2’s
- optional dependency of libssh2. We’re sure we’ve already built it (it’s a
- Cargo dependency), we just need to communicate this information. To do this
- we leverage the metadata format to communicate information between build
- scripts. In this example the libssh2 package printed out `cargo:root=...` to
- tell us where libssh2 is installed at, and we can then pass this along to
- cmake with the `CMAKE_PREFIX_PATH` environment variable.
-
-* We’ll need to handle some `CFLAGS` values when compiling C code (and tell
- `cmake` about this). Some flags we may want to pass are `-m64` for 64-bit
- code, `-m32` for 32-bit code, or `-fPIC` for 64-bit code as well.
-
-* Finally, we’ll invoke `cmake` to place all output into the `OUT_DIR`
- environment variable, and then we’ll print the necessary metadata to instruct
- rustc how to link to libgit2.
-
-Most of the functionality of this build script is easily refactorable into
-common dependencies, so our build script isn’t quite as intimidating as this
-descriptions! In reality it’s expected that build scripts are quite succinct by
-farming logic such as above to build dependencies.
+++ /dev/null
-## Configuration
-
-This document will explain how Cargo’s configuration system works, as well as
-available keys or configuration. For configuration of a project through its
-manifest, see the [manifest format](reference/manifest.html).
-
-### Hierarchical structure
-
-
-Cargo allows local configuration for a particular project as well as global
-configuration, like git. Cargo extends this to a hierarchical strategy.
-If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the
-following configuration files would be probed for and unified in this order:
-
-* `/projects/foo/bar/baz/.cargo/config`
-* `/projects/foo/bar/.cargo/config`
-* `/projects/foo/.cargo/config`
-* `/projects/.cargo/config`
-* `/.cargo/config`
-* `$HOME/.cargo/config`
-
-With this structure, you can specify configuration per-project, and even
-possibly check it into version control. You can also specify personal defaults
-with a configuration file in your home directory.
-
-### Configuration format
-
-All configuration is currently in the [TOML format][toml] (like the manifest),
-with simple key-value pairs inside of sections (tables) which all get merged
-together.
-
-[toml]: https://github.com/toml-lang/toml
-
-### Configuration keys
-
-All of the following keys are optional, and their defaults are listed as their
-value unless otherwise noted.
-
-Key values that specify a tool may be given as an absolute path, a relative path
-or as a pathless tool name. Absolute paths and pathless tool names are used as
-given. Relative paths are resolved relative to the parent directory of the
-`.cargo` directory of the config file that the value resides within.
-
-```toml
-# An array of paths to local repositories which are to be used as overrides for
-# dependencies. For more information see the Specifying Dependencies guide.
-paths = ["/path/to/override"]
-
-[cargo-new]
-# This is your name/email to place in the `authors` section of a new Cargo.toml
-# that is generated. If not present, then `git` will be probed, and if that is
-# not present then `$USER` and `$EMAIL` will be used.
-name = "..."
-email = "..."
-
-# By default `cargo new` will initialize a new Git repository. This key can be
-# set to `hg` to create a Mercurial repository, or `none` to disable this
-# behavior.
-vcs = "none"
-
-# For the following sections, $triple refers to any valid target triple, not the
-# literal string "$triple", and it will apply whenever that target triple is
-# being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for
-# conditional compilation.
-[target.$triple]
-# This is the linker which is passed to rustc (via `-C linker=`) when the `$triple`
-# is being compiled for. By default this flag is not passed to the compiler.
-linker = ".."
-# Same but for the library archiver which is passed to rustc via `-C ar=`.
-ar = ".."
-# If a runner is provided, compiled targets for the `$triple` will be executed
-# by invoking the specified runner executable with actual target as first argument.
-# This applies to `cargo run`, `cargo test` and `cargo bench` commands.
-# By default compiled targets are executed directly.
-runner = ".."
-# custom flags to pass to all compiler invocations that target $triple
-# this value overrides build.rustflags when both are present
-rustflags = ["..", ".."]
-
-[target.'cfg(...)']
-# Similar for the $triple configuration, but using the `cfg` syntax.
-# If several `cfg` and $triple targets are candidates, then the rustflags
-# are concatenated. The `cfg` syntax only applies to rustflags, and not to
-# linker.
-rustflags = ["..", ".."]
-
-# Configuration keys related to the registry
-[registry]
-index = "..." # URL of the registry index (defaults to the central repository)
-token = "..." # Access token (found on the central repo’s website)
-
-[http]
-proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
- # in libcurl format, e.g. "socks5h://host:port"
-timeout = 60000 # Timeout for each HTTP request, in milliseconds
-cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
-check-revoke = true # Indicates whether SSL certs are checked for revocation
-
-[build]
-jobs = 1 # number of parallel jobs, defaults to # of CPUs
-rustc = "rustc" # the rust compiler tool
-rustdoc = "rustdoc" # the doc generator tool
-target = "triple" # build for the target triple
-target-dir = "target" # path of where to place all generated artifacts
-rustflags = ["..", ".."] # custom flags to pass to all compiler invocations
-
-[term]
-verbose = false # whether cargo provides verbose output
-color = 'auto' # whether cargo colorizes output
-
-# Network configuration
-[net]
-retry = 2 # number of times a network call will automatically retried
-
-# Alias cargo commands. The first 3 aliases are built in. If your
-# command requires grouped whitespace use the list format.
-[alias]
-b = "build"
-t = "test"
-r = "run"
-rr = "run --release"
-space_example = ["run", "--release", "--", "\"command list\""]
-```
-
-### Environment variables
-
-Cargo can also be configured through environment variables in addition to the
-TOML syntax above. For each configuration key above of the form `foo.bar` the
-environment variable `CARGO_FOO_BAR` can also be used to define the value. For
-example the `build.jobs` key can also be defined by `CARGO_BUILD_JOBS`.
-
-Environment variables will take precedent over TOML configuration, and currently
-only integer, boolean, and string keys are supported to be defined by
-environment variables.
-
-In addition to the system above, Cargo recognizes a few other specific
-[environment variables][env].
-
-[env]: reference/environment-variables.html
+++ /dev/null
-## Environment Variables
-
-Cargo sets and reads a number of environment variables which your code can detect
-or override. Here is a list of the variables Cargo sets, organized by when it interacts
-with them:
-
-### Environment variables Cargo reads
-
-You can override these environment variables to change Cargo's behavior on your
-system:
-
-* `CARGO_HOME` - Cargo maintains a local cache of the registry index and of git
- checkouts of crates. By default these are stored under `$HOME/.cargo`, but
- this variable overrides the location of this directory. Once a crate is cached
- it is not removed by the clean command.
-* `CARGO_TARGET_DIR` - Location of where to place all generated artifacts,
- relative to the current working directory.
-* `RUSTC` - Instead of running `rustc`, Cargo will execute this specified
- compiler instead.
-* `RUSTC_WRAPPER` - Instead of simply running `rustc`, Cargo will execute this
- specified wrapper instead, passing as its commandline arguments the rustc
- invocation, with the first argument being rustc.
-* `RUSTDOC` - Instead of running `rustdoc`, Cargo will execute this specified
- `rustdoc` instance instead.
-* `RUSTDOCFLAGS` - A space-separated list of custom flags to pass to all `rustdoc`
- invocations that Cargo performs. In contrast with `cargo rustdoc`, this is
- useful for passing a flag to *all* `rustdoc` instances.
-* `RUSTFLAGS` - A space-separated list of custom flags to pass to all compiler
- invocations that Cargo performs. In contrast with `cargo rustc`, this is
- useful for passing a flag to *all* compiler instances.
-
-Note that Cargo will also read environment variables for `.cargo/config`
-configuration values, as described in [that documentation][config-env]
-
-[config-env]: reference/config.html#environment-variables
-
-### Environment variables Cargo sets for crates
-
-Cargo exposes these environment variables to your crate when it is compiled.
-Note that this applies for test binaries as well.
-To get the value of any of these variables in a Rust program, do this:
-
-```rust
-let version = env!("CARGO_PKG_VERSION");
-```
-
-`version` will now contain the value of `CARGO_PKG_VERSION`.
-
-* `CARGO` - Path to the `cargo` binary performing the build.
-* `CARGO_MANIFEST_DIR` - The directory containing the manifest of your package.
-* `CARGO_PKG_VERSION` - The full version of your package.
-* `CARGO_PKG_VERSION_MAJOR` - The major version of your package.
-* `CARGO_PKG_VERSION_MINOR` - The minor version of your package.
-* `CARGO_PKG_VERSION_PATCH` - The patch version of your package.
-* `CARGO_PKG_VERSION_PRE` - The pre-release version of your package.
-* `CARGO_PKG_AUTHORS` - Colon separated list of authors from the manifest of your package.
-* `CARGO_PKG_NAME` - The name of your package.
-* `CARGO_PKG_DESCRIPTION` - The description of your package.
-* `CARGO_PKG_HOMEPAGE` - The home page of your package.
-* `OUT_DIR` - If the package has a build script, this is set to the folder where the build
- script should place its output. See below for more information.
-
-### Environment variables Cargo sets for build scripts
-
-Cargo sets several environment variables when build scripts are run. Because these variables
-are not yet set when the build script is compiled, the above example using `env!` won't work
-and instead you'll need to retrieve the values when the build script is run:
-
-```rust
-use std::env;
-let out_dir = env::var("OUT_DIR").unwrap();
-```
-
-`out_dir` will now contain the value of `OUT_DIR`.
-
-* `CARGO` - Path to the `cargo` binary performing the build.
-* `CARGO_MANIFEST_DIR` - The directory containing the manifest for the package
- being built (the package containing the build
- script). Also note that this is the value of the
- current working directory of the build script when it
- starts.
-* `CARGO_MANIFEST_LINKS` - the manifest `links` value.
-* `CARGO_FEATURE_<name>` - For each activated feature of the package being
- built, this environment variable will be present
- where `<name>` is the name of the feature uppercased
- and having `-` translated to `_`.
-* `CARGO_CFG_<cfg>` - For each [configuration option][configuration] of the
- package being built, this environment variable will
- contain the value of the configuration, where `<cfg>` is
- the name of the configuration uppercased and having `-`
- translated to `_`.
- Boolean configurations are present if they are set, and
- not present otherwise.
- Configurations with multiple values are joined to a
- single variable with the values delimited by `,`.
-* `OUT_DIR` - the folder in which all output should be placed. This folder is
- inside the build directory for the package being built, and it is
- unique for the package in question.
-* `TARGET` - the target triple that is being compiled for. Native code should be
- compiled for this triple. Some more information about target
- triples can be found in [clang’s own documentation][clang].
-* `HOST` - the host triple of the rust compiler.
-* `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can
- be useful to pass a `-j` parameter to a system like `make`. Note
- that care should be taken when interpreting this environment
- variable. For historical purposes this is still provided but
- recent versions of Cargo, for example, do not need to run `make
- -j` as it'll automatically happen. Cargo implements its own
- [jobserver] and will allow build scripts to inherit this
- information, so programs compatible with GNU make jobservers will
- already have appropriately configured parallelism.
-* `OPT_LEVEL`, `DEBUG` - values of the corresponding variables for the
- profile currently being built.
-* `PROFILE` - `release` for release builds, `debug` for other builds.
-* `DEP_<name>_<key>` - For more information about this set of environment
- variables, see build script documentation about [`links`][links].
-* `RUSTC`, `RUSTDOC` - the compiler and documentation generator that Cargo has
- resolved to use, passed to the build script so it might
- use it as well.
-
-[links]: reference/build-scripts.html#the-links-manifest-key
-[profile]: reference/manifest.html#the-profile-sections
-[configuration]: https://doc.rust-lang.org/reference/attributes.html#conditional-compilation
-[clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple
-
-### Environment variables Cargo sets for 3rd party subcommands
-
-Cargo exposes this environment variable to 3rd party subcommands
-(ie. programs named `cargo-foobar` placed in `$PATH`):
-
-* `CARGO` - Path to the `cargo` binary performing the build.
+++ /dev/null
-## External tools
-
-One of the goals of Cargo is simple integration with third-party tools, like
-IDEs and other build systems. To make integration easier, Cargo has several
-facilities:
-
-* a `cargo metadata` command, which outputs project structure and dependencies
- information in JSON,
-
-* a `--message-format` flag, which outputs information about a particular build,
- and
-
-* support for custom subcommands.
-
-
-### Information about project structure
-
-You can use `cargo metadata` command to get information about project structure
-and dependencies. The output of the command looks like this:
-
-```text
-{
- // Integer version number of the format.
- "version": integer,
-
- // List of packages for this workspace, including dependencies.
- "packages": [
- {
- // Opaque package identifier.
- "id": PackageId,
-
- "name": string,
-
- "version": string,
-
- "source": SourceId,
-
- // A list of declared dependencies, see `resolve` field for actual dependencies.
- "dependencies": [ Dependency ],
-
- "targets: [ Target ],
-
- // Path to Cargo.toml
- "manifest_path": string,
- }
- ],
-
- "workspace_members": [ PackageId ],
-
- // Dependencies graph.
- "resolve": {
- "nodes": [
- {
- "id": PackageId,
- "dependencies": [ PackageId ]
- }
- ]
- }
-}
-```
-
-The format is stable and versioned. When calling `cargo metadata`, you should
-pass `--format-version` flag explicitly to avoid forward incompatibility
-hazard.
-
-If you are using Rust, there is [cargo_metadata] crate.
-
-[cargo_metadata]: https://crates.io/crates/cargo_metadata
-
-
-### Information about build
-
-When passing `--message-format=json`, Cargo will output the following
-information during the build:
-
-* compiler errors and warnings,
-
-* produced artifacts,
-
-* results of the build scripts (for example, native dependencies).
-
-The output goes to stdout in the JSON object per line format. The `reason` field
-distinguishes different kinds of messages.
-
-Information about dependencies in the Makefile-compatible format is stored in
-the `.d` files alongside the artifacts.
-
-
-### Custom subcommands
-
-Cargo is designed to be extensible with new subcommands without having to modify
-Cargo itself. This is achieved by translating a cargo invocation of the form
-cargo `(?<command>[^ ]+)` into an invocation of an external tool
-`cargo-${command}` that then needs to be present in one of the user's `$PATH`
-directories.
-
-Custom subcommand may use `CARGO` environment variable to call back to
-Cargo. Alternatively, it can link to `cargo` crate as a library, but this
-approach has drawbacks:
-
-* Cargo as a library is unstable, API changes without deprecation,
-
-* versions of Cargo library and Cargo binary may be different.
+++ /dev/null
-## Cargo Reference
-
-Now that you have an overview of how to use Cargo and have created your first
-crate, you may be interested in more details in the following areas.
-
-The reference covers the details of various areas of Cargo.
-
-* [Specifying Dependencies](reference/specifying-dependencies.html)
-* [The Manifest Format](reference/manifest.html)
-* [Configuration](reference/config.html)
-* [Environment Variables](reference/environment-variables.html)
-* [Build Scripts](reference/build-scripts.html)
-* [Publishing on crates.io](reference/publishing.html)
-* [Package ID Specifications](reference/pkgid-spec.html)
-* [Source Replacement](reference/source-replacement.html)
-* [External Tools](reference/external-tools.html)
+++ /dev/null
-## The Manifest Format
-
-The `Cargo.toml` file for each package is called its *manifest*. Every manifest
-file consists of one or more sections.
-
-### The `[package]` section
-
-The first section in a `Cargo.toml` is `[package]`.
-
-```toml
-[package]
-name = "hello_world" # the name of the package
-version = "0.1.0" # the current version, obeying semver
-authors = ["you@example.com"]
-```
-
-All three of these fields are mandatory.
-
-#### The `version` field
-
-Cargo bakes in the concept of [Semantic
-Versioning](http://semver.org/), 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 Rust, 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 tiny
- 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.
-
-#### The `build` field (optional)
-
-This field specifies a file in the project root which is a [build script][1] for
-building native code. More information can be found in the build script
-[guide][1].
-
-[1]: reference/build-scripts.html
-
-```toml
-[package]
-# ...
-build = "build.rs"
-```
-
-#### The `documentation` field (optional)
-
-This field specifies a URL to a website hosting the crate's documentation.
-If no URL is specified in the manifest file, [crates.io][cratesio] will
-automatically link your crate to the corresponding [docs.rs][docsrs] page.
-
-Documentation links from specific hosts are blacklisted. Hosts are added
-to the blacklist if they are known to not be hosting documentation and are
-possibly of malicious intent e.g. ad tracking networks. URLs from the
-following hosts are blacklisted:
-
-* rust-ci.org
-
-Documentation URLs from blacklisted hosts will not appear on crates.io, and
-may be replaced by docs.rs links.
-
-[docsrs]: https://docs.rs/
-[cratesio]: https://crates.io/
-
-#### The `exclude` and `include` fields (optional)
-
-You can explicitly specify to Cargo that a set of [globs][globs] should be
-ignored or included for the purposes of packaging and rebuilding a package. The
-globs specified in the `exclude` field identify a set of files that are not
-included when a package is published as well as ignored for the purposes of
-detecting when to rebuild a package, and the globs in `include` specify files
-that are explicitly included.
-
-If a VCS is being used for a package, the `exclude` field will be seeded with
-the VCS’ ignore settings (`.gitignore` for git for example).
-
-```toml
-[package]
-# ...
-exclude = ["build/**/*.o", "doc/**/*.html"]
-```
-
-```toml
-[package]
-# ...
-include = ["src/**/*", "Cargo.toml"]
-```
-
-The options are mutually exclusive: setting `include` will override an
-`exclude`. Note that `include` must be an exhaustive list of files as otherwise
-necessary source files may not be included.
-
-[globs]: http://doc.rust-lang.org/glob/glob/struct.Pattern.html
-
-#### Migrating to `gitignore`-like pattern matching
-
-The current interpretation of these configs is based on UNIX Globs, as
-implemented in the [`glob` crate](https://crates.io/crates/glob). We want
-Cargo's `include` and `exclude` configs to work as similar to `gitignore` as
-possible. [The `gitignore` specification](https://git-scm.com/docs/gitignore) is
-also based on Globs, but has a bunch of additional features that enable easier
-pattern writing and more control. Therefore, we are migrating the interpretation
-for the rules of these configs to use the [`ignore`
-crate](https://crates.io/crates/ignore), and treat them each rule as a single
-line in a `gitignore` file. See [the tracking
-issue](https://github.com/rust-lang/cargo/issues/4268) for more details on the
-migration.
-
-#### The `publish` field (optional)
-
-The `publish` field can be used to prevent a package from being published to a
-package registry (like *crates.io*) by mistake.
-
-```toml
-[package]
-# ...
-publish = false
-```
-
-#### The `workspace` field (optional)
-
-The `workspace` field can be used to configure the workspace that this package
-will be a member of. If not specified this will be inferred as the first
-Cargo.toml with `[workspace]` upwards in the filesystem.
-
-```toml
-[package]
-# ...
-workspace = "path/to/workspace/root"
-```
-
-For more information, see the documentation for the workspace table below.
-
-#### Package metadata
-
-There are a number of optional metadata fields also accepted under the
-`[package]` section:
-
-```toml
-[package]
-# ...
-
-# A short blurb about the package. This is not rendered in any format when
-# uploaded to crates.io (aka this is not markdown).
-description = "..."
-
-# These URLs point to more information about the package. These are
-# intended to be webviews of the relevant data, not necessarily compatible
-# with VCS tools and the like.
-documentation = "..."
-homepage = "..."
-repository = "..."
-
-# This points to a file under the package root (relative to this `Cargo.toml`).
-# The contents of this file are stored and indexed in the registry.
-# crates.io will render this file and place the result on the crate's page.
-readme = "..."
-
-# This is a list of up to five keywords that describe this crate. Keywords
-# are searchable on crates.io, and you may choose any words that would
-# help someone find this crate.
-keywords = ["...", "..."]
-
-# This is a list of up to five categories where this crate would fit.
-# Categories are a fixed list available at crates.io/category_slugs, and
-# they must match exactly.
-categories = ["...", "..."]
-
-# This is an SPDX 2.1 license expression for this package. Currently
-# crates.io will validate the license provided against a whitelist of
-# known license and exception identifiers from the SPDX license list
-# 2.4. Parentheses are not currently supported.
-#
-# Multiple licenses can be separated with a `/`, although that usage
-# is deprecated. Instead, use a license expression with AND and OR
-# operators to get more explicit semantics.
-license = "..."
-
-# If a project is using a nonstandard license, then this key may be specified in
-# lieu of the above key and must point to a file relative to this manifest
-# (similar to the readme key).
-license-file = "..."
-
-# Optional specification of badges to be displayed on crates.io.
-#
-# - The badges pertaining to build status that are currently available are
-# Appveyor, CircleCI, GitLab, and TravisCI.
-# - Available badges pertaining to code test coverage are Codecov and
-# Coveralls.
-# - There are also maintenance-related badges basesed on isitmaintained.com
-# which state the issue resolution time, percent of open issues, and future
-# maintenance intentions.
-#
-# If a `repository` key is required, this refers to a repository in
-# `user/repo` format.
-[badges]
-
-# Appveyor: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`.
-appveyor = { repository = "...", branch = "master", service = "github" }
-
-# Circle CI: `repository` is required. `branch` is optional; default is `master`
-circle-ci = { repository = "...", branch = "master" }
-
-# GitLab: `repository` is required. `branch` is optional; default is `master`
-gitlab = { repository = "...", branch = "master" }
-
-# Travis CI: `repository` in format "<user>/<project>" is required.
-# `branch` is optional; default is `master`
-travis-ci = { repository = "...", branch = "master" }
-
-# Codecov: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`.
-codecov = { repository = "...", branch = "master", service = "github" }
-
-# Coveralls: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default) and `bitbucket`.
-coveralls = { repository = "...", branch = "master", service = "github" }
-
-# Is it maintained resolution time: `repository` is required.
-is-it-maintained-issue-resolution = { repository = "..." }
-
-# Is it maintained percentage of open issues: `repository` is required.
-is-it-maintained-open-issues = { repository = "..." }
-
-# Maintenance: `status` is required Available options are `actively-developed`,
-# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
-# and `deprecated`.
-maintenance = { status = "..." }
-```
-
-The [crates.io](https://crates.io) registry will render the description, display
-the license, link to the three URLs and categorize by the keywords. These keys
-provide useful information to users of the registry and also influence the
-search ranking of a crate. It is highly discouraged to omit everything in a
-published crate.
-
-SPDX 2.1 license expressions are documented
-[here][spdx-2.1-license-expressions]. The current version of the
-license list is available [here][spdx-license-list], and version 2.4
-is available [here][spdx-license-list-2.4].
-
-#### The `metadata` table (optional)
-
-Cargo by default will warn about unused keys in `Cargo.toml` to assist in
-detecting typos and such. The `package.metadata` table, however, is completely
-ignored by Cargo and will not be warned about. This section can be used for
-tools which would like to store project configuration in `Cargo.toml`. For
-example:
-
-```toml
-[package]
-name = "..."
-# ...
-
-# Metadata used when generating an Android APK, for example.
-[package.metadata.android]
-package-name = "my-awesome-android-app"
-assets = "path/to/static"
-```
-
-### Dependency sections
-
-See the [specifying dependencies page](reference/specifying-dependencies.html) for
-information on the `[dependencies]`, `[dev-dependencies]`,
-`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
-
-### The `[profile.*]` sections
-
-Cargo supports custom configuration of how rustc is invoked through profiles at
-the top level. Any manifest may declare a profile, but only the top level
-project’s profiles are actually read. All dependencies’ profiles will be
-overridden. This is done so the top-level project has control over how its
-dependencies are compiled.
-
-There are five currently supported profile names, all of which have the same
-configuration available to them. Listed below is the configuration available,
-along with the defaults for each profile.
-
-```toml
-# The development profile, used for `cargo build`.
-[profile.dev]
-opt-level = 0 # controls the `--opt-level` the compiler builds with.
- # 0-1 is good for debugging. 2 is well-optimized. Max is 3.
-debug = true # include debug information (debug symbols). Equivalent to
- # `-C debuginfo=2` compiler flag.
-rpath = false # controls whether compiler should set loader paths.
- # If true, passes `-C rpath` flag to the compiler.
-lto = false # Link Time Optimization usually reduces size of binaries
- # and static libraries. Increases compilation time.
- # If true, passes `-C lto` flag to the compiler.
-debug-assertions = true # controls whether debug assertions are enabled
- # (e.g. debug_assert!() and arithmetic overflow checks)
-codegen-units = 1 # if > 1 enables parallel code generation which improves
- # compile times, but prevents some optimizations.
- # Passes `-C codegen-units`. Ignored when `lto = true`.
-panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
-
-# The release profile, used for `cargo build --release`.
-[profile.release]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 1
-panic = 'unwind'
-
-# The testing profile, used for `cargo test`.
-[profile.test]
-opt-level = 0
-debug = 2
-rpath = false
-lto = false
-debug-assertions = true
-codegen-units = 1
-panic = 'unwind'
-
-# The benchmarking profile, used for `cargo bench` and `cargo test --release`.
-[profile.bench]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 1
-panic = 'unwind'
-
-# The documentation profile, used for `cargo doc`.
-[profile.doc]
-opt-level = 0
-debug = 2
-rpath = false
-lto = false
-debug-assertions = true
-codegen-units = 1
-panic = 'unwind'
-```
-
-### The `[features]` section
-
-Cargo supports features to allow expression of:
-
-* conditional compilation options (usable through `cfg` attributes);
-* optional dependencies, which enhance a package, but are not required; and
-* clusters of optional dependencies, such as `postgres`, that would include the
- `postgres` package, the `postgres-macros` package, and possibly other packages
- (such as development-time mocking libraries, debugging tools, etc.).
-
-A feature of a package is either an optional dependency, or a set of other
-features. The format for specifying features is:
-
-```toml
-[package]
-name = "awesome"
-
-[features]
-# The default set of optional packages. Most people will want to use these
-# packages, but they are strictly optional. Note that `session` is not a package
-# but rather another feature listed in this manifest.
-default = ["jquery", "uglifier", "session"]
-
-# A feature with no dependencies is used mainly for conditional compilation,
-# like `#[cfg(feature = "go-faster")]`.
-go-faster = []
-
-# The `secure-password` feature depends on the bcrypt package. This aliasing
-# will allow people to talk about the feature in a higher-level way and allow
-# this package to add more requirements to the feature in the future.
-secure-password = ["bcrypt"]
-
-# Features can be used to reexport features of other packages. The `session`
-# feature of package `awesome` will ensure that the `session` feature of the
-# package `cookie` is also enabled.
-session = ["cookie/session"]
-
-[dependencies]
-# These packages are mandatory and form the core of this package’s distribution.
-cookie = "1.2.0"
-oauth = "1.1.0"
-route-recognizer = "=2.1.0"
-
-# A list of all of the optional dependencies, some of which are included in the
-# above `features`. They can be opted into by apps.
-jquery = { version = "1.0.2", optional = true }
-uglifier = { version = "1.5.3", optional = true }
-bcrypt = { version = "*", optional = true }
-civet = { version = "*", optional = true }
-```
-
-To use the package `awesome`:
-
-```toml
-[dependencies.awesome]
-version = "1.3.5"
-default-features = false # do not include the default features, and optionally
- # cherry-pick individual features
-features = ["secure-password", "civet"]
-```
-
-#### Rules
-
-The usage of features is subject to a few rules:
-
-* Feature names must not conflict with other package names in the manifest. This
- is because they are opted into via `features = [...]`, which only has a single
- namespace.
-* With the exception of the `default` feature, all features are opt-in. To opt
- out of the default feature, use `default-features = false` and cherry-pick
- individual features.
-* Feature groups are not allowed to cyclically depend on one another.
-* Dev-dependencies cannot be optional.
-* Features groups can only reference optional dependencies.
-* When a feature is selected, Cargo will call `rustc` with `--cfg
- feature="${feature_name}"`. If a feature group is included, it and all of its
- individual features will be included. This can be tested in code via
- `#[cfg(feature = "foo")]`.
-
-Note that it is explicitly allowed for features to not actually activate any
-optional dependencies. This allows packages to internally enable/disable
-features without requiring a new dependency.
-
-#### Usage in end products
-
-One major use-case for this feature is specifying optional features in
-end-products. For example, the Servo project may want to include optional
-features that people can enable or disable when they build it.
-
-In that case, Servo will describe features in its `Cargo.toml` and they can be
-enabled using command-line flags:
-
-```shell
-$ cargo build --release --features "shumway pdf"
-```
-
-Default features could be excluded using `--no-default-features`.
-
-#### Usage in packages
-
-In most cases, the concept of *optional dependency* in a library is best
-expressed as a separate package that the top-level application depends on.
-
-However, high-level packages, like Iron or Piston, may want the ability to
-curate a number of packages for easy installation. The current Cargo system
-allows them to curate a number of mandatory dependencies into a single package
-for easy installation.
-
-In some cases, packages may want to provide additional curation for optional
-dependencies:
-
-* grouping a number of low-level optional dependencies together into a single
- high-level feature;
-* specifying packages that are recommended (or suggested) to be included by
- users of the package; and
-* including a feature (like `secure-password` in the motivating example) that
- will only work if an optional dependency is available, and would be difficult
- to implement as a separate package (for example, it may be overly difficult to
- design an IO package to be completely decoupled from OpenSSL, with opt-in via
- the inclusion of a separate package).
-
-In almost all cases, it is an antipattern to use these features outside of
-high-level packages that are designed for curation. If a feature is optional, it
-can almost certainly be expressed as a separate package.
-
-### The `[workspace]` section
-
-Projects can define a workspace which is a set of crates that will all share the
-same `Cargo.lock` and output directory. The `[workspace]` table can be defined
-as:
-
-```toml
-[workspace]
-
-# Optional key, inferred if not present
-members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-
-# Optional key, empty if not present
-exclude = ["path1", "path/to/dir2"]
-```
-
-Workspaces were added to Cargo as part of [RFC 1525] and have a number of
-properties:
-
-* A workspace can contain multiple crates where one of them is the *root crate*.
-* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
- required to have other configuration.
-* Whenever any crate in the workspace is compiled, output is placed in the
- *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`.
-* The lock file for all crates in the workspace resides in the *workspace root*.
-* The `[patch]` and `[replace]` sections in `Cargo.toml` are only recognized
- in the *root crate*'s manifest, and ignored in member crates' manifests.
-
-[RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
-
-The *root crate* of a workspace, indicated by the presence of `[workspace]` in
-its manifest, is responsible for defining the entire workspace. All `path`
-dependencies residing in the workspace directory become members. You can add
-additional packages to the workspace by listing them in the `members` key. Note
-that members of the workspaces listed explicitly will also have their path
-dependencies included in the workspace. Sometimes a project may have a lot of
-workspace members and it can be onerous to keep up to date. The path dependency
-can also use [globs][globs] to match multiple paths. Finally, the `exclude`
-key can be used to blacklist paths from being included in a workspace. This can
-be useful if some path dependencies aren't desired to be in the workspace at
-all.
-
-The `package.workspace` manifest key (described above) is used in member crates
-to point at a workspace's root crate. If this key is omitted then it is inferred
-to be the first crate whose manifest contains `[workspace]` upwards in the
-filesystem.
-
-A crate may either specify `package.workspace` or specify `[workspace]`. That
-is, a crate cannot both be a root crate in a workspace (contain `[workspace]`)
-and also be a member crate of another workspace (contain `package.workspace`).
-
-Most of the time workspaces will not need to be dealt with as `cargo new` and
-`cargo init` will handle workspace configuration automatically.
-
-#### Virtual Manifest
-
-In workspace manifests, if the `package` table is present, the workspace root
-crate will be treated as a normal package, as well as a worksapce. If the
-`package` table is not present in a worksapce manifest, it is called a *virtual
-manifest*.
-
-When working with *virtual manifests*, package-related cargo commands, like
-`cargo build`, won't be available anymore. But, most of such commands support
-the `--all` option, will execute the command for all the non-virtual manifest in
-the workspace.
-
-#TODO: move this to a more appropriate place
-### The project layout
-
-If your project is an executable, name the main source file `src/main.rs`. If it
-is a library, name the main source file `src/lib.rs`.
-
-Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
-executable consists of more than just one source file, you might also use a directory
-inside `src/bin` containing a `main.rs` file which will be treated as an executable
-with a name of the parent directory.
-Do note, however, once you add a `[[bin]]` section ([see
-below](#configuring-a-target)), Cargo will no longer automatically build files
-located in `src/bin/*.rs`. Instead you must create a `[[bin]]` section for
-each file you want to build.
-
-Your project can optionally contain folders named `examples`, `tests`, and
-`benches`, which Cargo will treat as containing examples,
-integration tests, and benchmarks respectively.
-
-```shell
-▾ src/ # directory containing source files
- lib.rs # the main entry point for libraries and packages
- main.rs # the main entry point for projects producing executables
- ▾ bin/ # (optional) directory containing additional executables
- *.rs
- ▾ */ # (optional) directories containing multi-file executables
- main.rs
-▾ examples/ # (optional) examples
- *.rs
-▾ tests/ # (optional) integration tests
- *.rs
-▾ benches/ # (optional) benchmarks
- *.rs
-```
-
-To structure your code after you've created the files and folders for your
-project, you should remember to use Rust's module system, which you can read
-about in [the book](https://doc.rust-lang.org/book/crates-and-modules.html).
-
-### Examples
-
-Files located under `examples` are example uses of the functionality provided by
-the library. When compiled, they are placed in the `target/examples` directory.
-
-They can compile either as executables (with a `main()` function) or libraries
-and pull in the library by using `extern crate <library-name>`. They are
-compiled when you run your tests to protect them from bitrotting.
-
-You can run individual executable examples with the command `cargo run --example
-<example-name>`.
-
-Specify `crate-type` to make an example be compiled as a library:
-
-```toml
-[[example]]
-name = "foo"
-crate-type = ["staticlib"]
-```
-
-You can build individual library examples with the command `cargo build
---example <example-name>`.
-
-### Tests
-
-When you run `cargo test`, Cargo will:
-
-* compile and run your library’s unit tests, which are in the files reachable
- from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
- considered at this stage);
-* compile and run your library’s documentation tests, which are embedded inside
- of documentation blocks;
-* compile and run your library’s [integration tests](#integration-tests); and
-* compile your library’s examples.
-
-#### Integration tests
-
-Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
-Cargo will compile each of these files as a separate crate. The crate can link
-to your library by using `extern crate <library-name>`, like any other code that
-depends on it.
-
-Cargo will not automatically compile files inside subdirectories of `tests`, but
-an integration test can import modules from these directories as usual. For
-example, if you want several integration tests to share some code, you can put
-the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
-the test files.
-
-### Configuring a target
-
-All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
-sections support similar configuration for specifying how a target should be
-built. The double-bracket sections like `[[bin]]` are array-of-table of
-[TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can
-write more than one `[[bin]]` section to make several executables in your crate.
-
-The example below uses `[lib]`, but it also applies to all other sections
-as well. All values listed are the defaults for that option unless otherwise
-specified.
-
-```toml
-[package]
-# ...
-
-[lib]
-# The name of a target is the name of the library that will be generated. This
-# is defaulted to the name of the package or project, with any dashes replaced
-# with underscores. (Rust `extern crate` declarations reference this name;
-# therefore the value must be a valid Rust identifier to be usable.)
-name = "foo"
-
-# This field points at where the crate is located, relative to the `Cargo.toml`.
-path = "src/lib.rs"
-
-# A flag for enabling unit tests for this target. This is used by `cargo test`.
-test = true
-
-# A flag for enabling documentation tests for this target. This is only relevant
-# for libraries, it has no effect on other sections. This is used by
-# `cargo test`.
-doctest = true
-
-# A flag for enabling benchmarks for this target. This is used by `cargo bench`.
-bench = true
-
-# A flag for enabling documentation of this target. This is used by `cargo doc`.
-doc = true
-
-# If the target is meant to be a compiler plugin, this field must be set to true
-# for Cargo to correctly compile it and make it available for all dependencies.
-plugin = false
-
-# If the target is meant to be a "macros 1.1" procedural macro, this field must
-# be set to true.
-proc-macro = false
-
-# If set to false, `cargo test` will omit the `--test` flag to rustc, which
-# stops it from generating a test harness. This is useful when the binary being
-# built manages the test runner itself.
-harness = true
-```
-
-#### The `required-features` field (optional)
-
-The `required-features` field specifies which features the target needs in order
-to be built. If any of the required features are not selected, the target will
-be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`,
-and `[[example]]` sections, it has no effect on `[lib]`.
-
-```toml
-[features]
-# ...
-postgres = []
-sqlite = []
-tools = []
-
-[[bin]]
-# ...
-required-features = ["postgres", "tools"]
-```
-
-#### Building dynamic or static libraries
-
-If your project produces a library, you can specify which kind of library to
-build by explicitly listing the library in your `Cargo.toml`:
-
-```toml
-# ...
-
-[lib]
-name = "..."
-crate-type = ["dylib"] # could be `staticlib` as well
-```
-
-The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and
-`proc-macro`. You should only use this option in a project. Cargo will always
-compile packages (dependencies) based on the requirements of the project that
-includes them.
-
-You can read more about the different crate types in the
-[Rust Reference Manual](https://doc.rust-lang.org/reference/linkage.html)
-
-### The `[patch]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[patch.crates-io]
-foo = { git = 'https://github.com/example/foo' }
-bar = { path = 'my/local/bar' }
-```
-
-The `[patch]` table is made of dependency-like sub-tables. Each key after
-`[patch]` is a URL of the source that's being patched, or `crates-io` if
-you're modifying the https://crates.io registry. In the example above
-`crates-io` could be replaced with a git URL such as
-`https://github.com/rust-lang-nursery/log`.
-
-Each entry in these tables is a normal dependency specification, the same as
-found in the `[dependencies]` section of the manifest. The dependencies listed
-in the `[patch]` section are resolved and used to patch the source at the
-URL specified. The above manifest snippet patches the `crates-io` source (e.g.
-crates.io itself) with the `foo` crate and `bar` crate.
-
-Sources can be patched with versions of crates that do not exist, and they can
-also be patched with versions of crates that already exist. If a source is
-patched with a crate version that already exists in the source, then the
-source's original crate is replaced.
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation and [RFC 1969] for the
-technical specification of this feature. (Note that the `[patch]` feature will
-first become available in Rust 1.21, set to be released on 2017-10-12.)
-
-[RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
-[replace]: reference/specifying-dependencies.html#overriding-dependencies
-
-### The `[replace]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[replace]
-"foo:0.1.0" = { git = 'https://github.com/example/foo' }
-"bar:1.0.2" = { path = 'my/local/bar' }
-```
-
-Each key in the `[replace]` table is a [package id
-specification](reference/pkgid-spec.html) which allows arbitrarily choosing a node in the
-dependency graph to override. The value of each key is the same as the
-`[dependencies]` syntax for specifying dependencies, except that you can't
-specify features. Note that when a crate is overridden the copy it's overridden
-with must have both the same name and version, but it can come from a different
-source (e.g. git or a local path).
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation.
-
-[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
-[spdx-license-list]: https://spdx.org/licenses/
-[spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4
+++ /dev/null
-## Package ID Specifications
-
-### Package ID specifications
-
-Subcommands of Cargo frequently need to refer to a particular package within a
-dependency graph for various operations like updating, cleaning, building, etc.
-To solve this problem, Cargo supports Package ID Specifications. A specification
-is a string which is used to uniquely refer to one package within a graph of
-packages.
-
-#### Specification grammar
-
-The formal grammar for a Package Id Specification is:
-
-```notrust
-pkgid := pkgname
- | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
-pkgname := name [ ":" semver ]
-
-proto := "http" | "git" | ...
-```
-
-Here, brackets indicate that the contents are optional.
-
-#### Example specifications
-
-These could all be references to a package `foo` version `1.2.3` from the
-registry at `crates.io`
-
-| pkgid | name | version | url |
-|:-----------------------------|:-----:|:-------:|:----------------------:|
-| `foo` | `foo` | `*` | `*` |
-| `foo:1.2.3` | `foo` | `1.2.3` | `*` |
-| `crates.io/foo` | `foo` | `*` | `*://crates.io/foo` |
-| `crates.io/foo#1.2.3` | `foo` | `1.2.3` | `*://crates.io/foo` |
-| `crates.io/bar#foo:1.2.3` | `foo` | `1.2.3` | `*://crates.io/bar` |
-| `http://crates.io/foo#1.2.3` | `foo` | `1.2.3` | `http://crates.io/foo` |
-
-#### Brevity of specifications
-
-The goal of this is to enable both succinct and exhaustive syntaxes for
-referring to packages in a dependency graph. Ambiguous references may refer to
-one or more packages. Most commands generate an error if more than one package
-could be referred to with the same specification.
+++ /dev/null
-## Publishing on crates.io
-
-Once you've got a library that you'd like to share with the world, it's time to
-publish it on [crates.io]! Publishing a crate is when a specific
-version is uploaded to be hosted on [crates.io].
-
-Take care when publishing a crate, because a publish is **permanent**. The
-version can never be overwritten, and the code cannot be deleted. There is no
-limit to the number of versions which can be published, however.
-
-### Before your first publish
-
-First thing’s first, you’ll need an account on [crates.io] to acquire
-an API token. To do so, [visit the home page][crates.io] and log in via a GitHub
-account (required for now). After this, visit your [Account
-Settings](https://crates.io/me) page and run the `cargo login` command
-specified.
-
-```shell
-$ cargo login abcdefghijklmnopqrstuvwxyz012345
-```
-
-This command will inform Cargo of your API token and store it locally in your
-`~/.cargo/credentials` (previously it was `~/.cargo/config`). Note that this
-token is a **secret** and should not be shared with anyone else. If it leaks for
-any reason, you should regenerate it immediately.
-
-### Before publishing a new crate
-
-Keep in mind that crate names on [crates.io] are allocated on a first-come-first-
-serve basis. Once a crate name is taken, it cannot be used for another crate.
-
-#### Packaging a crate
-
-The next step is to package up your crate into a format that can be uploaded to
-[crates.io]. For this we’ll use the `cargo package` subcommand. This will take
-our entire crate and package it all up into a `*.crate` file in the
-`target/package` directory.
-
-```shell
-$ cargo package
-```
-
-As an added bonus, the `*.crate` will be verified independently of the current
-source tree. After the `*.crate` is created, it’s unpacked into
-`target/package` and then built from scratch to ensure that all necessary files
-are there for the build to succeed. This behavior can be disabled with the
-`--no-verify` flag.
-
-Now’s a good time to take a look at the `*.crate` file to make sure you didn’t
-accidentally package up that 2GB video asset, or large data files used for code
-generation, integration tests, or benchmarking. There is currently a 10MB
-upload size limit on `*.crate` files. So, if the size of `tests` and `benches`
-directories and their dependencies are up to a couple of MBs, you can keep them
-in your package; otherwsie, better to exclude them.
-
-Cargo will automatically ignore files ignored by your version control system
-when packaging, but if you want to specify an extra set of files to ignore you
-can use the `exclude` key in the manifest:
-
-```toml
-[package]
-# ...
-exclude = [
- "public/assets/*",
- "videos/*",
-]
-```
-
-The syntax of each element in this array is what
-[rust-lang/glob](https://github.com/rust-lang/glob) accepts. If you’d rather
-roll with a whitelist instead of a blacklist, Cargo also supports an `include`
-key, which if set, overrides the `exclude` key:
-
-```toml
-[package]
-# ...
-include = [
- "**/*.rs",
- "Cargo.toml",
-]
-```
-
-### Uploading the crate
-
-Now that we’ve got a `*.crate` file ready to go, it can be uploaded to
-[crates.io] with the `cargo publish` command. And that’s it, you’ve now published
-your first crate!
-
-```shell
-$ cargo publish
-```
-
-If you’d like to skip the `cargo package` step, the `cargo publish` subcommand
-will automatically package up the local crate if a copy isn’t found already.
-
-Be sure to check out the [metadata you can
-specify](reference/manifest.html#package-metadata) to ensure your crate can be
-discovered more easily!
-
-### Publishing a new version of an existing crate
-
-In order to release a new version, change the `version` value specified in your
-`Cargo.toml` manifest. Keep in mind [the semver
-rules](reference/manifest.html#the-version-field). Then optionally run `cargo package` if
-you want to inspect the `*.crate` file for the new version before publishing,
-and run `cargo publish` to upload the new version.
-
-### Managing a crates.io-based crate
-
-Management of crates is primarily done through the command line `cargo` tool
-rather than the [crates.io] web interface. For this, there are a few subcommands
-to manage a crate.
-
-#### `cargo yank`
-
-Occasions may arise where you publish a version of a crate that actually ends up
-being broken for one reason or another (syntax error, forgot to include a file,
-etc.). For situations such as this, Cargo supports a “yank” of a version of a
-crate.
-
-```shell
-$ cargo yank --vers 1.0.1
-$ cargo yank --vers 1.0.1 --undo
-```
-
-A yank **does not** delete any code. This feature is not intended for deleting
-accidentally uploaded secrets, for example. If that happens, you must reset
-those secrets immediately.
-
-The semantics of a yanked version are that no new dependencies can be created
-against that version, but all existing dependencies continue to work. One of the
-major goals of [crates.io] is to act as a permanent archive of crates that does
-not change over time, and allowing deletion of a version would go against this
-goal. Essentially a yank means that all projects with a `Cargo.lock` will not
-break, while any future `Cargo.lock` files generated will not list the yanked
-version.
-
-#### `cargo owner`
-
-A crate is often developed by more than one person, or the primary maintainer
-may change over time! The owner of a crate is the only person allowed to publish
-new versions of the crate, but an owner may designate additional owners.
-
-```shell
-$ cargo owner --add my-buddy
-$ cargo owner --remove my-buddy
-$ cargo owner --add github:rust-lang:owners
-$ cargo owner --remove github:rust-lang:owners
-```
-
-The owner IDs given to these commands must be GitHub user names or GitHub teams.
-
-If a user name is given to `--add`, that user becomes a “named” owner, with
-full rights to the crate. In addition to being able to publish or yank versions
-of the crate, they have the ability to add or remove owners, *including* the
-owner that made *them* an owner. Needless to say, you shouldn’t make people you
-don’t fully trust into a named owner. In order to become a named owner, a user
-must have logged into [crates.io] previously.
-
-If a team name is given to `--add`, that team becomes a “team” owner, with
-restricted right to the crate. While they have permission to publish or yank
-versions of the crate, they *do not* have the ability to add or remove owners.
-In addition to being more convenient for managing groups of owners, teams are
-just a bit more secure against owners becoming malicious.
-
-The syntax for teams is currently `github:org:team` (see examples above).
-In order to add a team as an owner one must be a member of that team. No
-such restriction applies to removing a team as an owner.
-
-### GitHub permissions
-
-Team membership is not something GitHub provides simple public access to, and it
-is likely for you to encounter the following message when working with them:
-
-> It looks like you don’t have permission to query a necessary property from
-GitHub to complete this request. You may need to re-authenticate on [crates.io]
-to grant permission to read GitHub org memberships. Just go to
-https://crates.io/login
-
-This is basically a catch-all for “you tried to query a team, and one of the
-five levels of membership access control denied this”. That is not an
-exaggeration. GitHub’s support for team access control is Enterprise Grade.
-
-The most likely cause of this is simply that you last logged in before this
-feature was added. We originally requested *no* permissions from GitHub when
-authenticating users, because we didn’t actually ever use the user’s token for
-anything other than logging them in. However to query team membership on your
-behalf, we now require
-[the `read:org` scope](https://developer.github.com/v3/oauth/#scopes).
-
-You are free to deny us this scope, and everything that worked before teams
-were introduced will keep working. However you will never be able to add a team
-as an owner, or publish a crate as a team owner. If you ever attempt to do this,
-you will get the error above. You may also see this error if you ever try to
-publish a crate that you don’t own at all, but otherwise happens to have a team.
-
-If you ever change your mind, or just aren’t sure if [crates.io] has sufficient
-permission, you can always go to https://crates.io/login, which will prompt you
-for permission if [crates.io] doesn’t have all the scopes it would like to.
-
-An additional barrier to querying GitHub is that the organization may be
-actively denying third party access. To check this, you can go to:
-
- https://github.com/organizations/:org/settings/oauth_application_policy
-
-where `:org` is the name of the organization (e.g. rust-lang). You may see
-something like:
-
-
-
-Where you may choose to explicitly remove [crates.io] from your organization’s
-blacklist, or simply press the “Remove Restrictions” button to allow all third
-party applications to access this data.
-
-Alternatively, when [crates.io] requested the `read:org` scope, you could have
-explicitly whitelisted [crates.io] querying the org in question by pressing
-the “Grant Access” button next to its name:
-
-
-
-[crates.io]: https://crates.io/
+++ /dev/null
-## Source Replacement
-
-Cargo supports the ability to **replace one source with another** to express
-strategies along the lines of mirrors or vendoring dependencies. Configuration
-is currently done through the [`.cargo/config` configuration][config] mechanism,
-like so:
-
-[config]: reference/config.html
-
-```toml
-# The `source` table is where all keys related to source-replacement
-# are stored.
-[source]
-
-# Under the `source` table are a number of other tables whose keys are a
-# name for the relevant source. For example this section defines a new
-# source, called `my-awesome-source`, which comes from a directory
-# located at `vendor` relative to the directory containing this `.cargo/config`
-# file
-[source.my-awesome-source]
-directory = "vendor"
-
-# The crates.io default source for crates is available under the name
-# "crates-io", and here we use the `replace-with` key to indicate that it's
-# replaced with our source above.
-[source.crates-io]
-replace-with = "my-awesome-source"
-```
-
-With this configuration Cargo attempts to look up all crates in the directory
-"vendor" rather than querying the online registry at crates.io. Using source
-replacement Cargo can express:
-
-* Vendoring - custom sources can be defined which represent crates on the local
- filesystem. These sources are subsets of the source that they're replacing and
- can be checked into projects if necessary.
-
-* Mirroring - sources can be replaced with an equivalent version which acts as a
- cache for crates.io itself.
-
-Cargo has a core assumption about source replacement that the source code is
-exactly the same from both sources. In our above example Cargo assumes that all
-of the crates coming from `my-awesome-source` are the exact same as the copies
-from `crates-io`. Note that this also means that `my-awesome-source` is not
-allowed to have crates which are not present in the `crates-io` source.
-
-As a consequence, source replacement is not appropriate for situations such as
-patching a dependency or a private registry. Cargo supports patching
-dependencies through the usage of [the `[replace]` key][replace-section], and
-private registry support is planned for a future version of Cargo.
-
-[replace-section]: reference/manifest.html#the-replace-section
-
-### Configuration
-
-Configuration of replacement sources is done through [`.cargo/config`][config]
-and the full set of available keys are:
-
-```toml
-# Each source has its own table where the key is the name of the source
-[source.the-source-name]
-
-# Indicate that `the-source-name` will be replaced with `another-source`,
-# defined elsewhere
-replace-with = "another-source"
-
-# Available kinds of sources that can be specified (described below)
-registry = "https://example.com/path/to/index"
-local-registry = "path/to/registry"
-directory = "path/to/vendor"
-```
-
-The `crates-io` represents the crates.io online registry (default source of
-crates) and can be replaced with:
-
-```toml
-[source.crates-io]
-replace-with = 'another-source'
-```
-
-### Registry Sources
-
-A "registry source" is one that is the same as crates.io itself. That is, it has
-an index served in a git repository which matches the format of the
-[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
-then has configuration indicating where to download crates from.
-
-Currently there is not an already-available project for setting up a mirror of
-crates.io. Stay tuned though!
-
-### Local Registry Sources
-
-A "local registry source" is intended to be a subset of another registry
-source, but available on the local filesystem (aka vendoring). Local registries
-are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are
-made up of a set of `*.crate` files and an index like the normal registry is.
-
-The primary way to manage and crate local registry sources is through the
-[`cargo-local-registry`][cargo-local-registry] subcommand, available on
-crates.io and can be installed with `cargo install cargo-local-registry`.
-
-[cargo-local-registry]: https://crates.io/crates/cargo-local-registry
-
-Local registries are contained within one directory and contain a number of
-`*.crate` files downloaded from crates.io as well as an `index` directory with
-the same format as the crates.io-index project (populated with just entries for
-the crates that are present).
-
-### Directory Sources
-
-A "directory source" is similar to a local registry source where it contains a
-number of crates available on the local filesystem, suitable for vendoring
-dependencies. Also like local registries, directory sources can primarily be
-managed by an external subcommand, [`cargo-vendor`][cargo-vendor], which can be
-installed with `cargo install cargo-vendor`.
-
-[cargo-vendor]: https://crates.io/crates/cargo-vendor
-
-Directory sources are distinct from local registries though in that they contain
-the unpacked version of `*.crate` files, making it more suitable in some
-situations to check everything into source control. A directory source is just a
-directory containing a number of other directories which contain the source code
-for crates (the unpacked version of `*.crate` files). Currently no restriction
-is placed on the name of each directory.
-
-Each crate in a directory source also has an associated metadata file indicating
-the checksum of each file in the crate to protect against accidental
-modifications.
+++ /dev/null
-## Specifying Dependencies
-
-Your crates can depend on other libraries from [crates.io], `git` repositories, or
-subdirectories on your local file system. You can also temporarily override the
-location of a dependency— for example, to be able to test out a bug fix in the
-dependency that you are working on locally. You can have different
-dependencies for different platforms, and dependencies that are only used during
-development. Let's take a look at how to do each of these.
-
-### Specifying dependencies from crates.io
-
-Cargo is configured to look for dependencies on [crates.io] by default. Only
-the name and a version string are required in this case. In [the cargo
-guide](guide/index.html), we specified a dependency on the `time` crate:
-
-```toml
-[dependencies]
-time = "0.1.12"
-```
-
-The string `"0.1.12"` is a [semver] version requirement. Since this
-string does not have any operators in it, it is interpreted the same way as
-if we had specified `"^0.1.12"`, which is called a caret requirement.
-
-[semver]: https://github.com/steveklabnik/semver#requirements
-
-### Caret requirements
-
-**Caret requirements** allow SemVer compatible updates to a specified version.
-An update is allowed if the new version number does not modify the left-most
-non-zero digit in the major, minor, patch grouping. In this case, if we ran
-`cargo update -p time`, cargo would update us to version `0.1.13` if it was
-available, but would not update us to `0.2.0`. If instead we had specified the
-version string as `^1.0`, cargo would update to `1.1` but not `2.0`. The version
-`0.0.x` is not considered compatible with any other version.
-
-Here are some more examples of caret requirements and the versions that would
-be allowed with them:
-
-```notrust
-^1.2.3 := >=1.2.3 <2.0.0
-^1.2 := >=1.2.0 <2.0.0
-^1 := >=1.0.0 <2.0.0
-^0.2.3 := >=0.2.3 <0.3.0
-^0.0.3 := >=0.0.3 <0.0.4
-^0.0 := >=0.0.0 <0.1.0
-^0 := >=0.0.0 <1.0.0
-```
-
-This compatibility convention is different from SemVer in the way it treats
-versions before 1.0.0. While SemVer says there is no compatibility before
-1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z`
-and `x > 0`.
-
-### Tilde requirements
-
-**Tilde requirements** specify a minimal version with some ability to update.
-If you specify a major, minor, and patch version or only a major and minor
-version, only patch-level changes are allowed. If you only specify a major
-version, then minor- and patch-level changes are allowed.
-
-`~1.2.3` is an example of a tilde requirement.
-
-```notrust
-~1.2.3 := >=1.2.3 <1.3.0
-~1.2 := >=1.2.0 <1.3.0
-~1 := >=1.0.0 <2.0.0
-```
-
-### Wildcard requirements
-
-**Wildcard requirements** allow for any version where the wildcard is
-positioned.
-
-`*`, `1.*` and `1.2.*` are examples of wildcard requirements.
-
-```notrust
-* := >=0.0.0
-1.* := >=1.0.0 <2.0.0
-1.2.* := >=1.2.0 <1.3.0
-```
-
-### Inequality requirements
-
-**Inequality requirements** allow manually specifying a version range or an
-exact version to depend on.
-
-Here are some examples of inequality requirements:
-
-```notrust
->= 1.2.0
-> 1
-< 2
-= 1.2.3
-```
-
-### Multiple requirements
-
-Multiple version requirements can also be separated with a comma, e.g. `>= 1.2,
-< 1.5`.
-
-### Specifying dependencies from `git` repositories
-
-To depend on a library located in a `git` repository, the minimum information
-you need to specify is the location of the repository with the `git` key:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand" }
-```
-
-Cargo will fetch the `git` repository at this location then look for a
-`Cargo.toml` for the requested crate anywhere inside the `git` repository
-(not necessarily at the root).
-
-Since we haven’t specified any other information, Cargo assumes that
-we intend to use the latest commit on the `master` branch to build our project.
-You can combine the `git` key with the `rev`, `tag`, or `branch` keys to
-specify something else. Here's an example of specifying that you want to use
-the latest commit on a branch named `next`:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }
-```
-
-### Specifying path dependencies
-
-Over time, our `hello_world` project from [the guide](guide/index.html) has
-grown significantly in size! It’s gotten to the point that we probably want to
-split out a separate crate for others to use. To do this Cargo supports **path
-dependencies** which are typically sub-crates that live within one repository.
-Let’s start off by making a new crate inside of our `hello_world` project:
-
-```shell
-# inside of hello_world/
-$ cargo new hello_utils
-```
-
-This will create a new folder `hello_utils` inside of which a `Cargo.toml` and
-`src` folder are ready to be configured. In order to tell Cargo about this, open
-up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies:
-
-```toml
-[dependencies]
-hello_utils = { path = "hello_utils" }
-```
-
-This tells Cargo that we depend on a crate called `hello_utils` which is found
-in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in).
-
-And that’s it! The next `cargo build` will automatically build `hello_utils` and
-all of its own dependencies, and others can also start using the crate as well.
-However, crates that use dependencies specified with only a path are not
-permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we
-would need to publish a version of `hello_utils` to [crates.io](https://crates.io)
-and specify its version in the dependencies line as well:
-
-```toml
-[dependencies]
-hello_utils = { path = "hello_utils", version = "0.1.0" }
-```
-
-### Overriding dependencies
-
-There are a number of methods in Cargo to support overriding dependencies and
-otherwise controlling the dependency graph. These options are typically, though,
-only available at the workspace level and aren't propagated through
-dependencies. In other words, "applications" have the ability to override
-dependencies but "libraries" do not.
-
-The desire to override a dependency or otherwise alter some dependencies can
-arise through a number of scenarios. Most of them, however, boil down to the
-ability to work with a crate before it's been published to crates.io. For
-example:
-
-* A crate you're working on is also used in a much larger application you're
- working on, and you'd like to test a bug fix to the library inside of the
- larger application.
-* An upstream crate you don't work on has a new feature or a bug fix on the
- master branch of its git repository which you'd like to test out.
-* You're about to publish a new major version of your crate, but you'd like to
- do integration testing across an entire project to ensure the new major
- version works.
-* You've submitted a fix to an upstream crate for a bug you found, but you'd
- like to immediately have your application start depending on the fixed version
- of the crate to avoid blocking on the bug fix getting merged.
-
-These scenarios are currently all solved with the [`[patch]` manifest
-section][patch-section]. Note that the `[patch]` feature is not yet currently
-stable and will be released on 2017-08-31. Historically some of these scenarios
-have been solved with [the `[replace]` section][replace-section], but we'll
-document the `[patch]` section here.
-
-[patch-section]: reference/manifest.html#the-patch-section
-[replace-section]: reference/manifest.html#the-replace-section
-
-### Testing a bugfix
-
-Let's say you're working with the [`uuid`] crate but while you're working on it
-you discover a bug. You are, however, quite enterprising so you decide to also
-try out to fix the bug! Originally your manifest will look like:
-
-[`uuid`](https://crates.io/crates/uuid)
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0"
-```
-
-First thing we'll do is to clone the [`uuid` repository][uuid-repository]
-locally via:
-
-```shell
-$ git clone https://github.com/rust-lang-nursery/uuid
-```
-
-Next we'll edit the manifest of `my-library` to contain:
-
-```toml
-[patch.crates-io]
-uuid = { path = "../path/to/uuid" }
-```
-
-Here we declare that we're *patching* the source `crates-io` with a new
-dependency. This will effectively add the local checked out version of `uuid` to
-the crates.io registry for our local project.
-
-Next up we need to ensure that our lock file is updated to use this new version
-of `uuid` so our project uses the locally checked out copy instead of one from
-crates.io. The way `[patch]` works is that it'll load the dependency at
-`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid`
-it'll *also* return the local version.
-
-This means that the version number of the local checkout is significant and will
-affect whether the patch is used. Our manifest declared `uuid = "1.0"` which
-means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution
-algorithm also means that we'll resolve to the maximum version within that
-range. Typically this doesn't matter as the version of the git repository will
-already be greater or match the maximum version published on crates.io, but it's
-important to keep this in mind!
-
-In any case, typically all you need to do now is:
-
-```shell
-$ cargo build
- Compiling uuid v1.0.0 (file://.../uuid)
- Compiling my-library v0.1.0 (file://.../my-library)
- Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
-```
-
-And that's it! You're now building with the local version of `uuid` (note the
-`file://` in the build output). If you don't see the `file://` version getting
-built then you may need to run `cargo update -p uuid --precise $version` where
-`$version` is the version of the locally checked out copy of `uuid`.
-
-Once you've fixed the bug you originally found the next thing you'll want to do
-is to likely submit that as a pull request to the `uuid` crate itself. Once
-you've done this then you can also update the `[patch]` section. The listing
-inside of `[patch]` is just like the `[dependencies]` section, so once your pull
-request is merged you could change your `path` dependency to:
-
-```toml
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-[uuid-repository]: https://github.com/rust-lang-nursery/uuid
-
-### Working with an unpublished minor version
-
-Let's now shift gears a bit from bug fixes to adding features. While working on
-`my-library` you discover that a whole new feature is needed in the `uuid`
-crate. You've implemented this feature, tested it locally above with `[patch]`,
-and submitted a pull request. Let's go over how you continue to use and test it
-before it's actually published.
-
-Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but
-since then the master branch of the git repository has updated to `1.0.1`. This
-branch includes your new feature you submitted previously. To use this
-repository we'll edit our `Cargo.toml` to look like
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0.1"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Note that our local dependency on `uuid` has been updated to `1.0.1` as it's
-what we'll actually require once the crate is published. This version doesn't
-exist on crates.io, though, so we provide it with the `[patch]` section of the
-manifest.
-
-Now when our library is built it'll fetch `uuid` from the git repository and
-resolve to 1.0.1 inside the repository instead of trying to download a version
-from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can
-be deleted.
-
-It's also worth nothing that `[patch]` applies *transitively*. Let's say you use
-`my-library` in a larger project, such as:
-
-```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Remember that `[patch]` is only applicable at the *top level* so we consumers of
-`my-library` have to repeat the `[patch]` section if necessary. Here, though,
-the new `uuid` crate applies to *both* our dependency on `uuid` and the
-`my-library -> uuid` dependency. The `uuid` crate will be resolved to one
-version for this entire crate graph, 1.0.1, and it'll be pulled from the git
-repository.
-
-### Prepublishing a breaking change
-
-As a final scenario, let's take a look at working with a new major version of a
-crate, typically accompanied with breaking changes. Sticking with our previous
-crates, this means that we're going to be creating version 2.0.0 of the `uuid`
-crate. After we've submitted all changes upstream we can update our manifest for
-`my-library` to look like:
-
-```toml
-[dependencies]
-uuid = "2.0"
-
-[patch.crates-io]
-uuid = { git = "https://github.com/rust-lang-nursery/uuid", branch = "2.0.0" }
-```
-
-And that's it! Like with the previous example the 2.0.0 version doesn't actually
-exist on crates.io but we can still put it in through a git dependency through
-the usage of the `[patch]` section. As a thought exercise let's take another
-look at the `my-binary` manifest from above again as well:
-
-```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid', version = '2.0.0' }
-```
-
-Note that this will actually resolve to two versions of the `uuid` crate. The
-`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but
-the `my-library` crate will use the 2.0.0 version of `uuid`. This will allow you
-to gradually roll out breaking changes to a crate through a dependency graph
-without being force to update everything all at once.
-
-### Overriding with local dependencies
-
-Sometimes you're only temporarily working on a crate and you don't want to have
-to modify `Cargo.toml` like with the `[patch]` section above. For this use
-case Cargo offers a much more limited version of overrides called **path
-overrides**.
-
-Path overrides are specified through `.cargo/config` instead of `Cargo.toml`,
-and you can find [more documentation about this configuration][config-docs].
-Inside of `.cargo/config` you'll specify a key called `paths`:
-
-[config-docs]: reference/config.html
-
-```toml
-paths = ["/path/to/uuid"]
-```
-
-This array should be filled with directories that contain a `Cargo.toml`. In
-this instance, we’re just adding `uuid`, so it will be the only one that’s
-overridden. This path can be either absolute or relative to the directory that
-contains the `.cargo` folder.
-
-Path overrides are more restricted than the `[patch]` section, however, in
-that they cannot change the structure of the dependency graph. When a
-path replacement is used then the previous set of dependencies
-must all match exactly to the new `Cargo.toml` specification. For example this
-means that path overrides cannot be used to test out adding a dependency to a
-crate, instead `[patch]` must be used in that situation. As a result usage of a
-path override is typically isolated to quick bug fixes rather than larger
-changes.
-
-Note: using a local configuration to override paths will only work for crates
-that have been published to [crates.io]. You cannot use this feature to tell
-Cargo how to find local unpublished crates.
-
-### Platform specific dependencies
-
-
-Platform-specific dependencies take the same format, but are listed under a
-`target` section. Normally Rust-like `#[cfg]` syntax will be used to define
-these sections:
-
-```toml
-[target.'cfg(windows)'.dependencies]
-winhttp = "0.4.0"
-
-[target.'cfg(unix)'.dependencies]
-openssl = "1.0.1"
-
-[target.'cfg(target_arch = "x86")'.dependencies]
-native = { path = "native/i686" }
-
-[target.'cfg(target_arch = "x86_64")'.dependencies]
-native = { path = "native/x86_64" }
-```
-
-Like with Rust, the syntax here supports the `not`, `any`, and `all` operators
-to combine various cfg name/value pairs. Note that the `cfg` syntax has only
-been available since Cargo 0.9.0 (Rust 1.8.0).
-
-In addition to `#[cfg]` syntax, Cargo also supports listing out the full target
-the dependencies would apply to:
-
-```toml
-[target.x86_64-pc-windows-gnu.dependencies]
-winhttp = "0.4.0"
-
-[target.i686-unknown-linux-gnu.dependencies]
-openssl = "1.0.1"
-```
-
-If you’re using a custom target specification, quote the full path and file
-name:
-
-```toml
-[target."x86_64/windows.json".dependencies]
-winhttp = "0.4.0"
-
-[target."i686/linux.json".dependencies]
-openssl = "1.0.1"
-native = { path = "native/i686" }
-
-[target."x86_64/linux.json".dependencies]
-openssl = "1.0.1"
-native = { path = "native/x86_64" }
-```
-
-### Development dependencies
-
-You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format
-is equivalent to `[dependencies]`:
-
-```toml
-[dev-dependencies]
-tempdir = "0.3"
-```
-
-Dev-dependencies are not used when compiling
-a package for building, but are used for compiling tests, examples, and
-benchmarks.
-
-These dependencies are *not* propagated to other packages which depend on this
-package.
-
-You can also have target-specific development dependencies by using
-`dev-dependencies` in the target section header instead of `dependencies`. For
-example:
-
-```toml
-[target.'cfg(unix)'.dev-dependencies]
-mio = "0.0.1"
-```
-
-[crates.io]: https://crates.io/
-
-### Build dependencies
-
-You can depend on other Cargo-based crates for use in your build scripts.
-Dependencies are declared through the `build-dependencies` section of the
-manifest:
-
-```toml
-[build-dependencies]
-gcc = "0.3"
-```
-
-The build script **does not** have access to the dependencies listed
-in the `dependencies` or `dev-dependencies` section. Build
-dependencies will likewise not be available to the package itself
-unless listed under the `dependencies` section as well. A package
-itself and its build script are built separately, so their
-dependencies need not coincide. Cargo is kept simpler and cleaner by
-using independent dependencies for independent purposes.
-
-### Choosing features
-
-If a package you depend on offers conditional features, you can
-specify which to use:
-
-```toml
-[dependencies.awesome]
-version = "1.3.5"
-default-features = false # do not include the default features, and optionally
- # cherry-pick individual features
-features = ["secure-password", "civet"]
-```
-
-More information about features can be found in the
-[manifest documentation](reference/manifest.html#the-features-section).
+++ /dev/null
-% Build Script Support
-
-Some packages need to compile third-party non-Rust code, for example C
-libraries. Other packages need to link to C libraries which can either be
-located on the system or possibly need to be built from source. Others still
-need facilities for functionality such as code generation before building (think
-parser generators).
-
-Cargo does not aim to replace other tools that are well-optimized for
-these tasks, but it does integrate with them with the `build` configuration
-option.
-
-```toml
-[package]
-# ...
-build = "build.rs"
-```
-
-The Rust file designated by the `build` command (relative to the package root)
-will be compiled and invoked before anything else is compiled in the package,
-allowing your Rust code to depend on the built or generated artifacts. Note that
-if you do not specify a value for `build` but your package root does contain a
-`"build.rs"` file, Cargo will compile and invoke this file for you.
-
-Some example use cases of the build command are:
-
-* Building a bundled C library.
-* Finding a C library on the host system.
-* Generating a Rust module from a specification.
-* Performing any platform-specific configuration needed for the crate.
-
-Each of these use cases will be detailed in full below to give examples of how
-the build command works.
-
-## Inputs to the Build Script
-
-When the build script is run, there are a number of inputs to the build script,
-all passed in the form of [environment variables][env].
-
-In addition to environment variables, the build script’s current directory is
-the source directory of the build script’s package.
-
-[env]: environment-variables.html
-
-## Outputs of the Build Script
-
-All the lines printed to stdout by a build script are written to a file like
-`target/debug/build/<pkg>/output` (the precise location may depend on your
-configuration). If you would like to see such output directly in your terminal,
-invoke cargo as 'very verbose' with the `-vv` flag. Note that if neither the
-build script nor project source files are modified, subsequent calls to
-cargo with the `-vv` will **not** print output to the terminal because a
-new build is not executed. Run `cargo clean` before each cargo invokation
-if you want to ensure that output is always displayed on your terminal.
-Any line that starts with `cargo:` is interpreted directly by Cargo.
-This line must be of the form `cargo:key=value`, like the examples below:
-
-```notrust
-# specially recognized by Cargo
-cargo:rustc-link-lib=static=foo
-cargo:rustc-link-search=native=/path/to/foo
-cargo:rustc-cfg=foo
-cargo:rustc-env=FOO=bar
-# arbitrary user-defined metadata
-cargo:root=/path/to/foo
-cargo:libdir=/path/to/foo/lib
-cargo:include=/path/to/foo/include
-```
-
-On the other hand, lines printed to stderr are written to a file like
-`target/debug/build/<pkg>/stderr` but are not interpreted by cargo.
-
-There are a few special keys that Cargo recognizes, some affecting how the
-crate is built:
-
-* `rustc-link-lib=[KIND=]NAME` indicates that the specified value is a library
- name and should be passed to the compiler as a `-l` flag. The optional `KIND`
- can be one of `static`, `dylib` (the default), or `framework`, see
- `rustc --help` for more details.
-* `rustc-link-search=[KIND=]PATH` indicates the specified value is a library
- search path and should be passed to the compiler as a `-L` flag. The optional
- `KIND` can be one of `dependency`, `crate`, `native`, `framework` or `all`
- (the default), see `rustc --help` for more details.
-* `rustc-flags=FLAGS` is a set of flags passed to the compiler, only `-l` and
- `-L` flags are supported.
-* `rustc-cfg=FEATURE` indicates that the specified feature will be passed as a
- `--cfg` flag to the compiler. This is often useful for performing compile-time
- detection of various features.
-* `rustc-env=VAR=VALUE` indicates that the specified environment variable
- will be added to the environment which the compiler is run within.
- The value can be then retrieved by the `env!` macro in the compiled crate.
- This is useful for embedding additional metadata in crate's code,
- such as the hash of Git HEAD or the unique identifier of a continuous
- integration server.
-* `rerun-if-changed=PATH` is a path to a file or directory which indicates that
- the build script should be re-run if it changes (detected by a more-recent
- last-modified timestamp on the file). Normally build scripts are re-run if
- any file inside the crate root changes, but this can be used to scope changes
- to just a small set of files. (If this path points to a directory the entire
- directory will not be traversed for changes -- only changes to the timestamp
- of the directory itself (which corresponds to some types of changes within the
- directory, depending on platform) will trigger a rebuild. To request a re-run
- on any changes within an entire directory, print a line for the directory and
- another line for everything inside it, recursively.)
- Note that if the build script itself (or one of its dependencies) changes,
- then it's rebuilt and rerun unconditionally, so
- `cargo:rerun-if-changed=build.rs` is almost always redundant (unless you
- want to ignore changes in all other files except for `build.rs`).
-* `rerun-if-env-changed=VAR` is the name of an environment variable which
- indicates that if the environment variable's value changes the build script
- should be rerun. This basically behaves the same as `rerun-if-changed` except
- that it works with environment variables instead. Note that the environment
- variables here are intended for global environment variables like `CC` and
- such, it's not necessary to use this for env vars like `TARGET` that Cargo
- sets. Also note that if `rerun-if-env-changed` is printed out then Cargo will
- *only* rerun the build script if those environment variables change or if
- files printed out by `rerun-if-changed` change.
-
-* `warning=MESSAGE` is a message that will be printed to the main console after
- a build script has finished running. Warnings are only shown for path
- dependencies (that is, those you're working on locally), so for example
- warnings printed out in crates.io crates are not emitted by default.
-
-Any other element is a user-defined metadata that will be passed to
-dependents. More information about this can be found in the [`links`][links]
-section.
-
-[links]: #the-links-manifest-key
-
-## Build Dependencies
-
-Build scripts are also allowed to have dependencies on other Cargo-based crates.
-Dependencies are declared through the `build-dependencies` section of the
-manifest.
-
-```toml
-[build-dependencies]
-foo = { git = "https://github.com/your-packages/foo" }
-```
-
-The build script **does not** have access to the dependencies listed in the
-`dependencies` or `dev-dependencies` section (they’re not built yet!). All build
-dependencies will also not be available to the package itself unless explicitly
-stated as so.
-
-## The `links` Manifest Key
-
-In addition to the manifest key `build`, Cargo also supports a `links` manifest
-key to declare the name of a native library that is being linked to:
-
-```toml
-[package]
-# ...
-links = "foo"
-build = "build.rs"
-```
-
-This manifest states that the package links to the `libfoo` native library, and
-it also has a build script for locating and/or building the library. Cargo
-requires that a `build` command is specified if a `links` entry is also
-specified.
-
-The purpose of this manifest key is to give Cargo an understanding about the set
-of native dependencies that a package has, as well as providing a principled
-system of passing metadata between package build scripts.
-
-Primarily, Cargo requires that there is at most one package per `links` value.
-In other words, it’s forbidden to have two packages link to the same native
-library. Note, however, that there are [conventions in place][star-sys] to
-alleviate this.
-
-[star-sys]: #-sys-packages
-
-As mentioned above in the output format, each build script can generate an
-arbitrary set of metadata in the form of key-value pairs. This metadata is
-passed to the build scripts of **dependent** packages. For example, if `libbar`
-depends on `libfoo`, then if `libfoo` generates `key=value` as part of its
-metadata, then the build script of `libbar` will have the environment variables
-`DEP_FOO_KEY=value`.
-
-Note that metadata is only passed to immediate dependents, not transitive
-dependents. The motivation for this metadata passing is outlined in the linking
-to system libraries case study below.
-
-## Overriding Build Scripts
-
-If a manifest contains a `links` key, then Cargo supports overriding the build
-script specified with a custom library. The purpose of this functionality is to
-prevent running the build script in question altogether and instead supply the
-metadata ahead of time.
-
-To override a build script, place the following configuration in any acceptable
-Cargo [configuration location](config.html).
-
-```toml
-[target.x86_64-unknown-linux-gnu.foo]
-rustc-link-search = ["/path/to/foo"]
-rustc-link-lib = ["foo"]
-root = "/path/to/foo"
-key = "value"
-```
-
-This section states that for the target `x86_64-unknown-linux-gnu` the library
-named `foo` has the metadata specified. This metadata is the same as the
-metadata generated as if the build script had run, providing a number of
-key/value pairs where the `rustc-flags`, `rustc-link-search`, and
-`rustc-link-lib` keys are slightly special.
-
-With this configuration, if a package declares that it links to `foo` then the
-build script will **not** be compiled or run, and the metadata specified will
-instead be used.
-
-# Case study: Code generation
-
-Some Cargo packages need to have code generated just before they are compiled
-for various reasons. Here we’ll walk through a simple example which generates a
-library call as part of the build script.
-
-First, let’s take a look at the directory structure of this package:
-
-```notrust
-.
-├── Cargo.toml
-├── build.rs
-└── src
- └── main.rs
-
-1 directory, 3 files
-```
-
-Here we can see that we have a `build.rs` build script and our binary in
-`main.rs`. Next, let’s take a look at the manifest:
-
-```toml
-# Cargo.toml
-
-[package]
-name = "hello-from-generated-code"
-version = "0.1.0"
-authors = ["you@example.com"]
-build = "build.rs"
-```
-
-Here we can see we’ve got a build script specified which we’ll use to generate
-some code. Let’s see what’s inside the build script:
-
-```rust,no_run
-// build.rs
-
-use std::env;
-use std::fs::File;
-use std::io::Write;
-use std::path::Path;
-
-fn main() {
- let out_dir = env::var("OUT_DIR").unwrap();
- let dest_path = Path::new(&out_dir).join("hello.rs");
- let mut f = File::create(&dest_path).unwrap();
-
- f.write_all(b"
- pub fn message() -> &'static str {
- \"Hello, World!\"
- }
- ").unwrap();
-}
-```
-
-There’s a couple of points of note here:
-
-* The script uses the `OUT_DIR` environment variable to discover where the
- output files should be located. It can use the process’ current working
- directory to find where the input files should be located, but in this case we
- don’t have any input files.
-* This script is relatively simple as it just writes out a small generated file.
- One could imagine that other more fanciful operations could take place such as
- generating a Rust module from a C header file or another language definition,
- for example.
-
-Next, let’s peek at the library itself:
-
-```rust,ignore
-// src/main.rs
-
-include!(concat!(env!("OUT_DIR"), "/hello.rs"));
-
-fn main() {
- println!("{}", message());
-}
-```
-
-This is where the real magic happens. The library is using the rustc-defined
-`include!` macro in combination with the `concat!` and `env!` macros to include
-the generated file (`hello.rs`) into the crate’s compilation.
-
-Using the structure shown here, crates can include any number of generated files
-from the build script itself.
-
-# Case study: Building some native code
-
-Sometimes it’s necessary to build some native C or C++ code as part of a
-package. This is another excellent use case of leveraging the build script to
-build a native library before the Rust crate itself. As an example, we’ll create
-a Rust library which calls into C to print “Hello, World!”.
-
-Like above, let’s first take a look at the project layout:
-
-```notrust
-.
-├── Cargo.toml
-├── build.rs
-└── src
- ├── hello.c
- └── main.rs
-
-1 directory, 4 files
-```
-
-Pretty similar to before! Next, the manifest:
-
-```toml
-# Cargo.toml
-
-[package]
-name = "hello-world-from-c"
-version = "0.1.0"
-authors = ["you@example.com"]
-build = "build.rs"
-```
-
-For now we’re not going to use any build dependencies, so let’s take a look at
-the build script now:
-
-```rust,no_run
-// build.rs
-
-use std::process::Command;
-use std::env;
-use std::path::Path;
-
-fn main() {
- let out_dir = env::var("OUT_DIR").unwrap();
-
- // note that there are a number of downsides to this approach, the comments
- // below detail how to improve the portability of these commands.
- Command::new("gcc").args(&["src/hello.c", "-c", "-fPIC", "-o"])
- .arg(&format!("{}/hello.o", out_dir))
- .status().unwrap();
- Command::new("ar").args(&["crus", "libhello.a", "hello.o"])
- .current_dir(&Path::new(&out_dir))
- .status().unwrap();
-
- println!("cargo:rustc-link-search=native={}", out_dir);
- println!("cargo:rustc-link-lib=static=hello");
-}
-```
-
-This build script starts out by compiling our C file into an object file (by
-invoking `gcc`) and then converting this object file into a static library (by
-invoking `ar`). The final step is feedback to Cargo itself to say that our
-output was in `out_dir` and the compiler should link the crate to `libhello.a`
-statically via the `-l static=hello` flag.
-
-Note that there are a number of drawbacks to this hardcoded approach:
-
-* The `gcc` command itself is not portable across platforms. For example it’s
- unlikely that Windows platforms have `gcc`, and not even all Unix platforms
- may have `gcc`. The `ar` command is also in a similar situation.
-* These commands do not take cross-compilation into account. If we’re cross
- compiling for a platform such as Android it’s unlikely that `gcc` will produce
- an ARM executable.
-
-Not to fear, though, this is where a `build-dependencies` entry would help! The
-Cargo ecosystem has a number of packages to make this sort of task much easier,
-portable, and standardized. For example, the build script could be written as:
-
-```rust,ignore
-// build.rs
-
-// Bring in a dependency on an externally maintained `cc` package which manages
-// invoking the C compiler.
-extern crate cc;
-
-fn main() {
- cc::Build::new()
- .file("src/hello.c")
- .compile("hello");
-}
-```
-
-Add a build time dependency on the `cc` crate with the following addition to
-your `Cargo.toml`:
-
-```toml
-[build-dependencies]
-cc = "1.0"
-```
-
-The [`cc` crate](https://crates.io/crates/cc) abstracts a range of build
-script requirements for C code:
-
-* It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc`
- for Unix platforms, etc.).
-* It takes the `TARGET` variable into account by passing appropriate flags to
- the compiler being used.
-* Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all
- handled automatically.
-* The stdout output and `OUT_DIR` locations are also handled by the `cc`
- library.
-
-Here we can start to see some of the major benefits of farming as much
-functionality as possible out to common build dependencies rather than
-duplicating logic across all build scripts!
-
-Back to the case study though, let’s take a quick look at the contents of the
-`src` directory:
-
-```c
-// src/hello.c
-
-#include <stdio.h>
-
-void hello() {
- printf("Hello, World!\n");
-}
-```
-
-```rust,ignore
-// src/main.rs
-
-// Note the lack of the `#[link]` attribute. We’re delegating the responsibility
-// of selecting what to link to over to the build script rather than hardcoding
-// it in the source file.
-extern { fn hello(); }
-
-fn main() {
- unsafe { hello(); }
-}
-```
-
-And there we go! This should complete our example of building some C code from a
-Cargo package using the build script itself. This also shows why using a build
-dependency can be crucial in many situations and even much more concise!
-
-We’ve also seen a brief example of how a build script can use a crate as a
-dependency purely for the build process and not for the crate itself at runtime.
-
-# Case study: Linking to system libraries
-
-The final case study here will be investigating how a Cargo library links to a
-system library and how the build script is leveraged to support this use case.
-
-Quite frequently a Rust crate wants to link to a native library often provided
-on the system to bind its functionality or just use it as part of an
-implementation detail. This is quite a nuanced problem when it comes to
-performing this in a platform-agnostic fashion, and the purpose of a build
-script is again to farm out as much of this as possible to make this as easy as
-possible for consumers.
-
-As an example to follow, let’s take a look at one of [Cargo’s own
-dependencies][git2-rs], [libgit2][libgit2]. The C library has a number of
-constraints:
-
-[git2-rs]: https://github.com/alexcrichton/git2-rs/tree/master/libgit2-sys
-[libgit2]: https://github.com/libgit2/libgit2
-
-* It has an optional dependency on OpenSSL on Unix to implement the https
- transport.
-* It has an optional dependency on libssh2 on all platforms to implement the ssh
- transport.
-* It is often not installed on all systems by default.
-* It can be built from source using `cmake`.
-
-To visualize what’s going on here, let’s take a look at the manifest for the
-relevant Cargo package that links to the native C library.
-
-```toml
-[package]
-name = "libgit2-sys"
-version = "0.1.0"
-authors = ["..."]
-links = "git2"
-build = "build.rs"
-
-[dependencies]
-libssh2-sys = { git = "https://github.com/alexcrichton/ssh2-rs" }
-
-[target.'cfg(unix)'.dependencies]
-openssl-sys = { git = "https://github.com/alexcrichton/openssl-sys" }
-
-# ...
-```
-
-As the above manifests show, we’ve got a `build` script specified, but it’s
-worth noting that this example has a `links` entry which indicates that the
-crate (`libgit2-sys`) links to the `git2` native library.
-
-Here we also see that we chose to have the Rust crate have an unconditional
-dependency on `libssh2` via the `libssh2-sys` crate, as well as a
-platform-specific dependency on `openssl-sys` for \*nix (other variants elided
-for now). It may seem a little counterintuitive to express *C dependencies* in
-the *Cargo manifest*, but this is actually using one of Cargo’s conventions in
-this space.
-
-## `*-sys` Packages
-
-To alleviate linking to system libraries, Cargo has a *convention* of package
-naming and functionality. Any package named `foo-sys` will provide two major
-pieces of functionality:
-
-* The library crate will link to the native library `libfoo`. This will often
- probe the current system for `libfoo` before resorting to building from
- source.
-* The library crate will provide **declarations** for functions in `libfoo`,
- but it does **not** provide bindings or higher-level abstractions.
-
-The set of `*-sys` packages provides a common set of dependencies for linking
-to native libraries. There are a number of benefits earned from having this
-convention of native-library-related packages:
-
-* Common dependencies on `foo-sys` alleviates the above rule about one package
- per value of `links`.
-* A common dependency allows centralizing logic on discovering `libfoo` itself
- (or building it from source).
-* These dependencies are easily overridable.
-
-## Building libgit2
-
-Now that we’ve got libgit2’s dependencies sorted out, we need to actually write
-the build script. We’re not going to look at specific snippets of code here and
-instead only take a look at the high-level details of the build script of
-`libgit2-sys`. This is not recommending all packages follow this strategy, but
-rather just outlining one specific strategy.
-
-The first step of the build script should do is to query whether libgit2 is
-already installed on the host system. To do this we’ll leverage the preexisting
-tool `pkg-config` (when its available). We’ll also use a `build-dependencies`
-section to refactor out all the `pkg-config` related code (or someone’s already
-done that!).
-
-If `pkg-config` failed to find libgit2, or if `pkg-config` just wasn’t
-installed, the next step is to build libgit2 from bundled source code
-(distributed as part of `libgit2-sys` itself). There are a few nuances when
-doing so that we need to take into account, however:
-
-* The build system of libgit2, `cmake`, needs to be able to find libgit2’s
- optional dependency of libssh2. We’re sure we’ve already built it (it’s a
- Cargo dependency), we just need to communicate this information. To do this
- we leverage the metadata format to communicate information between build
- scripts. In this example the libssh2 package printed out `cargo:root=...` to
- tell us where libssh2 is installed at, and we can then pass this along to
- cmake with the `CMAKE_PREFIX_PATH` environment variable.
-
-* We’ll need to handle some `CFLAGS` values when compiling C code (and tell
- `cmake` about this). Some flags we may want to pass are `-m64` for 64-bit
- code, `-m32` for 32-bit code, or `-fPIC` for 64-bit code as well.
-
-* Finally, we’ll invoke `cmake` to place all output into the `OUT_DIR`
- environment variable, and then we’ll print the necessary metadata to instruct
- rustc how to link to libgit2.
-
-Most of the functionality of this build script is easily refactorable into
-common dependencies, so our build script isn’t quite as intimidating as this
-descriptions! In reality it’s expected that build scripts are quite succinct by
-farming logic such as above to build dependencies.
+++ /dev/null
-% Configuration
-
-This document will explain how Cargo’s configuration system works, as well as
-available keys or configuration. For configuration of a project through its
-manifest, see the [manifest format](manifest.html).
-
-# Hierarchical structure
-
-Cargo allows local configuration for a particular project as well as global
-configuration, like git. Cargo extends this to a hierarchical strategy.
-If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the
-following configuration files would be probed for and unified in this order:
-
-* `/projects/foo/bar/baz/.cargo/config`
-* `/projects/foo/bar/.cargo/config`
-* `/projects/foo/.cargo/config`
-* `/projects/.cargo/config`
-* `/.cargo/config`
-* `$HOME/.cargo/config`
-
-With this structure, you can specify configuration per-project, and even
-possibly check it into version control. You can also specify personal defaults
-with a configuration file in your home directory.
-
-# Configuration format
-
-All configuration is currently in the [TOML format][toml] (like the manifest),
-with simple key-value pairs inside of sections (tables) which all get merged
-together.
-
-[toml]: https://github.com/toml-lang/toml
-
-# Configuration keys
-
-All of the following keys are optional, and their defaults are listed as their
-value unless otherwise noted.
-
-Key values that specify a tool may be given as an absolute path, a relative path
-or as a pathless tool name. Absolute paths and pathless tool names are used as
-given. Relative paths are resolved relative to the parent directory of the
-`.cargo` directory of the config file that the value resides within.
-
-```toml
-# An array of paths to local repositories which are to be used as overrides for
-# dependencies. For more information see the Specifying Dependencies guide.
-paths = ["/path/to/override"]
-
-[cargo-new]
-# This is your name/email to place in the `authors` section of a new Cargo.toml
-# that is generated. If not present, then `git` will be probed, and if that is
-# not present then `$USER` and `$EMAIL` will be used.
-name = "..."
-email = "..."
-
-# By default `cargo new` will initialize a new Git repository. This key can be
-# set to `hg` to create a Mercurial repository, or `none` to disable this
-# behavior.
-vcs = "none"
-
-# For the following sections, $triple refers to any valid target triple, not the
-# literal string "$triple", and it will apply whenever that target triple is
-# being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for
-# conditional compilation.
-[target.$triple]
-# This is the linker which is passed to rustc (via `-C linker=`) when the `$triple`
-# is being compiled for. By default this flag is not passed to the compiler.
-linker = ".."
-# Same but for the library archiver which is passed to rustc via `-C ar=`.
-ar = ".."
-# If a runner is provided, compiled targets for the `$triple` will be executed
-# by invoking the specified runner executable with actual target as first argument.
-# This applies to `cargo run`, `cargo test` and `cargo bench` commands.
-# By default compiled targets are executed directly.
-runner = ".."
-# custom flags to pass to all compiler invocations that target $triple
-# this value overrides build.rustflags when both are present
-rustflags = ["..", ".."]
-
-[target.'cfg(...)']
-# Similar for the $triple configuration, but using the `cfg` syntax.
-# If several `cfg` and $triple targets are candidates, then the rustflags
-# are concatenated. The `cfg` syntax only applies to rustflags, and not to
-# linker.
-rustflags = ["..", ".."]
-
-# Configuration keys related to the registry
-[registry]
-index = "..." # URL of the registry index (defaults to the central repository)
-token = "..." # Access token (found on the central repo’s website)
-
-[http]
-proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
- # in libcurl format, e.g. "socks5h://host:port"
-timeout = 60000 # Timeout for each HTTP request, in milliseconds
-cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
-check-revoke = true # Indicates whether SSL certs are checked for revocation
-
-[build]
-jobs = 1 # number of parallel jobs, defaults to # of CPUs
-rustc = "rustc" # the rust compiler tool
-rustdoc = "rustdoc" # the doc generator tool
-target = "triple" # build for the target triple
-target-dir = "target" # path of where to place all generated artifacts
-rustflags = ["..", ".."] # custom flags to pass to all compiler invocations
-incremental = true # whether or not to enable incremental compilation
-
-[term]
-verbose = false # whether cargo provides verbose output
-color = 'auto' # whether cargo colorizes output
-
-# Network configuration
-[net]
-retry = 2 # number of times a network call will automatically retried
-
-# Alias cargo commands. The first 3 aliases are built in. If your
-# command requires grouped whitespace use the list format.
-[alias]
-b = "build"
-t = "test"
-r = "run"
-rr = "run --release"
-space_example = ["run", "--release", "--", "\"command list\""]
-```
-
-# Environment variables
-
-Cargo can also be configured through environment variables in addition to the
-TOML syntax above. For each configuration key above of the form `foo.bar` the
-environment variable `CARGO_FOO_BAR` can also be used to define the value. For
-example the `build.jobs` key can also be defined by `CARGO_BUILD_JOBS`.
-
-Environment variables will take precedent over TOML configuration, and currently
-only integer, boolean, and string keys are supported to be defined by
-environment variables.
-
-In addition to the system above, Cargo recognizes a few other specific
-[environment variables][env].
-
-[env]: environment-variables.html
+++ /dev/null
-% Publishing on crates.io
-
-Once you've got a library that you'd like to share with the world, it's time to
-publish it on [crates.io]! Publishing a crate is when a specific
-version is uploaded to be hosted on [crates.io].
-
-Take care when publishing a crate, because a publish is **permanent**. The
-version can never be overwritten, and the code cannot be deleted. There is no
-limit to the number of versions which can be published, however.
-
-# Before your first publish
-
-First thing’s first, you’ll need an account on [crates.io] to acquire
-an API token. To do so, [visit the home page][crates.io] and log in via a GitHub
-account (required for now). After this, visit your [Account
-Settings](https://crates.io/me) page and run the `cargo login` command
-specified.
-
-```notrust
-$ cargo login abcdefghijklmnopqrstuvwxyz012345
-```
-
-This command will inform Cargo of your API token and store it locally in your
-`~/.cargo/credentials` (previously it was `~/.cargo/config`). Note that this
-token is a **secret** and should not be shared with anyone else. If it leaks for
-any reason, you should regenerate it immediately.
-
-# Before publishing a new crate
-
-Keep in mind that crate names on [crates.io] are allocated on a first-come-first-
-serve basis. Once a crate name is taken, it cannot be used for another crate.
-
-## Packaging a crate
-
-The next step is to package up your crate into a format that can be uploaded to
-[crates.io]. For this we’ll use the `cargo package` subcommand. This will take
-our entire crate and package it all up into a `*.crate` file in the
-`target/package` directory.
-
-```notrust
-$ cargo package
-```
-
-As an added bonus, the `*.crate` will be verified independently of the current
-source tree. After the `*.crate` is created, it’s unpacked into
-`target/package` and then built from scratch to ensure that all necessary files
-are there for the build to succeed. This behavior can be disabled with the
-`--no-verify` flag.
-
-Now’s a good time to take a look at the `*.crate` file to make sure you didn’t
-accidentally package up that 2GB video asset, or large data files used for code
-generation, integration tests, or benchmarking. There is currently a 10MB
-upload size limit on `*.crate` files. So, if the size of `tests` and `benches`
-directories and their dependencies are up to a couple of MBs, you can keep them
-in your package; otherwise, better to exclude them.
-
-Cargo will automatically ignore files ignored by your version control system
-when packaging, but if you want to specify an extra set of files to ignore you
-can use the `exclude` key in the manifest:
-
-```toml
-[package]
-# ...
-exclude = [
- "public/assets/*",
- "videos/*",
-]
-```
-
-The syntax of each element in this array is what
-[rust-lang/glob](https://github.com/rust-lang/glob) accepts. If you’d rather
-roll with a whitelist instead of a blacklist, Cargo also supports an `include`
-key, which if set, overrides the `exclude` key:
-
-```toml
-[package]
-# ...
-include = [
- "**/*.rs",
- "Cargo.toml",
-]
-```
-
-## Uploading the crate
-
-Now that we’ve got a `*.crate` file ready to go, it can be uploaded to
-[crates.io] with the `cargo publish` command. And that’s it, you’ve now published
-your first crate!
-
-```notrust
-$ cargo publish
-```
-
-If you’d like to skip the `cargo package` step, the `cargo publish` subcommand
-will automatically package up the local crate if a copy isn’t found already.
-
-Be sure to check out the [metadata you can
-specify](manifest.html#package-metadata) to ensure your crate can be discovered
-more easily!
-
-# Publishing a new version of an existing crate
-
-In order to release a new version, change the `version` value specified in your
-`Cargo.toml` manifest. Keep in mind [the semver
-rules](manifest.html#the-version-field). Then optionally run `cargo package` if
-you want to inspect the `*.crate` file for the new version before publishing,
-and run `cargo publish` to upload the new version.
-
-# Managing a crates.io-based crate
-
-Management of crates is primarily done through the command line `cargo` tool
-rather than the [crates.io] web interface. For this, there are a few subcommands
-to manage a crate.
-
-## `cargo yank`
-
-Occasions may arise where you publish a version of a crate that actually ends up
-being broken for one reason or another (syntax error, forgot to include a file,
-etc.). For situations such as this, Cargo supports a “yank” of a version of a
-crate.
-
-```notrust
-$ cargo yank --vers 1.0.1
-$ cargo yank --vers 1.0.1 --undo
-```
-
-A yank **does not** delete any code. This feature is not intended for deleting
-accidentally uploaded secrets, for example. If that happens, you must reset
-those secrets immediately.
-
-The semantics of a yanked version are that no new dependencies can be created
-against that version, but all existing dependencies continue to work. One of the
-major goals of [crates.io] is to act as a permanent archive of crates that does
-not change over time, and allowing deletion of a version would go against this
-goal. Essentially a yank means that all projects with a `Cargo.lock` will not
-break, while any future `Cargo.lock` files generated will not list the yanked
-version.
-
-## `cargo owner`
-
-A crate is often developed by more than one person, or the primary maintainer
-may change over time! The owner of a crate is the only person allowed to publish
-new versions of the crate, but an owner may designate additional owners.
-
-```notrust
-$ cargo owner --add my-buddy
-$ cargo owner --remove my-buddy
-$ cargo owner --add github:rust-lang:owners
-$ cargo owner --remove github:rust-lang:owners
-```
-
-The owner IDs given to these commands must be GitHub user names or GitHub teams.
-
-If a user name is given to `--add`, that user becomes a “named” owner, with
-full rights to the crate. In addition to being able to publish or yank versions
-of the crate, they have the ability to add or remove owners, *including* the
-owner that made *them* an owner. Needless to say, you shouldn’t make people you
-don’t fully trust into a named owner. In order to become a named owner, a user
-must have logged into [crates.io] previously.
-
-If a team name is given to `--add`, that team becomes a “team” owner, with
-restricted right to the crate. While they have permission to publish or yank
-versions of the crate, they *do not* have the ability to add or remove owners.
-In addition to being more convenient for managing groups of owners, teams are
-just a bit more secure against owners becoming malicious.
-
-The syntax for teams is currently `github:org:team` (see examples above).
-In order to add a team as an owner one must be a member of that team. No
-such restriction applies to removing a team as an owner.
-
-## GitHub permissions
-
-Team membership is not something GitHub provides simple public access to, and it
-is likely for you to encounter the following message when working with them:
-
-> It looks like you don’t have permission to query a necessary property from
-GitHub to complete this request. You may need to re-authenticate on [crates.io]
-to grant permission to read GitHub org memberships. Just go to
-https://crates.io/login
-
-This is basically a catch-all for “you tried to query a team, and one of the
-five levels of membership access control denied this”. That is not an
-exaggeration. GitHub’s support for team access control is Enterprise Grade.
-
-The most likely cause of this is simply that you last logged in before this
-feature was added. We originally requested *no* permissions from GitHub when
-authenticating users, because we didn’t actually ever use the user’s token for
-anything other than logging them in. However to query team membership on your
-behalf, we now require
-[the `read:org` scope](https://developer.github.com/v3/oauth/#scopes).
-
-You are free to deny us this scope, and everything that worked before teams
-were introduced will keep working. However you will never be able to add a team
-as an owner, or publish a crate as a team owner. If you ever attempt to do this,
-you will get the error above. You may also see this error if you ever try to
-publish a crate that you don’t own at all, but otherwise happens to have a team.
-
-If you ever change your mind, or just aren’t sure if [crates.io] has sufficient
-permission, you can always go to https://crates.io/login, which will prompt you
-for permission if [crates.io] doesn’t have all the scopes it would like to.
-
-An additional barrier to querying GitHub is that the organization may be
-actively denying third party access. To check this, you can go to:
-
- https://github.com/organizations/:org/settings/oauth_application_policy
-
-where `:org` is the name of the organization (e.g. rust-lang). You may see
-something like:
-
-
-
-Where you may choose to explicitly remove [crates.io] from your organization’s
-blacklist, or simply press the “Remove Restrictions” button to allow all third
-party applications to access this data.
-
-Alternatively, when [crates.io] requested the `read:org` scope, you could have
-explicitly whitelisted [crates.io] querying the org in question by pressing
-the “Grant Access” button next to its name:
-
-
-
-[crates.io]: https://crates.io/
+++ /dev/null
-% Environment Variables
-
-Cargo sets and reads a number of environment variables which your code can detect
-or override. Here is a list of the variables Cargo sets, organized by when it interacts
-with them:
-
-# Environment variables Cargo reads
-
-You can override these environment variables to change Cargo's behavior on your
-system:
-
-* `CARGO_HOME` - Cargo maintains a local cache of the registry index and of git
- checkouts of crates. By default these are stored under `$HOME/.cargo`, but
- this variable overrides the location of this directory. Once a crate is cached
- it is not removed by the clean command.
-* `CARGO_TARGET_DIR` - Location of where to place all generated artifacts,
- relative to the current working directory.
-* `RUSTC` - Instead of running `rustc`, Cargo will execute this specified
- compiler instead.
-* `RUSTC_WRAPPER` - Instead of simply running `rustc`, Cargo will execute this
- specified wrapper instead, passing as its commandline arguments the rustc
- invocation, with the first argument being rustc.
-* `RUSTDOC` - Instead of running `rustdoc`, Cargo will execute this specified
- `rustdoc` instance instead.
-* `RUSTDOCFLAGS` - A space-separated list of custom flags to pass to all `rustdoc`
- invocations that Cargo performs. In contrast with `cargo rustdoc`, this is
- useful for passing a flag to *all* `rustdoc` instances.
-* `RUSTFLAGS` - A space-separated list of custom flags to pass to all compiler
- invocations that Cargo performs. In contrast with `cargo rustc`, this is
- useful for passing a flag to *all* compiler instances.
-* `CARGO_INCREMENTAL` - If this is set to 1 then Cargo will force incremental
- compilation to be enabled for the current compilation, and when set to 0 it
- will force disabling it. If this env var isn't present then Cargo's defaults
- will otherwise be used.
-
-Note that Cargo will also read environment variables for `.cargo/config`
-configuration values, as described in [that documentation][config-env]
-
-[config-env]: config.html#environment-variables
-
-# Environment variables Cargo sets for crates
-
-Cargo exposes these environment variables to your crate when it is compiled.
-Note that this applies for test binaries as well.
-To get the value of any of these variables in a Rust program, do this:
-
-```
-let version = env!("CARGO_PKG_VERSION");
-```
-
-`version` will now contain the value of `CARGO_PKG_VERSION`.
-
-* `CARGO` - Path to the `cargo` binary performing the build.
-* `CARGO_MANIFEST_DIR` - The directory containing the manifest of your package.
-* `CARGO_PKG_VERSION` - The full version of your package.
-* `CARGO_PKG_VERSION_MAJOR` - The major version of your package.
-* `CARGO_PKG_VERSION_MINOR` - The minor version of your package.
-* `CARGO_PKG_VERSION_PATCH` - The patch version of your package.
-* `CARGO_PKG_VERSION_PRE` - The pre-release version of your package.
-* `CARGO_PKG_AUTHORS` - Colon separated list of authors from the manifest of your package.
-* `CARGO_PKG_NAME` - The name of your package.
-* `CARGO_PKG_DESCRIPTION` - The description of your package.
-* `CARGO_PKG_HOMEPAGE` - The home page of your package.
-* `OUT_DIR` - If the package has a build script, this is set to the folder where the build
- script should place its output. See below for more information.
-
-# Environment variables Cargo sets for build scripts
-
-Cargo sets several environment variables when build scripts are run. Because these variables
-are not yet set when the build script is compiled, the above example using `env!` won't work
-and instead you'll need to retrieve the values when the build script is run:
-
-```
-use std::env;
-let out_dir = env::var("OUT_DIR").unwrap();
-```
-
-`out_dir` will now contain the value of `OUT_DIR`.
-
-* `CARGO` - Path to the `cargo` binary performing the build.
-* `CARGO_MANIFEST_DIR` - The directory containing the manifest for the package
- being built (the package containing the build
- script). Also note that this is the value of the
- current working directory of the build script when it
- starts.
-* `CARGO_MANIFEST_LINKS` - the manifest `links` value.
-* `CARGO_FEATURE_<name>` - For each activated feature of the package being
- built, this environment variable will be present
- where `<name>` is the name of the feature uppercased
- and having `-` translated to `_`.
-* `CARGO_CFG_<cfg>` - For each [configuration option][configuration] of the
- package being built, this environment variable will
- contain the value of the configuration, where `<cfg>` is
- the name of the configuration uppercased and having `-`
- translated to `_`.
- Boolean configurations are present if they are set, and
- not present otherwise.
- Configurations with multiple values are joined to a
- single variable with the values delimited by `,`.
-* `OUT_DIR` - the folder in which all output should be placed. This folder is
- inside the build directory for the package being built, and it is
- unique for the package in question.
-* `TARGET` - the target triple that is being compiled for. Native code should be
- compiled for this triple. Some more information about target
- triples can be found in [clang’s own documentation][clang].
-* `HOST` - the host triple of the rust compiler.
-* `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can
- be useful to pass a `-j` parameter to a system like `make`. Note
- that care should be taken when interpreting this environment
- variable. For historical purposes this is still provided but
- recent versions of Cargo, for example, do not need to run `make
- -j` as it'll automatically happen. Cargo implements its own
- [jobserver] and will allow build scripts to inherit this
- information, so programs compatible with GNU make jobservers will
- already have appropriately configured parallelism.
-* `OPT_LEVEL`, `DEBUG` - values of the corresponding variables for the
- profile currently being built.
-* `PROFILE` - `release` for release builds, `debug` for other builds.
-* `DEP_<name>_<key>` - For more information about this set of environment
- variables, see build script documentation about [`links`][links].
-* `RUSTC`, `RUSTDOC` - the compiler and documentation generator that Cargo has
- resolved to use, passed to the build script so it might
- use it as well.
-
-[links]: build-script.html#the-links-manifest-key
-[profile]: manifest.html#the-profile-sections
-[configuration]: https://doc.rust-lang.org/reference/attributes.html#conditional-compilation
-[clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple
-[jobserver]: http://make.mad-scientist.net/papers/jobserver-implementation/
-
-# Environment variables Cargo sets for 3rd party subcommands
-
-Cargo exposes this environment variable to 3rd party subcommands
-(ie. programs named `cargo-foobar` placed in `$PATH`):
-
-* `CARGO` - Path to the `cargo` binary performing the build.
+++ /dev/null
-% External tools
-
-One of the goals of Cargo is simple integration with third-party tools, like
-IDEs and other build systems. To make integration easier, Cargo has several
-facilities:
-
-* a `cargo metadata` command, which outputs project structure and dependencies
- information in JSON,
-
-* a `--message-format` flag, which outputs information about a particular build,
- and
-
-* support for custom subcommands.
-
-
-# Information about project structure
-
-You can use `cargo metadata` command to get information about project structure
-and dependencies. The output of the command looks like this:
-
-```text
-{
- // Integer version number of the format.
- "version": integer,
-
- // List of packages for this workspace, including dependencies.
- "packages": [
- {
- // Opaque package identifier.
- "id": PackageId,
-
- "name": string,
-
- "version": string,
-
- "source": SourceId,
-
- // A list of declared dependencies, see `resolve` field for actual dependencies.
- "dependencies": [ Dependency ],
-
- "targets: [ Target ],
-
- // Path to Cargo.toml
- "manifest_path": string,
- }
- ],
-
- "workspace_members": [ PackageId ],
-
- // Dependencies graph.
- "resolve": {
- "nodes": [
- {
- "id": PackageId,
- "dependencies": [ PackageId ]
- }
- ]
- }
-}
-```
-
-The format is stable and versioned. When calling `cargo metadata`, you should
-pass `--format-version` flag explicitly to avoid forward incompatibility
-hazard.
-
-If you are using Rust, there is [cargo_metadata] crate.
-
-[cargo_metadata]: https://crates.io/crates/cargo_metadata
-
-
-# Information about build
-
-When passing `--message-format=json`, Cargo will output the following
-information during the build:
-
-* compiler errors and warnings,
-
-* produced artifacts,
-
-* results of the build scripts (for example, native dependencies).
-
-The output goes to stdout in the JSON object per line format. The `reason` field
-distinguishes different kinds of messages.
-
-Information about dependencies in the Makefile-compatible format is stored in
-the `.d` files alongside the artifacts.
-
-
-# Custom subcommands
-
-Cargo is designed to be extensible with new subcommands without having to modify
-Cargo itself. This is achieved by translating a cargo invocation of the form
-cargo `(?<command>[^ ]+)` into an invocation of an external tool
-`cargo-${command}` that then needs to be present in one of the user's `$PATH`
-directories.
-
-Custom subcommand may use `CARGO` environment variable to call back to
-Cargo. Alternatively, it can link to `cargo` crate as a library, but this
-approach has drawbacks:
-
-* Cargo as a library is unstable, API changes without deprecation,
-
-* versions of Cargo library and Cargo binary may be different.
+++ /dev/null
-% Frequently Asked Questions
-
-# Is the plan to use GitHub as a package repository?
-
-No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with
-npmjs.org and rubygems.org.
-
-We plan to support git repositories as a source of packages forever,
-because they can be used for early development and temporary patches,
-even when people use the registry as the primary source of packages.
-
-# Why build crates.io rather than use GitHub as a registry?
-
-We think that it’s very important to support multiple ways to download
-packages, including downloading from GitHub and copying packages into
-your project itself.
-
-That said, we think that [crates.io] offers a number of important benefits, and
-will likely become the primary way that people download packages in Cargo.
-
-For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a
-central registry model as well as a Git-based model, and most packages
-are downloaded through the registry in those ecosystems, with an
-important minority of packages making use of git-based packages.
-
-[1]: https://www.npmjs.org
-[2]: https://bundler.io
-
-Some of the advantages that make a central registry popular in other
-languages include:
-
-* **Discoverability**. A central registry provides an easy place to look
- for existing packages. Combined with tagging, this also makes it
- possible for a registry to provide ecosystem-wide information, such as a
- list of the most popular or most-depended-on packages.
-* **Speed**. A central registry makes it possible to easily fetch just
- the metadata for packages quickly and efficiently, and then to
- efficiently download just the published package, and not other bloat
- that happens to exist in the repository. This adds up to a significant
- improvement in the speed of dependency resolution and fetching. As
- dependency graphs scale up, downloading all of the git repositories bogs
- down fast. Also remember that not everybody has a high-speed,
- low-latency Internet connection.
-
-# Will Cargo work with C code (or other languages)?
-
-Yes!
-
-Cargo handles compiling Rust code, but we know that many Rust projects
-link against C code. We also know that there are decades of tooling
-built up around compiling languages other than Rust.
-
-Our solution: Cargo allows a package to [specify a script](build-script.html)
-(written in Rust) to run before invoking `rustc`. Rust is leveraged to
-implement platform-specific configuration and refactor out common build
-functionality among packages.
-
-# Can Cargo be used inside of `make` (or `ninja`, or ...)
-
-Indeed. While we intend Cargo to be useful as a standalone way to
-compile Rust projects at the top-level, we know that some people will
-want to invoke Cargo from other build tools.
-
-We have designed Cargo to work well in those contexts, paying attention
-to things like error codes and machine-readable output modes. We still
-have some work to do on those fronts, but using Cargo in the context of
-conventional scripts is something we designed for from the beginning and
-will continue to prioritize.
-
-# Does Cargo handle multi-platform projects or cross-compilation?
-
-Rust itself provides facilities for configuring sections of code based
-on the platform. Cargo also supports [platform-specific
-dependencies][target-deps], and we plan to support more per-platform
-configuration in `Cargo.toml` in the future.
-
-[target-deps]: manifest.html#the-dependencies-section
-
-In the longer-term, we’re looking at ways to conveniently cross-compile
-projects using Cargo.
-
-# Does Cargo support environments, like `production` or `test`?
-
-We support environments through the use of [profiles][profile] to support:
-
-[profile]: manifest.html#the-profile-sections
-
-* environment-specific flags (like `-g --opt-level=0` for development
- and `--opt-level=3` for production).
-* environment-specific dependencies (like `hamcrest` for test assertions).
-* environment-specific `#[cfg]`
-* a `cargo test` command
-
-# Does Cargo work on Windows?
-
-Yes!
-
-All commits to Cargo are required to pass the local test suite on Windows.
-If, however, you find a Windows issue, we consider it a bug, so [please file an
-issue][3].
-
-[3]: https://github.com/rust-lang/cargo/issues
-
-# Why do binaries have `Cargo.lock` in version control, but not libraries?
-
-The purpose of a `Cargo.lock` is to describe the state of the world at the time
-of a successful build. It is then used to provide deterministic builds across
-whatever machine is building the project by ensuring that the exact same
-dependencies are being compiled.
-
-This property is most desirable from applications and projects which are at the
-very end of the dependency chain (binaries). As a result, it is recommended that
-all binaries check in their `Cargo.lock`.
-
-For libraries the situation is somewhat different. A library is not only used by
-the library developers, but also any downstream consumers of the library. Users
-dependent on the library will not inspect the library’s `Cargo.lock` (even if it
-exists). This is precisely because a library should **not** be deterministically
-recompiled for all users of the library.
-
-If a library ends up being used transitively by several dependencies, it’s
-likely that just a single copy of the library is desired (based on semver
-compatibility). If all libraries were to check in their `Cargo.lock`, then
-multiple copies of the library would be used, and perhaps even a version
-conflict.
-
-In other words, libraries specify semver requirements for their dependencies but
-cannot see the full picture. Only end products like binaries have a full
-picture to decide what versions of dependencies should be used.
-
-# Can libraries use `*` as a version for their dependencies?
-
-**As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries)
-with wildcard dependency constraints.**
-
-While libraries _can_, strictly speaking, they should not. A version requirement
-of `*` says “This will work with every version ever,” which is never going
-to be true. Libraries should always specify the range that they do work with,
-even if it’s something as general as “every 1.x.y version.”
-
-# Why `Cargo.toml`?
-
-As one of the most frequent interactions with Cargo, the question of why the
-configuration file is named `Cargo.toml` arises from time to time. The leading
-capital-`C` was chosen to ensure that the manifest was grouped with other
-similar configuration files in directory listings. Sorting files often puts
-capital letters before lowercase letters, ensuring files like `Makefile` and
-`Cargo.toml` are placed together. The trailing `.toml` was chosen to emphasize
-the fact that the file is in the [TOML configuration
-format](https://github.com/toml-lang/toml).
-
-Cargo does not allow other names such as `cargo.toml` or `Cargofile` to
-emphasize the ease of how a Cargo repository can be identified. An option of
-many possible names has historically led to confusion where one case was handled
-but others were accidentally forgotten.
-
-[crates.io]: https://crates.io/
-
-# How can Cargo work offline?
-
-Cargo is often used in situations with limited or no network access such as
-airplanes, CI environments, or embedded in large production deployments. Users
-are often surprised when Cargo attempts to fetch resources from the network, and
-hence the request for Cargo to work offline comes up frequently.
-
-Cargo, at its heart, will not attempt to access the network unless told to do
-so. That is, if no crates comes from crates.io, a git repository, or some other
-network location, Cargo will never attempt to make a network connection. As a
-result, if Cargo attempts to touch the network, then it's because it needs to
-fetch a required resource.
-
-Cargo is also quite aggressive about caching information to minimize the amount
-of network activity. It will guarantee, for example, that if `cargo build` (or
-an equivalent) is run to completion then the next `cargo build` is guaranteed to
-not touch the network so long as `Cargo.toml` has not been modified in the
-meantime. This avoidance of the network boils down to a `Cargo.lock` existing
-and a populated cache of the crates reflected in the lock file. If either of
-these components are missing, then they're required for the build to succeed and
-must be fetched remotely.
-
-As of Rust 1.11.0 Cargo understands a new flag, `--frozen`, which is an
-assertion that it shouldn't touch the network. When passed, Cargo will
-immediately return an error if it would otherwise attempt a network request.
-The error should include contextual information about why the network request is
-being made in the first place to help debug as well. Note that this flag *does
-not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch
-the network as a previous command has been run to ensure that network activity
-shouldn't be necessary.
-
-For more information about vendoring, see documentation on [source
-replacement][replace].
-
-[replace]: source-replacement.html
+++ /dev/null
-</main>
-<footer>
-<a href='index.html'>Install</a>
-<span class='sep'>|</span>
-<a href='index.html'>Getting Started</a>
-<span class='sep'>|</span>
-<a href='guide.html'>Guide</a>
-</footer>
-
-<script type='text/javascript' src='javascripts/prism.js'></script>
-<script type='text/javascript' src='javascripts/all.js'></script>
+++ /dev/null
-% Cargo Guide
-
-Welcome to the Cargo guide. This guide will give you all that you need to know
-about how to use Cargo to develop Rust projects.
-
-# Why Cargo exists
-
-Cargo is a tool that allows Rust projects to declare their various
-dependencies and ensure that you’ll always get a repeatable build.
-
-To accomplish this goal, Cargo does four things:
-
-* Introduces two metadata files with various bits of project information.
-* Fetches and builds your project’s dependencies.
-* Invokes `rustc` or another build tool with the correct parameters to build
- your project.
-* Introduces conventions to make working with Rust projects easier.
-
-# Creating a new project
-
-To start a new project with Cargo, use `cargo new`:
-
-```shell
-$ cargo new hello_world --bin
-```
-
-We’re passing `--bin` because we’re making a binary program: if we
-were making a library, we’d leave it off. This also initializes a new `git`
-repository by default. If you don't want it to do that, pass `--vcs none`.
-
-Let’s check out what Cargo has generated for us:
-
-```shell
-$ cd hello_world
-$ tree .
-.
-├── Cargo.toml
-└── src
- └── main.rs
-
-1 directory, 2 files
-```
-
-If we had just used `cargo new hello_world` without the `--bin` flag, then
-we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
-we need to get started. First, let’s check out `Cargo.toml`:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-```
-
-This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
-
-Here’s what’s in `src/main.rs`:
-
-```rust
-fn main() {
- println!("Hello, world!");
-}
-```
-
-Cargo generated a “hello world” for us. Let’s compile it:
-
-```shell
-$ cargo build
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-And then run it:
-
-```shell
-$ ./target/debug/hello_world
-Hello, world!
-```
-
-We can also use `cargo run` to compile and then run it, all in one step (You
-won't see the `Compiling` line if you have not made any changes since you last
-compiled):
-
-```shell
-$ cargo run
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running `target/debug/hello_world`
-Hello, world!
-```
-
-You’ll now notice a new file, `Cargo.lock`. It contains information about our
-dependencies. Since we don’t have any yet, it’s not very interesting.
-
-Once you’re ready for release, you can use `cargo build --release` to compile
-your files with optimizations turned on:
-
-```shell
-$ cargo build --release
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-`cargo build --release` puts the resulting binary in `target/release` instead of
-`target/debug`.
-
-Compiling in debug mode is the default for development-- compilation time is
-shorter since the compiler doesn't do optimizations, but the code will run
-slower. Release mode takes longer to compile, but the code will run faster.
-
-# Working on an existing Cargo project
-
-If you download an existing project that uses Cargo, it’s really easy
-to get going.
-
-First, get the project from somewhere. In this example, we’ll use `rand`
-cloned from its repository on GitHub:
-
-```shell
-$ git clone https://github.com/rust-lang-nursery/rand.git
-$ cd rand
-```
-
-To build, use `cargo build`:
-
-```shell
-$ cargo build
- Compiling rand v0.1.0 (file:///path/to/project/rand)
-```
-
-This will fetch all of the dependencies and then build them, along with the
-project.
-
-# Adding dependencies from crates.io
-
-[crates.io] is the Rust community's central package registry that serves as a
-location to discover and download packages. `cargo` is configured to use it by
-default to find requested packages.
-
-To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.
-
-[crates.io]: https://crates.io/
-
-## Adding a dependency
-
-If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
-then list the crate name and version that you would like to use. This example
-adds a dependency of the `time` crate:
-
-```toml
-[dependencies]
-time = "0.1.12"
-```
-
-The version string is a [semver] version requirement. The [specifying
-dependencies](specifying-dependencies.html) docs have more information about
-the options you have here.
-
-[semver]: https://github.com/steveklabnik/semver#requirements
-
-If we also wanted to add a dependency on the `regex` crate, we would not need
-to add `[dependencies]` for each crate listed. Here's what your whole
-`Cargo.toml` file would look like with dependencies on the `time` and `regex`
-crates:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-time = "0.1.12"
-regex = "0.1.41"
-```
-
-Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
-their dependencies, compile them all, and update the `Cargo.lock`:
-
-```shell
-$ cargo build
- Updating registry `https://github.com/rust-lang/crates.io-index`
- Downloading memchr v0.1.5
- Downloading libc v0.1.10
- Downloading regex-syntax v0.2.1
- Downloading memchr v0.1.5
- Downloading aho-corasick v0.3.0
- Downloading regex v0.1.41
- Compiling memchr v0.1.5
- Compiling libc v0.1.10
- Compiling regex-syntax v0.2.1
- Compiling memchr v0.1.5
- Compiling aho-corasick v0.3.0
- Compiling regex v0.1.41
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-Our `Cargo.lock` contains the exact information about which revision of all of
-these dependencies we used.
-
-Now, if `regex` gets updated, we will still build with the same revision until
-we choose to `cargo update`.
-
-You can now use the `regex` library using `extern crate` in `main.rs`.
-
-```rust
-extern crate regex;
-
-use regex::Regex;
-
-fn main() {
- let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
- println!("Did our date match? {}", re.is_match("2014-01-01"));
-}
-```
-
-Running it will show:
-
-```shell
-$ cargo run
- Running `target/hello_world`
-Did our date match? true
-```
-# Project layout
-
-Cargo uses conventions for file placement to make it easy to dive into a new
-Cargo project:
-
-```shell
-.
-├── Cargo.lock
-├── Cargo.toml
-├── benches
-│ └── large-input.rs
-├── examples
-│ └── simple.rs
-├── src
-│ ├── bin
-│ │ └── another_executable.rs
-│ ├── lib.rs
-│ └── main.rs
-└── tests
- └── some-integration-tests.rs
-```
-
-* `Cargo.toml` and `Cargo.lock` are stored in the root of your project (*package
- root*).
-* Source code goes in the `src` directory.
-* The default library file is `src/lib.rs`.
-* The default executable file is `src/main.rs`.
-* Other executables can be placed in `src/bin/*.rs`.
-* Integration tests go in the `tests` directory (unit tests go in each file
- they're testing).
-* Examples go in the `examples` directory.
-* Benchmarks go in the `benches` directory.
-
-These are explained in more detail in the [manifest
-description](manifest.html#the-project-layout).
-
-# Cargo.toml vs Cargo.lock
-
-`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
-about them, here’s a summary:
-
-* `Cargo.toml` is about describing your dependencies in a broad sense, and is
- written by you.
-* `Cargo.lock` contains exact information about your dependencies. It is
- maintained by Cargo and should not be manually edited.
-
-If you’re building a library that other projects will depend on, put
-`Cargo.lock` in your `.gitignore`. If you’re building an executable like a
-command-line tool or an application, check `Cargo.lock` into `git`. If you're
-curious about why that is, see ["Why do binaries have `Cargo.lock` in version
-control, but not libraries?" in the
-FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
-
-Let’s dig in a little bit more.
-
-`Cargo.toml` is a **manifest** file in which we can specify a bunch of
-different metadata about our project. For example, we can say that we depend
-on another project:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-This project has a single dependency, on the `rand` library. We’ve stated in
-this case that we’re relying on a particular Git repository that lives on
-GitHub. Since we haven’t specified any other information, Cargo assumes that
-we intend to use the latest commit on the `master` branch to build our project.
-
-Sound good? Well, there’s one problem: If you build this project today, and
-then you send a copy to me, and I build this project tomorrow, something bad
-could happen. There could be more commits to `rand` in the meantime, and my
-build would include new commits while yours would not. Therefore, we would
-get different builds. This would be bad because we want reproducible builds.
-
-We could fix this problem by putting a `rev` line in our `Cargo.toml`:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
-```
-
-Now our builds will be the same. But there’s a big drawback: now we have to
-manually think about SHA-1s every time we want to update our library. This is
-both tedious and error prone.
-
-Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
-keep track of the exact revisions: Cargo will do it for us. When we have a
-manifest like this:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
-```
-
-Cargo will take the latest commit and write that information out into our
-`Cargo.lock` when we build for the first time. That file will look like this:
-
-```toml
-[[package]]
-name = "hello_world"
-version = "0.1.0"
-dependencies = [
- "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)",
-]
-
-[[package]]
-name = "rand"
-version = "0.1.0"
-source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
-```
-
-You can see that there’s a lot more information here, including the exact
-revision we used to build. Now when you give your project to someone else,
-they’ll use the exact same SHA, even though we didn’t specify it in our
-`Cargo.toml`.
-
-When we’re ready to opt in to a new version of the library, Cargo can
-re-calculate the dependencies and update things for us:
-
-```shell
-$ cargo update # updates all dependencies
-$ cargo update -p rand # updates just “rand”
-```
-
-This will write out a new `Cargo.lock` with the new version information. Note
-that the argument to `cargo update` is actually a
-[Package ID Specification](pkgid-spec.html) and `rand` is just a short
-specification.
-
-# Tests
-
-Cargo can run your tests with the `cargo test` command. Cargo looks for tests
-to run in two places: in each of your `src` files and any tests in `tests/`.
-Tests in your `src` files should be unit tests, and tests in `tests/` should be
-integration-style tests. As such, you’ll need to import your crates into
-the files in `tests`.
-
-Here's an example of running `cargo test` in our project, which currently has
-no tests:
-
-```shell
-$ cargo test
- Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running target/test/hello_world-9c2b65bbb79eabce
-
-running 0 tests
-
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
-```
-
-If our project had tests, we would see more output with the correct number of
-tests.
-
-You can also run a specific test by passing a filter:
-
-```shell
-$ cargo test foo
-```
-
-This will run any test with `foo` in its name.
-
-`cargo test` runs additional checks as well. For example, it will compile any
-examples you’ve included and will also test the examples in your
-documentation. Please see the [testing guide][testing] in the Rust
-documentation for more details.
-
-[testing]: https://doc.rust-lang.org/book/testing.html
-
-## Travis CI
-
-To test your project on Travis CI, here is a sample `.travis.yml` file:
-
-```yaml
-language: rust
-rust:
- - stable
- - beta
- - nightly
-matrix:
- allow_failures:
- - rust: nightly
-```
-
-This will test all three release channels, but any breakage in nightly
-will not fail your overall build. Please see the [Travis CI Rust
-documentation](https://docs.travis-ci.com/user/languages/rust/) for more
-information.
-
-
-## Build cache
-
-Cargo shares build artifacts among all the packages of a single workspace.
-Today, Cargo does not share build results across different workspaces, but
-a similar result can be achieved by using a third party tool, [sccache].
-
-To setup `sccache`, install it with `cargo install sccache` and set
-`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo.
-If you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
-`.bashrc`. Refer to sccache documentation for more details.
-
-[sccache]: https://github.com/mozilla/sccache
-
-
-# Further reading
-
-Now that you have an overview of how to use cargo and have created your first
-crate, you may be interested in:
-
-* [Publishing your crate on crates.io](crates-io.html)
-* [Reading about all the possible ways of specifying dependencies](specifying-dependencies.html)
-* [Learning more details about what you can specify in your `Cargo.toml` manifest](manifest.html)
-
-Even more topics are available in the Docs menu at the top!
+++ /dev/null
-<a href='https://github.com/rust-lang/cargo' class='fork-me'>
- <img src='images/forkme.png'/>
-</a>
-
-<div id="header">
- <a href='https://crates.io' class='logo'>
- <img id="logo" height=100 width=100 src='images/Cargo-Logo-Small.png'/>
- </a>
- <a href="index.html">
- <h1>CARGO</h1>
- </a>
-
- <div class="search">
- <form action="https://crates.io/search"
- method="GET">
- <input name="q" class="search" placeholder="Search crates" type="text"/>
- </form>
- </div>
-
- <div class="nav">
- <a href='https://crates.io/crates'>Browse All Crates</a>
-
- <span class='sep'>|</span>
-
- <div class="dropdown-container">
- <button class="dropdown">
- Docs
- <span class="arrow"></span>
- </button>
- <!-- Sync this list with
- https://github.com/rust-lang/crates.io/blob/master/app/templates/application.hbs
- and with Makefile.in in this repository -->
- <ul id="current-user-links" class="dropdown" data-bindattr-503="503">
- <li><a href='index.html'>Getting Started</a></li>
- <li><a href='guide.html'>Guide</a></li>
- <li><a href='specifying-dependencies.html'>Specifying Dependencies</a></li>
- <li><a href='crates-io.html'>Publishing on crates.io</a></li>
- <li><a href='faq.html'>FAQ</a></li>
- <li><a href='manifest.html'>Cargo.toml Format</a></li>
- <li><a href='build-script.html'>Build Scripts</a></li>
- <li><a href='config.html'>Configuration</a></li>
- <li><a href='pkgid-spec.html'>Package ID specs</a></li>
- <li><a href='environment-variables.html'>Environment Variables</a></li>
- <li><a href='source-replacement.html'>Source Replacement</a></li>
- <li><a href='external-tools.html'>External Tools</a></li>
- <li><a href='https://crates.io/policies'>Policies</a></li>
- </ul>
- </div>
- </div>
-</div>
-
-<main>
+++ /dev/null
-<script src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
-<link rel="icon" type="image/x-icon" href="favicon.ico">
+++ /dev/null
-% Cargo, Rust’s Package Manager
-
-# Installing
-
-### Install Stable Rust and Cargo
-
-The easiest way to get Cargo is to get the current stable release of [Rust] by
-using the `rustup` script:
-
-```shell
-$ curl -sSf https://static.rust-lang.org/rustup.sh | sh
-```
-
-After this, you can use the `rustup` command to also install `beta` or `nightly`
-channels for Rust and Cargo.
-
-### Install Nightly Cargo
-
-To install just Cargo, the current recommended installation method is through
-the official nightly builds. Note that Cargo will also require that [Rust] is
-already installed on the system.
-
-| Platform | 64-bit | 32-bit |
-|------------------|-------------------|-------------------|
-| Linux binaries | [tar.gz][linux64] | [tar.gz][linux32] |
-| MacOS binaries | [tar.gz][mac64] | [tar.gz][mac32] |
-| Windows binaries | [tar.gz][win64] | [tar.gz][win32] |
-
-### Build and Install Cargo from Source
-
-Alternatively, you can [build Cargo from source][compiling-from-source].
-
-[rust]: https://www.rust-lang.org/
-[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz
-[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz
-[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz
-[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz
-[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz
-[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz
-[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source
-
-# Let’s get started
-
-To start a new project with Cargo, use `cargo new`:
-
-```shell
-$ cargo new hello_world --bin
-```
-
-We’re passing `--bin` because we’re making a binary program: if we
-were making a library, we’d leave it off.
-
-Let’s check out what Cargo has generated for us:
-
-```shell
-$ cd hello_world
-$ tree .
-.
-├── Cargo.toml
-└── src
- └── main.rs
-
-1 directory, 2 files
-```
-
-This is all we need to get started. First, let’s check out `Cargo.toml`:
-
-```toml
-[package]
-name = "hello_world"
-version = "0.1.0"
-authors = ["Your Name <you@example.com>"]
-```
-
-This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your project.
-
-Here’s what’s in `src/main.rs`:
-
-```
-fn main() {
- println!("Hello, world!");
-}
-```
-
-Cargo generated a “hello world” for us. Let’s compile it:
-
-```shell
-$ cargo build
- Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
-```
-
-And then run it:
-
-```shell
-$ ./target/debug/hello_world
-Hello, world!
-```
-
-We can also use `cargo run` to compile and then run it, all in one step:
-
-```shell
-$ cargo run
- Fresh hello_world v0.1.0 (file:///path/to/project/hello_world)
- Running `target/hello_world`
-Hello, world!
-```
-
-# Going further
-
-For more details on using Cargo, check out the [Cargo Guide](guide.html)
+++ /dev/null
-//= require_tree .
-
-Prism.languages.toml = {
- // https://github.com/LeaVerou/prism/issues/307
- 'comment': [{
- pattern: /(^[^"]*?("[^"]*?"[^"]*?)*?[^"\\]*?)(\/\*[\w\W]*?\*\/|(^|[^:])#.*?(\r?\n|$))/g,
- lookbehind: true
- }],
- 'string': /("|')(\\?.)*?\1/g,
- 'number': /\d+/,
- 'boolean': /true|false/,
- 'toml-section': /\[.*\]/,
- 'toml-key': /[\w-]+/
-};
-
-$(function() {
- var pres = document.querySelectorAll('pre.rust');
- for (var i = 0; i < pres.length; i++) {
- pres[i].className += ' language-rust';
- }
-
- // Toggles docs menu
- $('button.dropdown, a.dropdown').click(function(el, e) {
- $(this).toggleClass('active').siblings('ul').toggleClass('open');
-
- return false;
- });
-
- // A click in the page anywhere but in the menu will turn the menu off
- $(document).on('click', function(e) {
- // Checks to make sure the click did not come from inside dropdown menu
- // if it doesn't we close the menu
- // else, we do nothing and just follow the link
- if (!$(e.target).closest('ul.dropdown').length) {
- var toggles = $('button.dropdown.active, a.dropdown.active');
- toggles.toggleClass('active').siblings('ul').toggleClass('open');
-
- }
- });
-});
+++ /dev/null
-/* http://prismjs.com/download.html?themes=prism&languages=markup+css+clike+javascript */
-self="undefined"!=typeof window?window:"undefined"!=typeof WorkerGlobalScope&&self instanceof WorkerGlobalScope?self:{};var Prism=function(){var e=/\blang(?:uage)?-(?!\*)(\w+)\b/i,t=self.Prism={util:{encode:function(e){return e instanceof n?new n(e.type,t.util.encode(e.content),e.alias):"Array"===t.util.type(e)?e.map(t.util.encode):e.replace(/&/g,"&").replace(/</g,"<").replace(/\u00a0/g," ")},type:function(e){return Object.prototype.toString.call(e).match(/\[object (\w+)\]/)[1]},clone:function(e){var n=t.util.type(e);switch(n){case"Object":var a={};for(var r in e)e.hasOwnProperty(r)&&(a[r]=t.util.clone(e[r]));return a;case"Array":return e.slice()}return e}},languages:{extend:function(e,n){var a=t.util.clone(t.languages[e]);for(var r in n)a[r]=n[r];return a},insertBefore:function(e,n,a,r){r=r||t.languages;var i=r[e],l={};for(var o in i)if(i.hasOwnProperty(o)){if(o==n)for(var s in a)a.hasOwnProperty(s)&&(l[s]=a[s]);l[o]=i[o]}return r[e]=l},DFS:function(e,n){for(var a in e)n.call(e,a,e[a]),"Object"===t.util.type(e)&&t.languages.DFS(e[a],n)}},highlightAll:function(e,n){for(var a,r=document.querySelectorAll('code[class*="language-"], [class*="language-"] code, code[class*="lang-"], [class*="lang-"] code'),i=0;a=r[i++];)t.highlightElement(a,e===!0,n)},highlightElement:function(a,r,i){for(var l,o,s=a;s&&!e.test(s.className);)s=s.parentNode;if(s&&(l=(s.className.match(e)||[,""])[1],o=t.languages[l]),o){a.className=a.className.replace(e,"").replace(/\s+/g," ")+" language-"+l,s=a.parentNode,/pre/i.test(s.nodeName)&&(s.className=s.className.replace(e,"").replace(/\s+/g," ")+" language-"+l);var c=a.textContent;if(c){var g={element:a,language:l,grammar:o,code:c};if(t.hooks.run("before-highlight",g),r&&self.Worker){var u=new Worker(t.filename);u.onmessage=function(e){g.highlightedCode=n.stringify(JSON.parse(e.data),l),t.hooks.run("before-insert",g),g.element.innerHTML=g.highlightedCode,i&&i.call(g.element),t.hooks.run("after-highlight",g)},u.postMessage(JSON.stringify({language:g.language,code:g.code}))}else g.highlightedCode=t.highlight(g.code,g.grammar,g.language),t.hooks.run("before-insert",g),g.element.innerHTML=g.highlightedCode,i&&i.call(a),t.hooks.run("after-highlight",g)}}},highlight:function(e,a,r){var i=t.tokenize(e,a);return n.stringify(t.util.encode(i),r)},tokenize:function(e,n){var a=t.Token,r=[e],i=n.rest;if(i){for(var l in i)n[l]=i[l];delete n.rest}e:for(var l in n)if(n.hasOwnProperty(l)&&n[l]){var o=n[l];o="Array"===t.util.type(o)?o:[o];for(var s=0;s<o.length;++s){var c=o[s],g=c.inside,u=!!c.lookbehind,f=0,h=c.alias;c=c.pattern||c;for(var p=0;p<r.length;p++){var d=r[p];if(r.length>e.length)break e;if(!(d instanceof a)){c.lastIndex=0;var m=c.exec(d);if(m){u&&(f=m[1].length);var y=m.index-1+f,m=m[0].slice(f),v=m.length,k=y+v,b=d.slice(0,y+1),w=d.slice(k+1),N=[p,1];b&&N.push(b);var O=new a(l,g?t.tokenize(m,g):m,h);N.push(O),w&&N.push(w),Array.prototype.splice.apply(r,N)}}}}}return r},hooks:{all:{},add:function(e,n){var a=t.hooks.all;a[e]=a[e]||[],a[e].push(n)},run:function(e,n){var a=t.hooks.all[e];if(a&&a.length)for(var r,i=0;r=a[i++];)r(n)}}},n=t.Token=function(e,t,n){this.type=e,this.content=t,this.alias=n};if(n.stringify=function(e,a,r){if("string"==typeof e)return e;if("[object Array]"==Object.prototype.toString.call(e))return e.map(function(t){return n.stringify(t,a,e)}).join("");var i={type:e.type,content:n.stringify(e.content,a,r),tag:"span",classes:["token",e.type],attributes:{},language:a,parent:r};if("comment"==i.type&&(i.attributes.spellcheck="true"),e.alias){var l="Array"===t.util.type(e.alias)?e.alias:[e.alias];Array.prototype.push.apply(i.classes,l)}t.hooks.run("wrap",i);var o="";for(var s in i.attributes)o+=s+'="'+(i.attributes[s]||"")+'"';return"<"+i.tag+' class="'+i.classes.join(" ")+'" '+o+">"+i.content+"</"+i.tag+">"},!self.document)return self.addEventListener?(self.addEventListener("message",function(e){var n=JSON.parse(e.data),a=n.language,r=n.code;self.postMessage(JSON.stringify(t.util.encode(t.tokenize(r,t.languages[a])))),self.close()},!1),self.Prism):self.Prism;var a=document.getElementsByTagName("script");return a=a[a.length-1],a&&(t.filename=a.src,document.addEventListener&&!a.hasAttribute("data-manual")&&document.addEventListener("DOMContentLoaded",t.highlightAll)),self.Prism}();"undefined"!=typeof module&&module.exports&&(module.exports=Prism);;
-Prism.languages.markup={comment:/<!--[\w\W]*?-->/g,prolog:/<\?.+?\?>/,doctype:/<!DOCTYPE.+?>/,cdata:/<!\[CDATA\[[\w\W]*?]]>/i,tag:{pattern:/<\/?[\w:-]+\s*(?:\s+[\w:-]+(?:=(?:("|')(\\?[\w\W])*?\1|[^\s'">=]+))?\s*)*\/?>/gi,inside:{tag:{pattern:/^<\/?[\w:-]+/i,inside:{punctuation:/^<\/?/,namespace:/^[\w-]+?:/}},"attr-value":{pattern:/=(?:('|")[\w\W]*?(\1)|[^\s>]+)/gi,inside:{punctuation:/=|>|"/g}},punctuation:/\/?>/g,"attr-name":{pattern:/[\w:-]+/g,inside:{namespace:/^[\w-]+?:/}}}},entity:/\&#?[\da-z]{1,8};/gi},Prism.hooks.add("wrap",function(t){"entity"===t.type&&(t.attributes.title=t.content.replace(/&/,"&"))});;
-Prism.languages.css={comment:/\/\*[\w\W]*?\*\//g,atrule:{pattern:/@[\w-]+?.*?(;|(?=\s*{))/gi,inside:{punctuation:/[;:]/g}},url:/url\((["']?).*?\1\)/gi,selector:/[^\{\}\s][^\{\};]*(?=\s*\{)/g,property:/(\b|\B)[\w-]+(?=\s*:)/gi,string:/("|')(\\?.)*?\1/g,important:/\B!important\b/gi,punctuation:/[\{\};:]/g,"function":/[-a-z0-9]+(?=\()/gi},Prism.languages.markup&&Prism.languages.insertBefore("markup","tag",{style:{pattern:/<style[\w\W]*?>[\w\W]*?<\/style>/gi,inside:{tag:{pattern:/<style[\w\W]*?>|<\/style>/gi,inside:Prism.languages.markup.tag.inside},rest:Prism.languages.css}}});;
-Prism.languages.clike={comment:[{pattern:/(^|[^\\])\/\*[\w\W]*?\*\//g,lookbehind:!0},{pattern:/(^|[^\\:])\/\/.*?(\r?\n|$)/g,lookbehind:!0}],string:/("|')(\\?.)*?\1/g,"class-name":{pattern:/((?:(?:class|interface|extends|implements|trait|instanceof|new)\s+)|(?:catch\s+\())[a-z0-9_\.\\]+/gi,lookbehind:!0,inside:{punctuation:/(\.|\\)/}},keyword:/\b(if|else|while|do|for|return|in|instanceof|function|new|try|throw|catch|finally|null|break|continue)\b/g,"boolean":/\b(true|false)\b/g,"function":{pattern:/[a-z0-9_]+\(/gi,inside:{punctuation:/\(/}},number:/\b-?(0x[\dA-Fa-f]+|\d*\.?\d+([Ee]-?\d+)?)\b/g,operator:/[-+]{1,2}|!|<=?|>=?|={1,3}|&{1,2}|\|?\||\?|\*|\/|\~|\^|\%/g,ignore:/&(lt|gt|amp);/gi,punctuation:/[{}[\];(),.:]/g};;
-Prism.languages.javascript=Prism.languages.extend("clike",{keyword:/\b(break|case|catch|class|const|continue|debugger|default|delete|do|else|enum|export|extends|false|finally|for|function|get|if|implements|import|in|instanceof|interface|let|new|null|package|private|protected|public|return|set|static|super|switch|this|throw|true|try|typeof|var|void|while|with|yield)\b/g,number:/\b-?(0x[\dA-Fa-f]+|\d*\.?\d+([Ee]-?\d+)?|NaN|-?Infinity)\b/g}),Prism.languages.insertBefore("javascript","keyword",{regex:{pattern:/(^|[^/])\/(?!\/)(\[.+?]|\\.|[^/\r\n])+\/[gim]{0,3}(?=\s*($|[\r\n,.;})]))/g,lookbehind:!0}}),Prism.languages.markup&&Prism.languages.insertBefore("markup","tag",{script:{pattern:/<script[\w\W]*?>[\w\W]*?<\/script>/gi,inside:{tag:{pattern:/<script[\w\W]*?>|<\/script>/gi,inside:Prism.languages.markup.tag.inside},rest:Prism.languages.javascript}}});;
+++ /dev/null
-% The Manifest Format
-
-# The `[package]` section
-
-The first section in a `Cargo.toml` is `[package]`.
-
-```toml
-[package]
-name = "hello_world" # the name of the package
-version = "0.1.0" # the current version, obeying semver
-authors = ["you@example.com"]
-```
-
-All three of these fields are mandatory.
-
-## The `version` field
-
-Cargo bakes in the concept of [Semantic
-Versioning](http://semver.org/), 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 Rust, 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 tiny
- 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.
-
-## The `build` field (optional)
-
-This field specifies a file in the project root which is a [build script][1] for
-building native code. More information can be found in the build script
-[guide][1].
-
-[1]: build-script.html
-
-```toml
-[package]
-# ...
-build = "build.rs"
-```
-
-## The `documentation` field (optional)
-
-This field specifies a URL to a website hosting the crate's documentation.
-If no URL is specified in the manifest file, [crates.io][cratesio] will
-automatically link your crate to the corresponding [docs.rs][docsrs] page.
-
-Documentation links from specific hosts are blacklisted. Hosts are added
-to the blacklist if they are known to not be hosting documentation and are
-possibly of malicious intent e.g. ad tracking networks. URLs from the
-following hosts are blacklisted:
-
-* rust-ci.org
-
-Documentation URLs from blacklisted hosts will not appear on crates.io, and
-may be replaced by docs.rs links.
-
-[docsrs]: https://docs.rs/
-[cratesio]: https://crates.io/
-
-## The `exclude` and `include` fields (optional)
-
-You can explicitly specify to Cargo that a set of [globs][globs] should be
-ignored or included for the purposes of packaging and rebuilding a package. The
-globs specified in the `exclude` field identify a set of files that are not
-included when a package is published as well as ignored for the purposes of
-detecting when to rebuild a package, and the globs in `include` specify files
-that are explicitly included.
-
-If a VCS is being used for a package, the `exclude` field will be seeded with
-the VCS’ ignore settings (`.gitignore` for git for example).
-
-```toml
-[package]
-# ...
-exclude = ["build/**/*.o", "doc/**/*.html"]
-```
-
-```toml
-[package]
-# ...
-include = ["src/**/*", "Cargo.toml"]
-```
-
-The options are mutually exclusive: setting `include` will override an
-`exclude`. Note that `include` must be an exhaustive list of files as otherwise
-necessary source files may not be included.
-
-[globs]: http://doc.rust-lang.org/glob/glob/struct.Pattern.html
-
-### Migrating to `gitignore`-like pattern matching
-
-The current interpretation of these configs is based on UNIX Globs, as
-implemented in the [`glob` crate](https://crates.io/crates/glob). We want
-Cargo's `include` and `exclude` configs to work as similar to `gitignore` as
-possible. [The `gitignore` specification](https://git-scm.com/docs/gitignore) is
-also based on Globs, but has a bunch of additional features that enable easier
-pattern writing and more control. Therefore, we are migrating the interpretation
-for the rules of these configs to use the [`ignore`
-crate](https://crates.io/crates/ignore), and treat them each rule as a single
-line in a `gitignore` file. See [the tracking
-issue](https://github.com/rust-lang/cargo/issues/4268) for more details on the
-migration.
-
-## The `publish` field (optional)
-
-The `publish` field can be used to prevent a package from being published to a
-package registry (like *crates.io*) by mistake.
-
-```toml
-[package]
-# ...
-publish = false
-```
-
-## The `workspace` field (optional)
-
-The `workspace` field can be used to configure the workspace that this package
-will be a member of. If not specified this will be inferred as the first
-Cargo.toml with `[workspace]` upwards in the filesystem.
-
-```toml
-[package]
-# ...
-workspace = "path/to/workspace/root"
-```
-
-For more information, see the documentation for the workspace table below.
-
-## Package metadata
-
-There are a number of optional metadata fields also accepted under the
-`[package]` section:
-
-```toml
-[package]
-# ...
-
-# A short blurb about the package. This is not rendered in any format when
-# uploaded to crates.io (aka this is not markdown).
-description = "..."
-
-# These URLs point to more information about the package. These are
-# intended to be webviews of the relevant data, not necessarily compatible
-# with VCS tools and the like.
-documentation = "..."
-homepage = "..."
-repository = "..."
-
-# This points to a file under the package root (relative to this `Cargo.toml`).
-# The contents of this file are stored and indexed in the registry.
-# crates.io will render this file and place the result on the crate's page.
-readme = "..."
-
-# This is a list of up to five keywords that describe this crate. Keywords
-# are searchable on crates.io, and you may choose any words that would
-# help someone find this crate.
-keywords = ["...", "..."]
-
-# This is a list of up to five categories where this crate would fit.
-# Categories are a fixed list available at crates.io/category_slugs, and
-# they must match exactly.
-categories = ["...", "..."]
-
-# This is an SPDX 2.1 license expression for this package. Currently
-# crates.io will validate the license provided against a whitelist of
-# known license and exception identifiers from the SPDX license list
-# 2.4. Parentheses are not currently supported.
-#
-# Multiple licenses can be separated with a `/`, although that usage
-# is deprecated. Instead, use a license expression with AND and OR
-# operators to get more explicit semantics.
-license = "..."
-
-# If a project is using a nonstandard license, then this key may be specified in
-# lieu of the above key and must point to a file relative to this manifest
-# (similar to the readme key).
-license-file = "..."
-
-# Optional specification of badges to be displayed on crates.io.
-#
-# - The badges pertaining to build status that are currently available are
-# Appveyor, CircleCI, GitLab, and TravisCI.
-# - Available badges pertaining to code test coverage are Codecov and
-# Coveralls.
-# - There are also maintenance-related badges basesed on isitmaintained.com
-# which state the issue resolution time, percent of open issues, and future
-# maintenance intentions.
-#
-# If a `repository` key is required, this refers to a repository in
-# `user/repo` format.
-[badges]
-
-# Appveyor: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`; `id` is optional; you can specify the appveyor project id if you
-# want to use that instead. `project_name` is optional; use when the repository
-# name differs from the appveyor project name.
-appveyor = { repository = "...", branch = "master", service = "github" }
-
-# Circle CI: `repository` is required. `branch` is optional; default is `master`
-circle-ci = { repository = "...", branch = "master" }
-
-# GitLab: `repository` is required. `branch` is optional; default is `master`
-gitlab = { repository = "...", branch = "master" }
-
-# Travis CI: `repository` in format "<user>/<project>" is required.
-# `branch` is optional; default is `master`
-travis-ci = { repository = "...", branch = "master" }
-
-# Codecov: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default), `bitbucket`, and
-# `gitlab`.
-codecov = { repository = "...", branch = "master", service = "github" }
-
-# Coveralls: `repository` is required. `branch` is optional; default is `master`
-# `service` is optional; valid values are `github` (default) and `bitbucket`.
-coveralls = { repository = "...", branch = "master", service = "github" }
-
-# Is it maintained resolution time: `repository` is required.
-is-it-maintained-issue-resolution = { repository = "..." }
-
-# Is it maintained percentage of open issues: `repository` is required.
-is-it-maintained-open-issues = { repository = "..." }
-
-# Maintenance: `status` is required Available options are `actively-developed`,
-# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
-# and `deprecated`.
-maintenance = { status = "..." }
-```
-
-The [crates.io](https://crates.io) registry will render the description, display
-the license, link to the three URLs and categorize by the keywords. These keys
-provide useful information to users of the registry and also influence the
-search ranking of a crate. It is highly discouraged to omit everything in a
-published crate.
-
-SPDX 2.1 license expressions are documented
-[here][spdx-2.1-license-expressions]. The current version of the
-license list is available [here][spdx-license-list], and version 2.4
-is available [here][spdx-license-list-2.4].
-
-## The `metadata` table (optional)
-
-Cargo by default will warn about unused keys in `Cargo.toml` to assist in
-detecting typos and such. The `package.metadata` table, however, is completely
-ignored by Cargo and will not be warned about. This section can be used for
-tools which would like to store project configuration in `Cargo.toml`. For
-example:
-
-```toml
-[package]
-name = "..."
-# ...
-
-# Metadata used when generating an Android APK, for example.
-[package.metadata.android]
-package-name = "my-awesome-android-app"
-assets = "path/to/static"
-```
-
-# Dependency sections
-
-See the [specifying dependencies page](specifying-dependencies.html) for
-information on the `[dependencies]`, `[dev-dependencies]`,
-`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
-
-# The `[profile.*]` sections
-
-Cargo supports custom configuration of how rustc is invoked through profiles at
-the top level. Any manifest may declare a profile, but only the top level
-project’s profiles are actually read. All dependencies’ profiles will be
-overridden. This is done so the top-level project has control over how its
-dependencies are compiled.
-
-There are five currently supported profile names, all of which have the same
-configuration available to them. Listed below is the configuration available,
-along with the defaults for each profile.
-
-```toml
-# The development profile, used for `cargo build`.
-[profile.dev]
-opt-level = 0 # controls the `--opt-level` the compiler builds with.
- # 0-1 is good for debugging. 2 is well-optimized. Max is 3.
-debug = true # include debug information (debug symbols). Equivalent to
- # `-C debuginfo=2` compiler flag.
-rpath = false # controls whether compiler should set loader paths.
- # If true, passes `-C rpath` flag to the compiler.
-lto = false # Link Time Optimization usually reduces size of binaries
- # and static libraries. Increases compilation time.
- # If true, passes `-C lto` flag to the compiler.
-debug-assertions = true # controls whether debug assertions are enabled
- # (e.g. debug_assert!() and arithmetic overflow checks)
-codegen-units = 1 # if > 1 enables parallel code generation which improves
- # compile times, but prevents some optimizations.
- # Passes `-C codegen-units`. Ignored when `lto = true`.
-panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
-incremental = true # whether or not incremental compilation is enabled
-
-# The release profile, used for `cargo build --release`.
-[profile.release]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 1
-panic = 'unwind'
-incremental = false
-
-# The testing profile, used for `cargo test`.
-[profile.test]
-opt-level = 0
-debug = 2
-rpath = false
-lto = false
-debug-assertions = true
-codegen-units = 1
-panic = 'unwind'
-incremental = true
-
-# The benchmarking profile, used for `cargo bench` and `cargo test --release`.
-[profile.bench]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 1
-panic = 'unwind'
-incremental = false
-
-# The documentation profile, used for `cargo doc`.
-[profile.doc]
-opt-level = 0
-debug = 2
-rpath = false
-lto = false
-debug-assertions = true
-codegen-units = 1
-panic = 'unwind'
-incremental = true
-```
-
-# The `[features]` section
-
-Cargo supports features to allow expression of:
-
-* conditional compilation options (usable through `cfg` attributes);
-* optional dependencies, which enhance a package, but are not required; and
-* clusters of optional dependencies, such as `postgres`, that would include the
- `postgres` package, the `postgres-macros` package, and possibly other packages
- (such as development-time mocking libraries, debugging tools, etc.).
-
-A feature of a package is either an optional dependency, or a set of other
-features. The format for specifying features is:
-
-```toml
-[package]
-name = "awesome"
-
-[features]
-# The default set of optional packages. Most people will want to use these
-# packages, but they are strictly optional. Note that `session` is not a package
-# but rather another feature listed in this manifest.
-default = ["jquery", "uglifier", "session"]
-
-# A feature with no dependencies is used mainly for conditional compilation,
-# like `#[cfg(feature = "go-faster")]`.
-go-faster = []
-
-# The `secure-password` feature depends on the bcrypt package. This aliasing
-# will allow people to talk about the feature in a higher-level way and allow
-# this package to add more requirements to the feature in the future.
-secure-password = ["bcrypt"]
-
-# Features can be used to reexport features of other packages. The `session`
-# feature of package `awesome` will ensure that the `session` feature of the
-# package `cookie` is also enabled.
-session = ["cookie/session"]
-
-[dependencies]
-# These packages are mandatory and form the core of this package’s distribution.
-cookie = "1.2.0"
-oauth = "1.1.0"
-route-recognizer = "=2.1.0"
-
-# A list of all of the optional dependencies, some of which are included in the
-# above `features`. They can be opted into by apps.
-jquery = { version = "1.0.2", optional = true }
-uglifier = { version = "1.5.3", optional = true }
-bcrypt = { version = "*", optional = true }
-civet = { version = "*", optional = true }
-```
-
-To use the package `awesome`:
-
-```toml
-[dependencies.awesome]
-version = "1.3.5"
-default-features = false # do not include the default features, and optionally
- # cherry-pick individual features
-features = ["secure-password", "civet"]
-```
-
-## Rules
-
-The usage of features is subject to a few rules:
-
-* Feature names must not conflict with other package names in the manifest. This
- is because they are opted into via `features = [...]`, which only has a single
- namespace.
-* With the exception of the `default` feature, all features are opt-in. To opt
- out of the default feature, use `default-features = false` and cherry-pick
- individual features.
-* Feature groups are not allowed to cyclically depend on one another.
-* Dev-dependencies cannot be optional.
-* Features groups can only reference optional dependencies.
-* When a feature is selected, Cargo will call `rustc` with `--cfg
- feature="${feature_name}"`. If a feature group is included, it and all of its
- individual features will be included. This can be tested in code via
- `#[cfg(feature = "foo")]`.
-
-Note that it is explicitly allowed for features to not actually activate any
-optional dependencies. This allows packages to internally enable/disable
-features without requiring a new dependency.
-
-## Usage in end products
-
-One major use-case for this feature is specifying optional features in
-end-products. For example, the Servo project may want to include optional
-features that people can enable or disable when they build it.
-
-In that case, Servo will describe features in its `Cargo.toml` and they can be
-enabled using command-line flags:
-
-```
-$ cargo build --release --features "shumway pdf"
-```
-
-Default features could be excluded using `--no-default-features`.
-
-## Usage in packages
-
-In most cases, the concept of *optional dependency* in a library is best
-expressed as a separate package that the top-level application depends on.
-
-However, high-level packages, like Iron or Piston, may want the ability to
-curate a number of packages for easy installation. The current Cargo system
-allows them to curate a number of mandatory dependencies into a single package
-for easy installation.
-
-In some cases, packages may want to provide additional curation for optional
-dependencies:
-
-* grouping a number of low-level optional dependencies together into a single
- high-level feature;
-* specifying packages that are recommended (or suggested) to be included by
- users of the package; and
-* including a feature (like `secure-password` in the motivating example) that
- will only work if an optional dependency is available, and would be difficult
- to implement as a separate package (for example, it may be overly difficult to
- design an IO package to be completely decoupled from OpenSSL, with opt-in via
- the inclusion of a separate package).
-
-In almost all cases, it is an antipattern to use these features outside of
-high-level packages that are designed for curation. If a feature is optional, it
-can almost certainly be expressed as a separate package.
-
-# The `[workspace]` section
-
-Projects can define a workspace which is a set of crates that will all share the
-same `Cargo.lock` and output directory. The `[workspace]` table can be defined
-as:
-
-```toml
-[workspace]
-
-# Optional key, inferred from path dependencies if not present.
-# Additional non-path dependencies that should be included must be given here.
-# In particular, for a virtual manifest, all members have to be listed.
-members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-
-# Optional key, empty if not present.
-exclude = ["path1", "path/to/dir2"]
-```
-
-Workspaces were added to Cargo as part of [RFC 1525] and have a number of
-properties:
-
-* A workspace can contain multiple crates where one of them is the *root crate*.
-* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
- required to have other configuration.
-* Whenever any crate in the workspace is compiled, output is placed in the
- *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`.
-* The lock file for all crates in the workspace resides in the *workspace root*.
-* The `[patch]` and `[replace]` sections in `Cargo.toml` are only recognized
- in the *root crate*'s manifest, and ignored in member crates' manifests.
-
-[RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
-
-The *root crate* of a workspace, indicated by the presence of `[workspace]` in
-its manifest, is responsible for defining the entire workspace. All `path`
-dependencies residing in the workspace directory become members. You can add
-additional packages to the workspace by listing them in the `members` key. Note
-that members of the workspaces listed explicitly will also have their path
-dependencies included in the workspace. Sometimes a project may have a lot of
-workspace members and it can be onerous to keep up to date. The path dependency
-can also use [globs][globs] to match multiple paths. Finally, the `exclude`
-key can be used to blacklist paths from being included in a workspace. This can
-be useful if some path dependencies aren't desired to be in the workspace at
-all.
-
-The `package.workspace` manifest key (described above) is used in member crates
-to point at a workspace's root crate. If this key is omitted then it is inferred
-to be the first crate whose manifest contains `[workspace]` upwards in the
-filesystem.
-
-A crate may either specify `package.workspace` or specify `[workspace]`. That
-is, a crate cannot both be a root crate in a workspace (contain `[workspace]`)
-and also be a member crate of another workspace (contain `package.workspace`).
-
-Most of the time workspaces will not need to be dealt with as `cargo new` and
-`cargo init` will handle workspace configuration automatically.
-
-## Virtual Manifest
-
-In workspace manifests, if the `package` table is present, the workspace root
-crate will be treated as a normal package, as well as a workspace. If the
-`package` table is not present in a workspace manifest, it is called a *virtual
-manifest*.
-
-## Package selection
-
-In a workspace, package-related cargo commands like `cargo build` apply to
-packages selected by `-p` / `--package` or `--all` command-line parameters.
-When neither is specified, the optional `default-members` configuration is used:
-
-```toml
-[workspace]
-members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-default-members = ["path/to/member2", "path/to/member3/foo"]
-```
-
-When specified, `default-members` must expand to a subset of `members`.
-
-When `default-members` is not specified, the default is the root manifest
-if it is a package, or every member manifest (as if `--all` were specified
-on the command-line) for virtual workspaces.
-
-# The project layout
-
-If your project is an executable, name the main source file `src/main.rs`. If it
-is a library, name the main source file `src/lib.rs`.
-
-Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
-executable consists of more than just one source file, you might also use a directory
-inside `src/bin` containing a `main.rs` file which will be treated as an executable
-with a name of the parent directory.
-Do note, however, once you add a `[[bin]]` section ([see
-below](#configuring-a-target)), Cargo will no longer automatically build files
-located in `src/bin/*.rs`. Instead you must create a `[[bin]]` section for
-each file you want to build.
-
-Your project can optionally contain folders named `examples`, `tests`, and
-`benches`, which Cargo will treat as containing examples,
-integration tests, and benchmarks respectively. Analogous to `bin` targets, they
-may be composed of single files or directories with a `main.rs` file.
-
-```notrust
-▾ src/ # directory containing source files
- lib.rs # the main entry point for libraries and packages
- main.rs # the main entry point for projects producing executables
- ▾ bin/ # (optional) directory containing additional executables
- *.rs
- ▾ */ # (optional) directories containing multi-file executables
- main.rs
-▾ examples/ # (optional) examples
- *.rs
- ▾ */ # (optional) directories containing multi-file examples
- main.rs
-▾ tests/ # (optional) integration tests
- *.rs
- ▾ */ # (optional) directories containing multi-file tests
- main.rs
-▾ benches/ # (optional) benchmarks
- *.rs
- ▾ */ # (optional) directories containing multi-file benchmarks
- main.rs
-```
-
-To structure your code after you've created the files and folders for your
-project, you should remember to use Rust's module system, which you can read
-about in [the book](https://doc.rust-lang.org/book/crates-and-modules.html).
-
-# Examples
-
-Files located under `examples` are example uses of the functionality provided by
-the library. When compiled, they are placed in the `target/examples` directory.
-
-They can compile either as executables (with a `main()` function) or libraries
-and pull in the library by using `extern crate <library-name>`. They are
-compiled when you run your tests to protect them from bitrotting.
-
-You can run individual executable examples with the command `cargo run --example
-<example-name>`.
-
-Specify `crate-type` to make an example be compiled as a library:
-
-```toml
-[[example]]
-name = "foo"
-crate-type = ["staticlib"]
-```
-
-You can build individual library examples with the command `cargo build
---example <example-name>`.
-
-# Tests
-
-When you run `cargo test`, Cargo will:
-
-* compile and run your library’s unit tests, which are in the files reachable
- from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
- considered at this stage);
-* compile and run your library’s documentation tests, which are embedded inside
- of documentation blocks;
-* compile and run your library’s [integration tests](#integration-tests); and
-* compile your library’s examples.
-
-## Integration tests
-
-Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
-Cargo will compile each of these files as a separate crate. The crate can link
-to your library by using `extern crate <library-name>`, like any other code that
-depends on it.
-
-Cargo will not automatically compile files inside subdirectories of `tests`, but
-an integration test can import modules from these directories as usual. For
-example, if you want several integration tests to share some code, you can put
-the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
-the test files.
-
-# Configuring a target
-
-All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
-sections support similar configuration for specifying how a target should be
-built. The double-bracket sections like `[[bin]]` are array-of-table of
-[TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can
-write more than one `[[bin]]` section to make several executables in your crate.
-
-The example below uses `[lib]`, but it also applies to all other sections
-as well. All values listed are the defaults for that option unless otherwise
-specified.
-
-```toml
-[package]
-# ...
-
-[lib]
-# The name of a target is the name of the library that will be generated. This
-# is defaulted to the name of the package or project, with any dashes replaced
-# with underscores. (Rust `extern crate` declarations reference this name;
-# therefore the value must be a valid Rust identifier to be usable.)
-name = "foo"
-
-# This field points at where the crate is located, relative to the `Cargo.toml`.
-path = "src/lib.rs"
-
-# A flag for enabling unit tests for this target. This is used by `cargo test`.
-test = true
-
-# A flag for enabling documentation tests for this target. This is only relevant
-# for libraries, it has no effect on other sections. This is used by
-# `cargo test`.
-doctest = true
-
-# A flag for enabling benchmarks for this target. This is used by `cargo bench`.
-bench = true
-
-# A flag for enabling documentation of this target. This is used by `cargo doc`.
-doc = true
-
-# If the target is meant to be a compiler plugin, this field must be set to true
-# for Cargo to correctly compile it and make it available for all dependencies.
-plugin = false
-
-# If the target is meant to be a "macros 1.1" procedural macro, this field must
-# be set to true.
-proc-macro = false
-
-# If set to false, `cargo test` will omit the `--test` flag to rustc, which
-# stops it from generating a test harness. This is useful when the binary being
-# built manages the test runner itself.
-harness = true
-```
-
-## The `required-features` field (optional)
-
-The `required-features` field specifies which features the target needs in order
-to be built. If any of the required features are not selected, the target will
-be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`,
-and `[[example]]` sections, it has no effect on `[lib]`.
-
-```toml
-[features]
-# ...
-postgres = []
-sqlite = []
-tools = []
-
-[[bin]]
-# ...
-required-features = ["postgres", "tools"]
-```
-
-# Building dynamic or static libraries
-
-If your project produces a library, you can specify which kind of library to
-build by explicitly listing the library in your `Cargo.toml`:
-
-```toml
-# ...
-
-[lib]
-name = "..."
-crate-type = ["dylib"] # could be `staticlib` as well
-```
-
-The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and
-`proc-macro`. You should only use this option in a project. Cargo will always
-compile packages (dependencies) based on the requirements of the project that
-includes them.
-
-You can read more about the different crate types in the
-[Rust Reference Manual](https://doc.rust-lang.org/reference/linkage.html)
-
-# The `[patch]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[patch.crates-io]
-foo = { git = 'https://github.com/example/foo' }
-bar = { path = 'my/local/bar' }
-
-[dependencies.baz]
-git = 'https://github.com/example/baz'
-
-[patch.'https://github.com/example/baz']
-baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
-```
-
-The `[patch]` table is made of dependency-like sub-tables. Each key after
-`[patch]` is a URL of the source that's being patched, or `crates-io` if
-you're modifying the https://crates.io registry. In the example above
-`crates-io` could be replaced with a git URL such as
-`https://github.com/rust-lang-nursery/log`; the second `[patch]`
-section in the example uses this to specify a source called `baz`.
-
-Each entry in these tables is a normal dependency specification, the same as
-found in the `[dependencies]` section of the manifest. The dependencies listed
-in the `[patch]` section are resolved and used to patch the source at the
-URL specified. The above manifest snippet patches the `crates-io` source (e.g.
-crates.io itself) with the `foo` crate and `bar` crate. It also
-patches the `https://github.com/example/baz` source with a `my-branch` that
-comes from elsewhere.
-
-Sources can be patched with versions of crates that do not exist, and they can
-also be patched with versions of crates that already exist. If a source is
-patched with a crate version that already exists in the source, then the
-source's original crate is replaced.
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation and [RFC 1969] for the
-technical specification of this feature. Note that the `[patch]` feature will
-first become available in Rust 1.21, set to be released on 2017-10-12.
-
-[RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
-[replace]: specifying-dependencies.html#overriding-dependencies
-
-# The `[replace]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[replace]
-"foo:0.1.0" = { git = 'https://github.com/example/foo' }
-"bar:1.0.2" = { path = 'my/local/bar' }
-```
-
-Each key in the `[replace]` table is a [package id
-specification](pkgid-spec.html) which allows arbitrarily choosing a node in the
-dependency graph to override. The value of each key is the same as the
-`[dependencies]` syntax for specifying dependencies, except that you can't
-specify features. Note that when a crate is overridden the copy it's overridden
-with must have both the same name and version, but it can come from a different
-source (e.g. git or a local path).
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation.
-
-[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
-[spdx-license-list]: https://spdx.org/licenses/
-[spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4
+++ /dev/null
-% Package ID Specifications
-
-# Package ID specifications
-
-Subcommands of Cargo frequently need to refer to a particular package within a
-dependency graph for various operations like updating, cleaning, building, etc.
-To solve this problem, Cargo supports Package ID Specifications. A specification
-is a string which is used to uniquely refer to one package within a graph of
-packages.
-
-## Specification grammar
-
-The formal grammar for a Package Id Specification is:
-
-```notrust
-pkgid := pkgname
- | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
-pkgname := name [ ":" semver ]
-
-proto := "http" | "git" | ...
-```
-
-Here, brackets indicate that the contents are optional.
-
-## Example specifications
-
-These could all be references to a package `foo` version `1.2.3` from the
-registry at `crates.io`
-
-| pkgid | name | version | url |
-|:-----------------------------|:-----:|:-------:|:----------------------:|
-| `foo` | `foo` | `*` | `*` |
-| `foo:1.2.3` | `foo` | `1.2.3` | `*` |
-| `crates.io/foo` | `foo` | `*` | `*://crates.io/foo` |
-| `crates.io/foo#1.2.3` | `foo` | `1.2.3` | `*://crates.io/foo` |
-| `crates.io/bar#foo:1.2.3` | `foo` | `1.2.3` | `*://crates.io/bar` |
-| `http://crates.io/foo#1.2.3` | `foo` | `1.2.3` | `http://crates.io/foo` |
-
-## Brevity of specifications
-
-The goal of this is to enable both succinct and exhaustive syntaxes for
-referring to packages in a dependency graph. Ambiguous references may refer to
-one or more packages. Most commands generate an error if more than one package
-could be referred to with the same specification.
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta http-equiv="refresh" content="0;URL='https://crates.io/policies'" />
-</head>
-<body class="rustdoc">
- Redirecting to <a href="https://crates.io/policies">https://crates.io/policies</a>...
-</body>
-</html>
+++ /dev/null
-% Replacing sources
-
-Cargo supports the ability to **replace one source with another** to express
-strategies along the lines of mirrors or vendoring dependencies. Configuration
-is currently done through the [`.cargo/config` configuration][config] mechanism,
-like so:
-
-[config]: config.html
-
-```toml
-# The `source` table is where all keys related to source-replacement
-# are stored.
-[source]
-
-# Under the `source` table are a number of other tables whose keys are a
-# name for the relevant source. For example this section defines a new
-# source, called `my-awesome-source`, which comes from a directory
-# located at `vendor` relative to the directory containing this `.cargo/config`
-# file
-[source.my-awesome-source]
-directory = "vendor"
-
-# The crates.io default source for crates is available under the name
-# "crates-io", and here we use the `replace-with` key to indicate that it's
-# replaced with our source above.
-[source.crates-io]
-replace-with = "my-awesome-source"
-```
-
-With this configuration Cargo attempts to look up all crates in the directory
-"vendor" rather than querying the online registry at crates.io. Using source
-replacement Cargo can express:
-
-* Vendoring - custom sources can be defined which represent crates on the local
- filesystem. These sources are subsets of the source that they're replacing and
- can be checked into projects if necessary.
-
-* Mirroring - sources can be replaced with an equivalent version which acts as a
- cache for crates.io itself.
-
-Cargo has a core assumption about source replacement that the source code is
-exactly the same from both sources. In our above example Cargo assumes that all
-of the crates coming from `my-awesome-source` are the exact same as the copies
-from `crates-io`. Note that this also means that `my-awesome-source` is not
-allowed to have crates which are not present in the `crates-io` source.
-
-As a consequence, source replacement is not appropriate for situations such as
-patching a dependency or a private registry. Cargo supports patching
-dependencies through the usage of [the `[replace]` key][replace-section], and
-private registry support is planned for a future version of Cargo.
-
-[replace-section]: manifest.html#the-replace-section
-
-## Configuration
-
-Configuration of replacement sources is done through [`.cargo/config`][config]
-and the full set of available keys are:
-
-```toml
-# Each source has its own table where the key is the name of the source
-[source.the-source-name]
-
-# Indicate that `the-source-name` will be replaced with `another-source`,
-# defined elsewhere
-replace-with = "another-source"
-
-# Available kinds of sources that can be specified (described below)
-registry = "https://example.com/path/to/index"
-local-registry = "path/to/registry"
-directory = "path/to/vendor"
-
-# Git sources can optionally specify a branch/tag/rev as well
-git = "https://example.com/path/to/repo"
-# branch = "master"
-# tag = "v1.0.1"
-# rev = "313f44e8"
-```
-
-The `crates-io` represents the crates.io online registry (default source of
-crates) and can be replaced with:
-
-```toml
-[source.crates-io]
-replace-with = 'another-source'
-```
-
-## Registry Sources
-
-A "registry source" is one that is the same as crates.io itself. That is, it has
-an index served in a git repository which matches the format of the
-[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
-then has configuration indicating where to download crates from.
-
-Currently there is not an already-available project for setting up a mirror of
-crates.io. Stay tuned though!
-
-## Local Registry Sources
-
-A "local registry source" is intended to be a subset of another registry
-source, but available on the local filesystem (aka vendoring). Local registries
-are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are
-made up of a set of `*.crate` files and an index like the normal registry is.
-
-The primary way to manage and crate local registry sources is through the
-[`cargo-local-registry`][cargo-local-registry] subcommand, available on
-crates.io and can be installed with `cargo install cargo-local-registry`.
-
-[cargo-local-registry]: https://crates.io/crates/cargo-local-registry
-
-Local registries are contained within one directory and contain a number of
-`*.crate` files downloaded from crates.io as well as an `index` directory with
-the same format as the crates.io-index project (populated with just entries for
-the crates that are present).
-
-## Directory Sources
-
-A "directory source" is similar to a local registry source where it contains a
-number of crates available on the local filesystem, suitable for vendoring
-dependencies. Also like local registries, directory sources can primarily be
-managed by an external subcommand, [`cargo-vendor`][cargo-vendor], which can be
-installed with `cargo install cargo-vendor`.
-
-[cargo-vendor]: https://crates.io/crates/cargo-vendor
-
-Directory sources are distinct from local registries though in that they contain
-the unpacked version of `*.crate` files, making it more suitable in some
-situations to check everything into source control. A directory source is just a
-directory containing a number of other directories which contain the source code
-for crates (the unpacked version of `*.crate` files). Currently no restriction
-is placed on the name of each directory.
-
-Each crate in a directory source also has an associated metadata file indicating
-the checksum of each file in the crate to protect against accidental
-modifications.
+++ /dev/null
-% Specifying Dependencies
-
-Your crates can depend on other libraries from [crates.io], `git` repositories, or
-subdirectories on your local file system. You can also temporarily override the
-location of a dependency— for example, to be able to test out a bug fix in the
-dependency that you are working on locally. You can have different
-dependencies for different platforms, and dependencies that are only used during
-development. Let's take a look at how to do each of these.
-
-# Specifying dependencies from crates.io
-
-Cargo is configured to look for dependencies on [crates.io] by default. Only
-the name and a version string are required in this case. In [the cargo
-guide](guide.html), we specified a dependency on the `time` crate:
-
-```toml
-[dependencies]
-time = "0.1.12"
-```
-
-The string `"0.1.12"` is a [semver] version requirement. Since this
-string does not have any operators in it, it is interpreted the same way as
-if we had specified `"^0.1.12"`, which is called a caret requirement.
-
-[semver]: https://github.com/steveklabnik/semver#requirements
-
-## Caret requirements
-
-**Caret requirements** allow SemVer compatible updates to a specified version.
-An update is allowed if the new version number does not modify the left-most
-non-zero digit in the major, minor, patch grouping. In this case, if we ran
-`cargo update -p time`, cargo would update us to version `0.1.13` if it was
-available, but would not update us to `0.2.0`. If instead we had specified the
-version string as `^1.0`, cargo would update to `1.1` but not `2.0`. `0.0.x` is
-not considered compatible with any other version.
-
-Here are some more examples of caret requirements and the versions that would
-be allowed with them:
-
-```notrust
-^1.2.3 := >=1.2.3 <2.0.0
-^1.2 := >=1.2.0 <2.0.0
-^1 := >=1.0.0 <2.0.0
-^0.2.3 := >=0.2.3 <0.3.0
-^0.0.3 := >=0.0.3 <0.0.4
-^0.0 := >=0.0.0 <0.1.0
-^0 := >=0.0.0 <1.0.0
-```
-
-This compatibility convention is different from SemVer in the way it treats
-versions before 1.0.0. While SemVer says there is no compatibility before
-1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z`
-and `x > 0`.
-
-## Tilde requirements
-
-**Tilde requirements** specify a minimal version with some ability to update.
-If you specify a major, minor, and patch version or only a major and minor
-version, only patch-level changes are allowed. If you only specify a major
-version, then minor- and patch-level changes are allowed.
-
-`~1.2.3` is an example of a tilde requirement.
-
-```notrust
-~1.2.3 := >=1.2.3 <1.3.0
-~1.2 := >=1.2.0 <1.3.0
-~1 := >=1.0.0 <2.0.0
-```
-
-## Wildcard requirements
-
-**Wildcard requirements** allow for any version where the wildcard is
-positioned.
-
-`*`, `1.*` and `1.2.*` are examples of wildcard requirements.
-
-```notrust
-* := >=0.0.0
-1.* := >=1.0.0 <2.0.0
-1.2.* := >=1.2.0 <1.3.0
-```
-
-## Inequality requirements
-
-**Inequality requirements** allow manually specifying a version range or an
-exact version to depend on.
-
-Here are some examples of inequality requirements:
-
-```notrust
->= 1.2.0
-> 1
-< 2
-= 1.2.3
-```
-
-## Multiple requirements
-
-Multiple version requirements can also be separated with a comma, e.g. `>= 1.2,
-< 1.5`.
-
-# Specifying dependencies from `git` repositories
-
-To depend on a library located in a `git` repository, the minimum information
-you need to specify is the location of the repository with the `git` key:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand" }
-```
-
-Cargo will fetch the `git` repository at this location then look for a
-`Cargo.toml` for the requested crate anywhere inside the `git` repository
-(not necessarily at the root).
-
-Since we haven’t specified any other information, Cargo assumes that
-we intend to use the latest commit on the `master` branch to build our project.
-You can combine the `git` key with the `rev`, `tag`, or `branch` keys to
-specify something else. Here's an example of specifying that you want to use
-the latest commit on a branch named `next`:
-
-```toml
-[dependencies]
-rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }
-```
-
-# Specifying path dependencies
-
-Over time, our `hello_world` project from [the guide](guide.html) has grown
-significantly in size! It’s gotten to the point that we probably want to
-split out a separate crate for others to use. To do this Cargo supports
-**path dependencies** which are typically sub-crates that live within one
-repository. Let’s start off by making a new crate inside of our `hello_world`
-project:
-
-```shell
-# inside of hello_world/
-$ cargo new hello_utils
-```
-
-This will create a new folder `hello_utils` inside of which a `Cargo.toml` and
-`src` folder are ready to be configured. In order to tell Cargo about this, open
-up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies:
-
-```toml
-[dependencies]
-hello_utils = { path = "hello_utils" }
-```
-
-This tells Cargo that we depend on a crate called `hello_utils` which is found
-in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in).
-
-And that’s it! The next `cargo build` will automatically build `hello_utils` and
-all of its own dependencies, and others can also start using the crate as well.
-However, crates that use dependencies specified with only a path are not
-permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we
-would need to publish a version of `hello_utils` to [crates.io](https://crates.io)
-and specify its version in the dependencies line as well:
-
-```toml
-[dependencies]
-hello_utils = { path = "hello_utils", version = "0.1.0" }
-```
-
-# Overriding dependencies
-
-There are a number of methods in Cargo to support overriding dependencies and
-otherwise controlling the dependency graph. These options are typically, though,
-only available at the workspace level and aren't propagated through
-dependencies. In other words, "applications" have the ability to override
-dependencies but "libraries" do not.
-
-The desire to override a dependency or otherwise alter some dependencies can
-arise through a number of scenarios. Most of them, however, boil down to the
-ability to work with a crate before it's been published to crates.io. For
-example:
-
-* A crate you're working on is also used in a much larger application you're
- working on, and you'd like to test a bug fix to the library inside of the
- larger application.
-* An upstream crate you don't work on has a new feature or a bug fix on the
- master branch of its git repository which you'd like to test out.
-* You're about to publish a new major version of your crate, but you'd like to
- do integration testing across an entire project to ensure the new major
- version works.
-* You've submitted a fix to an upstream crate for a bug you found, but you'd
- like to immediately have your application start depending on the fixed version
- of the crate to avoid blocking on the bug fix getting merged.
-
-These scenarios are currently all solved with the [`[patch]` manifest
-section][patch-section]. (Note that the `[patch]` feature will first become
-available in Rust 1.21, set to be released on 2017-10-12.) Historically some of
-these scenarios have been solved with [the `[replace]` section][replace-section],
-but we'll document the `[patch]` section here.
-
-[patch-section]: manifest.html#the-patch-section
-[replace-section]: manifest.html#the-replace-section
-
-### Testing a bugfix
-
-Let's say you're working with the [`uuid`] crate but while you're working on it
-you discover a bug. You are, however, quite enterprising so you decide to also
-try out to fix the bug! Originally your manifest will look like:
-
-[`uuid`](https://crates.io/crates/uuid)
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0"
-```
-
-First thing we'll do is to clone the [`uuid` repository][uuid-repository]
-locally via:
-
-```shell
-$ git clone https://github.com/rust-lang-nursery/uuid
-```
-
-Next we'll edit the manifest of `my-library` to contain:
-
-```toml
-[patch.crates-io]
-uuid = { path = "../path/to/uuid" }
-```
-
-Here we declare that we're *patching* the source `crates-io` with a new
-dependency. This will effectively add the local checked out version of `uuid` to
-the crates.io registry for our local project.
-
-Next up we need to ensure that our lock file is updated to use this new version
-of `uuid` so our project uses the locally checked out copy instead of one from
-crates.io. The way `[patch]` works is that it'll load the dependency at
-`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid`
-it'll *also* return the local version.
-
-This means that the version number of the local checkout is significant and will
-affect whether the patch is used. Our manifest declared `uuid = "1.0"` which
-means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution
-algorithm also means that we'll resolve to the maximum version within that
-range. Typically this doesn't matter as the version of the git repository will
-already be greater or match the maximum version published on crates.io, but it's
-important to keep this in mind!
-
-In any case, typically all you need to do now is:
-
-```shell
-$ cargo build
- Compiling uuid v1.0.0 (file://.../uuid)
- Compiling my-library v0.1.0 (file://.../my-library)
- Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
-```
-
-And that's it! You're now building with the local version of `uuid` (note the
-`file://` in the build output). If you don't see the `file://` version getting
-built then you may need to run `cargo update -p uuid --precise $version` where
-`$version` is the version of the locally checked out copy of `uuid`.
-
-Once you've fixed the bug you originally found the next thing you'll want to do
-is to likely submit that as a pull request to the `uuid` crate itself. Once
-you've done this then you can also update the `[patch]` section. The listing
-inside of `[patch]` is just like the `[dependencies]` section, so once your pull
-request is merged you could change your `path` dependency to:
-
-```toml
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-[uuid-repository]: https://github.com/rust-lang-nursery/uuid
-
-### Working with an unpublished minor version
-
-Let's now shift gears a bit from bug fixes to adding features. While working on
-`my-library` you discover that a whole new feature is needed in the `uuid`
-crate. You've implemented this feature, tested it locally above with `[patch]`,
-and submitted a pull request. Let's go over how you continue to use and test it
-before it's actually published.
-
-Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but
-since then the master branch of the git repository has updated to `1.0.1`. This
-branch includes your new feature you submitted previously. To use this
-repository we'll edit our `Cargo.toml` to look like
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0.1"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Note that our local dependency on `uuid` has been updated to `1.0.1` as it's
-what we'll actually require once the crate is published. This version doesn't
-exist on crates.io, though, so we provide it with the `[patch]` section of the
-manifest.
-
-Now when our library is built it'll fetch `uuid` from the git repository and
-resolve to 1.0.1 inside the repository instead of trying to download a version
-from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can
-be deleted.
-
-It's also worth nothing that `[patch]` applies *transitively*. Let's say you use
-`my-library` in a larger project, such as:
-
-```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Remember that `[patch]` is only applicable at the *top level* so we consumers of
-`my-library` have to repeat the `[patch]` section if necessary. Here, though,
-the new `uuid` crate applies to *both* our dependency on `uuid` and the
-`my-library -> uuid` dependency. The `uuid` crate will be resolved to one
-version for this entire crate graph, 1.0.1, and it'll be pulled from the git
-repository.
-
-### Prepublishing a breaking change
-
-As a final scenario, let's take a look at working with a new major version of a
-crate, typically accompanied with breaking changes. Sticking with our previous
-crates, this means that we're going to be creating version 2.0.0 of the `uuid`
-crate. After we've submitted all changes upstream we can update our manifest for
-`my-library` to look like:
-
-```toml
-[dependencies]
-uuid = "2.0"
-
-[patch.crates-io]
-uuid = { git = "https://github.com/rust-lang-nursery/uuid", branch = "2.0.0" }
-```
-
-And that's it! Like with the previous example the 2.0.0 version doesn't actually
-exist on crates.io but we can still put it in through a git dependency through
-the usage of the `[patch]` section. As a thought exercise let's take another
-look at the `my-binary` manifest from above again as well:
-
-```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid', version = '2.0.0' }
-```
-
-Note that this will actually resolve to two versions of the `uuid` crate. The
-`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but
-the `my-library` crate will use the 2.0.0 version of `uuid`. This will allow you
-to gradually roll out breaking changes to a crate through a dependency graph
-without being force to update everything all at once.
-
-### Overriding with local dependencies
-
-Sometimes you're only temporarily working on a crate and you don't want to have
-to modify `Cargo.toml` like with the `[patch]` section above. For this use
-case Cargo offers a much more limited version of overrides called **path
-overrides**.
-
-Path overrides are specified through `.cargo/config` instead of `Cargo.toml`,
-and you can find [more documentation about this configuration][config-docs].
-Inside of `.cargo/config` you'll specify a key called `paths`:
-
-[config-docs]: config.html
-
-```toml
-paths = ["/path/to/uuid"]
-```
-
-This array should be filled with directories that contain a `Cargo.toml`. In
-this instance, we’re just adding `uuid`, so it will be the only one that’s
-overridden. This path can be either absolute or relative to the directory that
-contains the `.cargo` folder.
-
-Path overrides are more restricted than the `[patch]` section, however, in
-that they cannot change the structure of the dependency graph. When a
-path replacement is used then the previous set of dependencies
-must all match exactly to the new `Cargo.toml` specification. For example this
-means that path overrides cannot be used to test out adding a dependency to a
-crate, instead `[patch]` must be used in that situation. As a result usage of a
-path override is typically isolated to quick bug fixes rather than larger
-changes.
-
-Note: using a local configuration to override paths will only work for crates
-that have been published to [crates.io]. You cannot use this feature to tell
-Cargo how to find local unpublished crates.
-
-# Platform specific dependencies
-
-
-Platform-specific dependencies take the same format, but are listed under a
-`target` section. Normally Rust-like `#[cfg]` syntax will be used to define
-these sections:
-
-```toml
-[target.'cfg(windows)'.dependencies]
-winhttp = "0.4.0"
-
-[target.'cfg(unix)'.dependencies]
-openssl = "1.0.1"
-
-[target.'cfg(target_arch = "x86")'.dependencies]
-native = { path = "native/i686" }
-
-[target.'cfg(target_arch = "x86_64")'.dependencies]
-native = { path = "native/x86_64" }
-```
-
-Like with Rust, the syntax here supports the `not`, `any`, and `all` operators
-to combine various cfg name/value pairs. Note that the `cfg` syntax has only
-been available since Cargo 0.9.0 (Rust 1.8.0).
-
-In addition to `#[cfg]` syntax, Cargo also supports listing out the full target
-the dependencies would apply to:
-
-```toml
-[target.x86_64-pc-windows-gnu.dependencies]
-winhttp = "0.4.0"
-
-[target.i686-unknown-linux-gnu.dependencies]
-openssl = "1.0.1"
-```
-
-If you’re using a custom target specification, quote the full path and file
-name:
-
-```toml
-[target."x86_64/windows.json".dependencies]
-winhttp = "0.4.0"
-
-[target."i686/linux.json".dependencies]
-openssl = "1.0.1"
-native = { path = "native/i686" }
-
-[target."x86_64/linux.json".dependencies]
-openssl = "1.0.1"
-native = { path = "native/x86_64" }
-```
-
-# Development dependencies
-
-You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format
-is equivalent to `[dependencies]`:
-
-```toml
-[dev-dependencies]
-tempdir = "0.3"
-```
-
-Dev-dependencies are not used when compiling
-a package for building, but are used for compiling tests, examples, and
-benchmarks.
-
-These dependencies are *not* propagated to other packages which depend on this
-package.
-
-You can also have target-specific development dependencies by using
-`dev-dependencies` in the target section header instead of `dependencies`. For
-example:
-
-```toml
-[target.'cfg(unix)'.dev-dependencies]
-mio = "0.0.1"
-```
-
-[crates.io]: https://crates.io/
-
-# Build dependencies
-
-You can depend on other Cargo-based crates for use in your build scripts.
-Dependencies are declared through the `build-dependencies` section of the
-manifest:
-
-```toml
-[build-dependencies]
-gcc = "0.3"
-```
-
-The build script **does not** have access to the dependencies listed
-in the `dependencies` or `dev-dependencies` section. Build
-dependencies will likewise not be available to the package itself
-unless listed under the `dependencies` section as well. A package
-itself and its build script are built separately, so their
-dependencies need not coincide. Cargo is kept simpler and cleaner by
-using independent dependencies for independent purposes.
-
-# Choosing features
-
-If a package you depend on offers conditional features, you can
-specify which to use:
-
-```toml
-[dependencies.awesome]
-version = "1.3.5"
-default-features = false # do not include the default features, and optionally
- # cherry-pick individual features
-features = ["secure-password", "civet"]
-```
-
-More information about features can be found in the
-[manifest documentation](manifest.html#the-features-section).
--- /dev/null
+# Summary
+
+[Introduction](index.md)
+
+* [Getting Started](getting-started/index.md)
+ * [Installation](getting-started/installation.md)
+ * [First Steps with Cargo](getting-started/first-steps.md)
+
+* [Cargo Guide](guide/index.md)
+ * [Why Cargo Exists](guide/why-cargo-exists.md)
+ * [Creating a New Project](guide/creating-a-new-project.md)
+ * [Working on an Existing Project](guide/working-on-an-existing-project.md)
+ * [Dependencies](guide/dependencies.md)
+ * [Project Layout](guide/project-layout.md)
+ * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md)
+ * [Tests](guide/tests.md)
+ * [Continuous Integration](guide/continuous-integration.md)
+
+* [Cargo Reference](reference/index.md)
+ * [Specifying Dependencies](reference/specifying-dependencies.md)
+ * [The Manifest Format](reference/manifest.md)
+ * [Configuration](reference/config.md)
+ * [Environment Variables](reference/environment-variables.md)
+ * [Build Scripts](reference/build-scripts.md)
+ * [Publishing on crates.io](reference/publishing.md)
+ * [Package ID Specifications](reference/pkgid-spec.md)
+ * [Source Replacement](reference/source-replacement.md)
+ * [External Tools](reference/external-tools.md)
+
+* [FAQ](faq.md)
--- /dev/null
+## Frequently Asked Questions
+
+### Is the plan to use GitHub as a package repository?
+
+No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with
+npmjs.org and rubygems.org.
+
+We plan to support git repositories as a source of packages forever,
+because they can be used for early development and temporary patches,
+even when people use the registry as the primary source of packages.
+
+### Why build crates.io rather than use GitHub as a registry?
+
+We think that it’s very important to support multiple ways to download
+packages, including downloading from GitHub and copying packages into
+your project itself.
+
+That said, we think that [crates.io] offers a number of important benefits, and
+will likely become the primary way that people download packages in Cargo.
+
+For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a
+central registry model as well as a Git-based model, and most packages
+are downloaded through the registry in those ecosystems, with an
+important minority of packages making use of git-based packages.
+
+[1]: https://www.npmjs.org
+[2]: https://bundler.io
+
+Some of the advantages that make a central registry popular in other
+languages include:
+
+* **Discoverability**. A central registry provides an easy place to look
+ for existing packages. Combined with tagging, this also makes it
+ possible for a registry to provide ecosystem-wide information, such as a
+ list of the most popular or most-depended-on packages.
+* **Speed**. A central registry makes it possible to easily fetch just
+ the metadata for packages quickly and efficiently, and then to
+ efficiently download just the published package, and not other bloat
+ that happens to exist in the repository. This adds up to a significant
+ improvement in the speed of dependency resolution and fetching. As
+ dependency graphs scale up, downloading all of the git repositories bogs
+ down fast. Also remember that not everybody has a high-speed,
+ low-latency Internet connection.
+
+### Will Cargo work with C code (or other languages)?
+
+Yes!
+
+Cargo handles compiling Rust code, but we know that many Rust projects
+link against C code. We also know that there are decades of tooling
+built up around compiling languages other than Rust.
+
+Our solution: Cargo allows a package to [specify a script](reference/build-scripts.html)
+(written in Rust) to run before invoking `rustc`. Rust is leveraged to
+implement platform-specific configuration and refactor out common build
+functionality among packages.
+
+### Can Cargo be used inside of `make` (or `ninja`, or ...)
+
+Indeed. While we intend Cargo to be useful as a standalone way to
+compile Rust projects at the top-level, we know that some people will
+want to invoke Cargo from other build tools.
+
+We have designed Cargo to work well in those contexts, paying attention
+to things like error codes and machine-readable output modes. We still
+have some work to do on those fronts, but using Cargo in the context of
+conventional scripts is something we designed for from the beginning and
+will continue to prioritize.
+
+### Does Cargo handle multi-platform projects or cross-compilation?
+
+Rust itself provides facilities for configuring sections of code based
+on the platform. Cargo also supports [platform-specific
+dependencies][target-deps], and we plan to support more per-platform
+configuration in `Cargo.toml` in the future.
+
+[target-deps]: reference/specifying-dependencies.html#platform-specific-dependencies
+
+In the longer-term, we’re looking at ways to conveniently cross-compile
+projects using Cargo.
+
+### Does Cargo support environments, like `production` or `test`?
+
+We support environments through the use of [profiles][profile] to support:
+
+[profile]: reference/manifest.html#the-profile-sections
+
+* environment-specific flags (like `-g --opt-level=0` for development
+ and `--opt-level=3` for production).
+* environment-specific dependencies (like `hamcrest` for test assertions).
+* environment-specific `#[cfg]`
+* a `cargo test` command
+
+### Does Cargo work on Windows?
+
+Yes!
+
+All commits to Cargo are required to pass the local test suite on Windows.
+If, however, you find a Windows issue, we consider it a bug, so [please file an
+issue][3].
+
+[3]: https://github.com/rust-lang/cargo/issues
+
+### Why do binaries have `Cargo.lock` in version control, but not libraries?
+
+The purpose of a `Cargo.lock` is to describe the state of the world at the time
+of a successful build. It is then used to provide deterministic builds across
+whatever machine is building the project by ensuring that the exact same
+dependencies are being compiled.
+
+This property is most desirable from applications and projects which are at the
+very end of the dependency chain (binaries). As a result, it is recommended that
+all binaries check in their `Cargo.lock`.
+
+For libraries the situation is somewhat different. A library is not only used by
+the library developers, but also any downstream consumers of the library. Users
+dependent on the library will not inspect the library’s `Cargo.lock` (even if it
+exists). This is precisely because a library should **not** be deterministically
+recompiled for all users of the library.
+
+If a library ends up being used transitively by several dependencies, it’s
+likely that just a single copy of the library is desired (based on semver
+compatibility). If all libraries were to check in their `Cargo.lock`, then
+multiple copies of the library would be used, and perhaps even a version
+conflict.
+
+In other words, libraries specify semver requirements for their dependencies but
+cannot see the full picture. Only end products like binaries have a full
+picture to decide what versions of dependencies should be used.
+
+### Can libraries use `*` as a version for their dependencies?
+
+**As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries)
+with wildcard dependency constraints.**
+
+While libraries _can_, strictly speaking, they should not. A version requirement
+of `*` says “This will work with every version ever,” which is never going
+to be true. Libraries should always specify the range that they do work with,
+even if it’s something as general as “every 1.x.y version.”
+
+### Why `Cargo.toml`?
+
+As one of the most frequent interactions with Cargo, the question of why the
+configuration file is named `Cargo.toml` arises from time to time. The leading
+capital-`C` was chosen to ensure that the manifest was grouped with other
+similar configuration files in directory listings. Sorting files often puts
+capital letters before lowercase letters, ensuring files like `Makefile` and
+`Cargo.toml` are placed together. The trailing `.toml` was chosen to emphasize
+the fact that the file is in the [TOML configuration
+format](https://github.com/toml-lang/toml).
+
+Cargo does not allow other names such as `cargo.toml` or `Cargofile` to
+emphasize the ease of how a Cargo repository can be identified. An option of
+many possible names has historically led to confusion where one case was handled
+but others were accidentally forgotten.
+
+[crates.io]: https://crates.io/
+
+### How can Cargo work offline?
+
+Cargo is often used in situations with limited or no network access such as
+airplanes, CI environments, or embedded in large production deployments. Users
+are often surprised when Cargo attempts to fetch resources from the network, and
+hence the request for Cargo to work offline comes up frequently.
+
+Cargo, at its heart, will not attempt to access the network unless told to do
+so. That is, if no crates comes from crates.io, a git repository, or some other
+network location, Cargo will never attempt to make a network connection. As a
+result, if Cargo attempts to touch the network, then it's because it needs to
+fetch a required resource.
+
+Cargo is also quite aggressive about caching information to minimize the amount
+of network activity. It will guarantee, for example, that if `cargo build` (or
+an equivalent) is run to completion then the next `cargo build` is guaranteed to
+not touch the network so long as `Cargo.toml` has not been modified in the
+meantime. This avoidance of the network boils down to a `Cargo.lock` existing
+and a populated cache of the crates reflected in the lock file. If either of
+these components are missing, then they're required for the build to succeed and
+must be fetched remotely.
+
+As of Rust 1.11.0 Cargo understands a new flag, `--frozen`, which is an
+assertion that it shouldn't touch the network. When passed, Cargo will
+immediately return an error if it would otherwise attempt a network request.
+The error should include contextual information about why the network request is
+being made in the first place to help debug as well. Note that this flag *does
+not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch
+the network as a previous command has been run to ensure that network activity
+shouldn't be necessary.
+
+For more information about vendoring, see documentation on [source
+replacement][replace].
+
+[replace]: reference/source-replacement.html
--- /dev/null
+## First Steps with Cargo
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We’re passing `--bin` because we’re making a binary program: if we
+were making a library, we’d leave it off.
+
+Let’s check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+ └── main.rs
+
+1 directory, 2 files
+```
+
+This is all we need to get started. First, let’s check out `Cargo.toml`:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project.
+
+Here’s what’s in `src/main.rs`:
+
+```rust
+fn main() {
+ println!("Hello, world!");
+}
+```
+
+Cargo generated a “hello world” for us. Let’s compile it:
+
+```shell
+$ cargo build
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+And then run it:
+
+```shell
+$ ./target/debug/hello_world
+Hello, world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step:
+
+```shell
+$ cargo run
+ Fresh hello_world v0.1.0 (file:///path/to/project/hello_world)
+ Running `target/hello_world`
+Hello, world!
+```
+
+### Going further
+
+For more details on using Cargo, check out the [Cargo Guide](guide/index.html)
--- /dev/null
+## Getting Started
+
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+
+* [Installation](getting-started/installation.html)
+* [First steps with Cargo](getting-started/first-steps.html)
--- /dev/null
+## Installation
+
+### Install Stable Rust and Cargo
+
+The easiest way to get Cargo is to get the current stable release of [Rust] by
+using the `rustup` script:
+
+```shell
+$ curl -sSf https://static.rust-lang.org/rustup.sh | sh
+```
+
+After this, you can use the `rustup` command to also install `beta` or `nightly`
+channels for Rust and Cargo.
+
+### Install Nightly Cargo
+
+To install just Cargo, the current recommended installation method is through
+the official nightly builds. Note that Cargo will also require that [Rust] is
+already installed on the system.
+
+| Platform | 64-bit | 32-bit |
+|------------------|-------------------|-------------------|
+| Linux binaries | [tar.gz][linux64] | [tar.gz][linux32] |
+| MacOS binaries | [tar.gz][mac64] | [tar.gz][mac32] |
+| Windows binaries | [tar.gz][win64] | [tar.gz][win32] |
+
+### Build and Install Cargo from Source
+
+Alternatively, you can [build Cargo from source][compiling-from-source].
+
+[rust]: https://www.rust-lang.org/
+[linux64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-unknown-linux-gnu.tar.gz
+[linux32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-unknown-linux-gnu.tar.gz
+[mac64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-apple-darwin.tar.gz
+[mac32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-apple-darwin.tar.gz
+[win64]: https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz
+[win32]: https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz
+[compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source
--- /dev/null
+## Cargo.toml vs Cargo.lock
+
+`Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
+about them, here’s a summary:
+
+* `Cargo.toml` is about describing your dependencies in a broad sense, and is
+ written by you.
+* `Cargo.lock` contains exact information about your dependencies. It is
+ maintained by Cargo and should not be manually edited.
+
+If you’re building a library that other projects will depend on, put
+`Cargo.lock` in your `.gitignore`. If you’re building an executable like a
+command-line tool or an application, check `Cargo.lock` into `git`. If you're
+curious about why that is, see ["Why do binaries have `Cargo.lock` in version
+control, but not libraries?" in the
+FAQ](faq.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
+
+Let’s dig in a little bit more.
+
+`Cargo.toml` is a **manifest** file in which we can specify a bunch of
+different metadata about our project. For example, we can say that we depend
+on another project:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+
+[dependencies]
+rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
+```
+
+This project has a single dependency, on the `rand` library. We’ve stated in
+this case that we’re relying on a particular Git repository that lives on
+GitHub. Since we haven’t specified any other information, Cargo assumes that
+we intend to use the latest commit on the `master` branch to build our project.
+
+Sound good? Well, there’s one problem: If you build this project today, and
+then you send a copy to me, and I build this project tomorrow, something bad
+could happen. There could be more commits to `rand` in the meantime, and my
+build would include new commits while yours would not. Therefore, we would
+get different builds. This would be bad because we want reproducible builds.
+
+We could fix this problem by putting a `rev` line in our `Cargo.toml`:
+
+```toml
+[dependencies]
+rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" }
+```
+
+Now our builds will be the same. But there’s a big drawback: now we have to
+manually think about SHA-1s every time we want to update our library. This is
+both tedious and error prone.
+
+Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
+keep track of the exact revisions: Cargo will do it for us. When we have a
+manifest like this:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+
+[dependencies]
+rand = { git = "https://github.com/rust-lang-nursery/rand.git" }
+```
+
+Cargo will take the latest commit and write that information out into our
+`Cargo.lock` when we build for the first time. That file will look like this:
+
+```toml
+[[package]]
+name = "hello_world"
+version = "0.1.0"
+dependencies = [
+ "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)",
+]
+
+[[package]]
+name = "rand"
+version = "0.1.0"
+source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9"
+```
+
+You can see that there’s a lot more information here, including the exact
+revision we used to build. Now when you give your project to someone else,
+they’ll use the exact same SHA, even though we didn’t specify it in our
+`Cargo.toml`.
+
+When we’re ready to opt in to a new version of the library, Cargo can
+re-calculate the dependencies and update things for us:
+
+```shell
+$ cargo update # updates all dependencies
+$ cargo update -p rand # updates just “rand”
+```
+
+This will write out a new `Cargo.lock` with the new version information. Note
+that the argument to `cargo update` is actually a
+[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
+specification.
--- /dev/null
+## Continuous Integration
+
+### Travis CI
+
+To test your project on Travis CI, here is a sample `.travis.yml` file:
+
+```yaml
+language: rust
+rust:
+ - stable
+ - beta
+ - nightly
+matrix:
+ allow_failures:
+ - rust: nightly
+```
+
+This will test all three release channels, but any breakage in nightly
+will not fail your overall build. Please see the [Travis CI Rust
+documentation](https://docs.travis-ci.com/user/languages/rust/) for more
+information.
--- /dev/null
+## Creating a New Project
+
+To start a new project with Cargo, use `cargo new`:
+
+```shell
+$ cargo new hello_world --bin
+```
+
+We’re passing `--bin` because we’re making a binary program: if we
+were making a library, we’d leave it off. This also initializes a new `git`
+repository by default. If you don't want it to do that, pass `--vcs none`.
+
+Let’s check out what Cargo has generated for us:
+
+```shell
+$ cd hello_world
+$ tree .
+.
+├── Cargo.toml
+└── src
+ └── main.rs
+
+1 directory, 2 files
+```
+
+If we had just used `cargo new hello_world` without the `--bin` flag, then
+we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all
+we need to get started. First, let’s check out `Cargo.toml`:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+```
+
+This is called a **manifest**, and it contains all of the metadata that Cargo
+needs to compile your project.
+
+Here’s what’s in `src/main.rs`:
+
+```rust
+fn main() {
+ println!("Hello, world!");
+}
+```
+
+Cargo generated a “hello world” for us. Let’s compile it:
+
+```shell
+$ cargo build
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+And then run it:
+
+```shell
+$ ./target/debug/hello_world
+Hello, world!
+```
+
+We can also use `cargo run` to compile and then run it, all in one step (You
+won't see the `Compiling` line if you have not made any changes since you last
+compiled):
+
+```shell
+$ cargo run
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+ Running `target/debug/hello_world`
+Hello, world!
+```
+
+You’ll now notice a new file, `Cargo.lock`. It contains information about our
+dependencies. Since we don’t have any yet, it’s not very interesting.
+
+Once you’re ready for release, you can use `cargo build --release` to compile
+your files with optimizations turned on:
+
+```shell
+$ cargo build --release
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+`cargo build --release` puts the resulting binary in `target/release` instead of
+`target/debug`.
+
+Compiling in debug mode is the default for development-- compilation time is
+shorter since the compiler doesn't do optimizations, but the code will run
+slower. Release mode takes longer to compile, but the code will run faster.
--- /dev/null
+## Dependencies
+
+[crates.io] is the Rust community's central package registry that serves as a
+location to discover and download packages. `cargo` is configured to use it by
+default to find requested packages.
+
+To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.
+
+[crates.io]: https://crates.io/
+
+### Adding a dependency
+
+If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
+then list the crate name and version that you would like to use. This example
+adds a dependency of the `time` crate:
+
+```toml
+[dependencies]
+time = "0.1.12"
+```
+
+The version string is a [semver] version requirement. The [specifying
+dependencies](reference/specifying-dependencies.html) docs have more information about
+the options you have here.
+
+[semver]: https://github.com/steveklabnik/semver#requirements
+
+If we also wanted to add a dependency on the `regex` crate, we would not need
+to add `[dependencies]` for each crate listed. Here's what your whole
+`Cargo.toml` file would look like with dependencies on the `time` and `regex`
+crates:
+
+```toml
+[package]
+name = "hello_world"
+version = "0.1.0"
+authors = ["Your Name <you@example.com>"]
+
+[dependencies]
+time = "0.1.12"
+regex = "0.1.41"
+```
+
+Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
+their dependencies, compile them all, and update the `Cargo.lock`:
+
+```shell
+$ cargo build
+ Updating registry `https://github.com/rust-lang/crates.io-index`
+ Downloading memchr v0.1.5
+ Downloading libc v0.1.10
+ Downloading regex-syntax v0.2.1
+ Downloading memchr v0.1.5
+ Downloading aho-corasick v0.3.0
+ Downloading regex v0.1.41
+ Compiling memchr v0.1.5
+ Compiling libc v0.1.10
+ Compiling regex-syntax v0.2.1
+ Compiling memchr v0.1.5
+ Compiling aho-corasick v0.3.0
+ Compiling regex v0.1.41
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+```
+
+Our `Cargo.lock` contains the exact information about which revision of all of
+these dependencies we used.
+
+Now, if `regex` gets updated, we will still build with the same revision until
+we choose to `cargo update`.
+
+You can now use the `regex` library using `extern crate` in `main.rs`.
+
+```
+extern crate regex;
+
+use regex::Regex;
+
+fn main() {
+ let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+ println!("Did our date match? {}", re.is_match("2014-01-01"));
+}
+```
+
+Running it will show:
+
+```shell
+$ cargo run
+ Running `target/hello_world`
+Did our date match? true
+```
--- /dev/null
+## Cargo Guide
+
+This guide will give you all that you need to know about how to use Cargo to
+develop Rust projects.
+
+* [Why Cargo Exists](guide/why-cargo-exists.html)
+* [Creating a New Project](guide/creating-a-new-project.html)
+* [Working on an Existing Cargo Project](guide/working-on-an-existing-project.html)
+* [Dependencies](guide/dependencies.html)
+* [Project Layout](guide/project-layout.html)
+* [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.html)
+* [Tests](guide/tests.html)
+* [Continuous Integration](guide/continuous-integration.html)
--- /dev/null
+## Project Layout
+
+Cargo uses conventions for file placement to make it easy to dive into a new
+Cargo project:
+
+```shell
+.
+├── Cargo.lock
+├── Cargo.toml
+├── benches
+│ └── large-input.rs
+├── examples
+│ └── simple.rs
+├── src
+│ ├── bin
+│ │ └── another_executable.rs
+│ ├── lib.rs
+│ └── main.rs
+└── tests
+ └── some-integration-tests.rs
+```
+
+* `Cargo.toml` and `Cargo.lock` are stored in the root of your project (*package
+ root*).
+* Source code goes in the `src` directory.
+* The default library file is `src/lib.rs`.
+* The default executable file is `src/main.rs`.
+* Other executables can be placed in `src/bin/*.rs`.
+* Integration tests go in the `tests` directory (unit tests go in each file
+ they're testing).
+* Examples go in the `examples` directory.
+* Benchmarks go in the `benches` directory.
+
+These are explained in more detail in the [manifest
+description](reference/manifest.html#the-project-layout).
--- /dev/null
+## Tests
+
+Cargo can run your tests with the `cargo test` command. Cargo looks for tests
+to run in two places: in each of your `src` files and any tests in `tests/`.
+Tests in your `src` files should be unit tests, and tests in `tests/` should be
+integration-style tests. As such, you’ll need to import your crates into
+the files in `tests`.
+
+Here's an example of running `cargo test` in our project, which currently has
+no tests:
+
+```shell
+$ cargo test
+ Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e)
+ Compiling hello_world v0.1.0 (file:///path/to/project/hello_world)
+ Running target/test/hello_world-9c2b65bbb79eabce
+
+running 0 tests
+
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
+```
+
+If our project had tests, we would see more output with the correct number of
+tests.
+
+You can also run a specific test by passing a filter:
+
+```shell
+$ cargo test foo
+```
+
+This will run any test with `foo` in its name.
+
+`cargo test` runs additional checks as well. For example, it will compile any
+examples you’ve included and will also test the examples in your
+documentation. Please see the [testing guide][testing] in the Rust
+documentation for more details.
+
+[testing]: https://doc.rust-lang.org/book/testing.html
--- /dev/null
+## Why Cargo Exists
+
+Cargo is a tool that allows Rust projects to declare their various
+dependencies and ensure that you’ll always get a repeatable build.
+
+To accomplish this goal, Cargo does four things:
+
+* Introduces two metadata files with various bits of project information.
+* Fetches and builds your project’s dependencies.
+* Invokes `rustc` or another build tool with the correct parameters to build
+ your project.
+* Introduces conventions to make working with Rust projects easier.
--- /dev/null
+## Working on an Existing Cargo Project
+
+If you download an existing project that uses Cargo, it’s really easy
+to get going.
+
+First, get the project from somewhere. In this example, we’ll use `rand`
+cloned from its repository on GitHub:
+
+```shell
+$ git clone https://github.com/rust-lang-nursery/rand.git
+$ cd rand
+```
+
+To build, use `cargo build`:
+
+```shell
+$ cargo build
+ Compiling rand v0.1.0 (file:///path/to/project/rand)
+```
+
+This will fetch all of the dependencies and then build them, along with the
+project.
--- /dev/null
+# The Cargo Book
+
+
+
+Cargo is the [Rust] *package manager*. Cargo downloads your Rust project’s
+dependencies, compiles your project, makes packages, and upload them to
+[crates.io], the Rust community’s *package registry*.
+
+
+### Sections
+
+**[Getting Started](getting-started/index.html)**
+
+To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+
+**[Cargo Guide](guide/index.html)**
+
+The guide will give you all you need to know about how to use Cargo to develop
+Rust projects.
+
+**[Cargo Reference](reference/index.html)**
+
+The reference covers the details of various areas of Cargo.
+
+**[Frequently Asked Questions](faq.html)**
+
+[rust]: https://www.rust-lang.org/
+[crates.io]: https://crates.io/
--- /dev/null
+## Build Scripts
+
+Some packages need to compile third-party non-Rust code, for example C
+libraries. Other packages need to link to C libraries which can either be
+located on the system or possibly need to be built from source. Others still
+need facilities for functionality such as code generation before building (think
+parser generators).
+
+Cargo does not aim to replace other tools that are well-optimized for
+these tasks, but it does integrate with them with the `build` configuration
+option.
+
+```toml
+[package]
+# ...
+build = "build.rs"
+```
+
+The Rust file designated by the `build` command (relative to the package root)
+will be compiled and invoked before anything else is compiled in the package,
+allowing your Rust code to depend on the built or generated artifacts.
+By default Cargo looks up for `"build.rs"` file in a package root (even if you
+do not specify a value for `build`). Use `build = "custom_build_name.rs"` to specify
+a custom build name or `build = false` to disable automatic detection of the build script.
+
+Some example use cases of the build command are:
+
+* Building a bundled C library.
+* Finding a C library on the host system.
+* Generating a Rust module from a specification.
+* Performing any platform-specific configuration needed for the crate.
+
+Each of these use cases will be detailed in full below to give examples of how
+the build command works.
+
+### Inputs to the Build Script
+
+When the build script is run, there are a number of inputs to the build script,
+all passed in the form of [environment variables][env].
+
+In addition to environment variables, the build script’s current directory is
+the source directory of the build script’s package.
+
+[env]: reference/environment-variables.html
+
+### Outputs of the Build Script
+
+All the lines printed to stdout by a build script are written to a file like
+`target/debug/build/<pkg>/output` (the precise location may depend on your
+configuration). Any line that starts with `cargo:` is interpreted directly by
+Cargo. This line must be of the form `cargo:key=value`, like the examples below:
+
+```shell
+# specially recognized by Cargo
+cargo:rustc-link-lib=static=foo
+cargo:rustc-link-search=native=/path/to/foo
+cargo:rustc-cfg=foo
+cargo:rustc-env=FOO=bar
+# arbitrary user-defined metadata
+cargo:root=/path/to/foo
+cargo:libdir=/path/to/foo/lib
+cargo:include=/path/to/foo/include
+```
+
+On the other hand, lines printed to stderr are written to a file like
+`target/debug/build/<pkg>/stderr` but are not interpreted by cargo.
+
+There are a few special keys that Cargo recognizes, some affecting how the
+crate is built:
+
+* `rustc-link-lib=[KIND=]NAME` indicates that the specified value is a library
+ name and should be passed to the compiler as a `-l` flag. The optional `KIND`
+ can be one of `static`, `dylib` (the default), or `framework`, see
+ `rustc --help` for more details.
+* `rustc-link-search=[KIND=]PATH` indicates the specified value is a library
+ search path and should be passed to the compiler as a `-L` flag. The optional
+ `KIND` can be one of `dependency`, `crate`, `native`, `framework` or `all`
+ (the default), see `rustc --help` for more details.
+* `rustc-flags=FLAGS` is a set of flags passed to the compiler, only `-l` and
+ `-L` flags are supported.
+* `rustc-cfg=FEATURE` indicates that the specified feature will be passed as a
+ `--cfg` flag to the compiler. This is often useful for performing compile-time
+ detection of various features.
+* `rustc-env=VAR=VALUE` indicates that the specified environment variable
+ will be added to the environment which the compiler is run within.
+ The value can be then retrieved by the `env!` macro in the compiled crate.
+ This is useful for embedding additional metadata in crate's code,
+ such as the hash of Git HEAD or the unique identifier of a continuous
+ integration server.
+* `rerun-if-changed=PATH` is a path to a file or directory which indicates that
+ the build script should be re-run if it changes (detected by a more-recent
+ last-modified timestamp on the file). Normally build scripts are re-run if
+ any file inside the crate root changes, but this can be used to scope changes
+ to just a small set of files. (If this path points to a directory the entire
+ directory will not be traversed for changes -- only changes to the timestamp
+ of the directory itself (which corresponds to some types of changes within the
+ directory, depending on platform) will trigger a rebuild. To request a re-run
+ on any changes within an entire directory, print a line for the directory and
+ another line for everything inside it, recursively.)
+ Note that if the build script itself (or one of its dependencies) changes,
+ then it's rebuilt and rerun unconditionally, so
+ `cargo:rerun-if-changed=build.rs` is almost always redundant (unless you
+ want to ignore changes in all other files except for `build.rs`).
+* `rerun-if-env-changed=VAR` is the name of an environment variable which
+ indicates that if the environment variable's value changes the build script
+ should be rerun. This basically behaves the same as `rerun-if-changed` except
+ that it works with environment variables instead. Note that the environment
+ variables here are intended for global environment variables like `CC` and
+ such, it's not necessary to use this for env vars like `TARGET` that Cargo
+ sets. Also note that if `rerun-if-env-changed` is printed out then Cargo will
+ *only* rerun the build script if those environment variables change or if
+ files printed out by `rerun-if-changed` change.
+
+* `warning=MESSAGE` is a message that will be printed to the main console after
+ a build script has finished running. Warnings are only shown for path
+ dependencies (that is, those you're working on locally), so for example
+ warnings printed out in crates.io crates are not emitted by default.
+
+Any other element is a user-defined metadata that will be passed to
+dependents. More information about this can be found in the [`links`][links]
+section.
+
+[links]: #the-links-manifest-key
+
+### Build Dependencies
+
+Build scripts are also allowed to have dependencies on other Cargo-based crates.
+Dependencies are declared through the `build-dependencies` section of the
+manifest.
+
+```toml
+[build-dependencies]
+foo = { git = "https://github.com/your-packages/foo" }
+```
+
+The build script **does not** have access to the dependencies listed in the
+`dependencies` or `dev-dependencies` section (they’re not built yet!). All build
+dependencies will also not be available to the package itself unless explicitly
+stated as so.
+
+### The `links` Manifest Key
+
+In addition to the manifest key `build`, Cargo also supports a `links` manifest
+key to declare the name of a native library that is being linked to:
+
+```toml
+[package]
+# ...
+links = "foo"
+build = "build.rs"
+```
+
+This manifest states that the package links to the `libfoo` native library, and
+it also has a build script for locating and/or building the library. Cargo
+requires that a `build` command is specified if a `links` entry is also
+specified.
+
+The purpose of this manifest key is to give Cargo an understanding about the set
+of native dependencies that a package has, as well as providing a principled
+system of passing metadata between package build scripts.
+
+Primarily, Cargo requires that there is at most one package per `links` value.
+In other words, it’s forbidden to have two packages link to the same native
+library. Note, however, that there are [conventions in place][star-sys] to
+alleviate this.
+
+[star-sys]: #-sys-packages
+
+As mentioned above in the output format, each build script can generate an
+arbitrary set of metadata in the form of key-value pairs. This metadata is
+passed to the build scripts of **dependent** packages. For example, if `libbar`
+depends on `libfoo`, then if `libfoo` generates `key=value` as part of its
+metadata, then the build script of `libbar` will have the environment variables
+`DEP_FOO_KEY=value`.
+
+Note that metadata is only passed to immediate dependents, not transitive
+dependents. The motivation for this metadata passing is outlined in the linking
+to system libraries case study below.
+
+### Overriding Build Scripts
+
+If a manifest contains a `links` key, then Cargo supports overriding the build
+script specified with a custom library. The purpose of this functionality is to
+prevent running the build script in question altogether and instead supply the
+metadata ahead of time.
+
+To override a build script, place the following configuration in any acceptable
+Cargo [configuration location](reference/config.html).
+
+```toml
+[target.x86_64-unknown-linux-gnu.foo]
+rustc-link-search = ["/path/to/foo"]
+rustc-link-lib = ["foo"]
+root = "/path/to/foo"
+key = "value"
+```
+
+This section states that for the target `x86_64-unknown-linux-gnu` the library
+named `foo` has the metadata specified. This metadata is the same as the
+metadata generated as if the build script had run, providing a number of
+key/value pairs where the `rustc-flags`, `rustc-link-search`, and
+`rustc-link-lib` keys are slightly special.
+
+With this configuration, if a package declares that it links to `foo` then the
+build script will **not** be compiled or run, and the metadata specified will
+instead be used.
+
+### Case study: Code generation
+
+Some Cargo packages need to have code generated just before they are compiled
+for various reasons. Here we’ll walk through a simple example which generates a
+library call as part of the build script.
+
+First, let’s take a look at the directory structure of this package:
+
+```shell
+.
+├── Cargo.toml
+├── build.rs
+└── src
+ └── main.rs
+
+1 directory, 3 files
+```
+
+Here we can see that we have a `build.rs` build script and our binary in
+`main.rs`. Next, let’s take a look at the manifest:
+
+```toml
+# Cargo.toml
+
+[package]
+name = "hello-from-generated-code"
+version = "0.1.0"
+authors = ["you@example.com"]
+build = "build.rs"
+```
+
+Here we can see we’ve got a build script specified which we’ll use to generate
+some code. Let’s see what’s inside the build script:
+
+```rust,no_run
+// build.rs
+
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::Path;
+
+fn main() {
+ let out_dir = env::var("OUT_DIR").unwrap();
+ let dest_path = Path::new(&out_dir).join("hello.rs");
+ let mut f = File::create(&dest_path).unwrap();
+
+ f.write_all(b"
+ pub fn message() -> &'static str {
+ \"Hello, World!\"
+ }
+ ").unwrap();
+}
+```
+
+There’s a couple of points of note here:
+
+* The script uses the `OUT_DIR` environment variable to discover where the
+ output files should be located. It can use the process’ current working
+ directory to find where the input files should be located, but in this case we
+ don’t have any input files.
+* This script is relatively simple as it just writes out a small generated file.
+ One could imagine that other more fanciful operations could take place such as
+ generating a Rust module from a C header file or another language definition,
+ for example.
+
+Next, let’s peek at the library itself:
+
+```rust,ignore
+// src/main.rs
+
+include!(concat!(env!("OUT_DIR"), "/hello.rs"));
+
+fn main() {
+ println!("{}", message());
+}
+```
+
+This is where the real magic happens. The library is using the rustc-defined
+`include!` macro in combination with the `concat!` and `env!` macros to include
+the generated file (`hello.rs`) into the crate’s compilation.
+
+Using the structure shown here, crates can include any number of generated files
+from the build script itself.
+
+### Case study: Building some native code
+
+Sometimes it’s necessary to build some native C or C++ code as part of a
+package. This is another excellent use case of leveraging the build script to
+build a native library before the Rust crate itself. As an example, we’ll create
+a Rust library which calls into C to print “Hello, World!”.
+
+Like above, let’s first take a look at the project layout:
+
+```shell
+.
+├── Cargo.toml
+├── build.rs
+└── src
+ ├── hello.c
+ └── main.rs
+
+1 directory, 4 files
+```
+
+Pretty similar to before! Next, the manifest:
+
+```toml
+# Cargo.toml
+
+[package]
+name = "hello-world-from-c"
+version = "0.1.0"
+authors = ["you@example.com"]
+build = "build.rs"
+```
+
+For now we’re not going to use any build dependencies, so let’s take a look at
+the build script now:
+
+```rust,no_run
+// build.rs
+
+use std::process::Command;
+use std::env;
+use std::path::Path;
+
+fn main() {
+ let out_dir = env::var("OUT_DIR").unwrap();
+
+ // note that there are a number of downsides to this approach, the comments
+ // below detail how to improve the portability of these commands.
+ Command::new("gcc").args(&["src/hello.c", "-c", "-fPIC", "-o"])
+ .arg(&format!("{}/hello.o", out_dir))
+ .status().unwrap();
+ Command::new("ar").args(&["crus", "libhello.a", "hello.o"])
+ .current_dir(&Path::new(&out_dir))
+ .status().unwrap();
+
+ println!("cargo:rustc-link-search=native={}", out_dir);
+ println!("cargo:rustc-link-lib=static=hello");
+}
+```
+
+This build script starts out by compiling our C file into an object file (by
+invoking `gcc`) and then converting this object file into a static library (by
+invoking `ar`). The final step is feedback to Cargo itself to say that our
+output was in `out_dir` and the compiler should link the crate to `libhello.a`
+statically via the `-l static=hello` flag.
+
+Note that there are a number of drawbacks to this hardcoded approach:
+
+* The `gcc` command itself is not portable across platforms. For example it’s
+ unlikely that Windows platforms have `gcc`, and not even all Unix platforms
+ may have `gcc`. The `ar` command is also in a similar situation.
+* These commands do not take cross-compilation into account. If we’re cross
+ compiling for a platform such as Android it’s unlikely that `gcc` will produce
+ an ARM executable.
+
+Not to fear, though, this is where a `build-dependencies` entry would help! The
+Cargo ecosystem has a number of packages to make this sort of task much easier,
+portable, and standardized. For example, the build script could be written as:
+
+```rust,ignore
+// build.rs
+
+// Bring in a dependency on an externally maintained `gcc` package which manages
+// invoking the C compiler.
+extern crate gcc;
+
+fn main() {
+ gcc::compile_library("libhello.a", &["src/hello.c"]);
+}
+```
+
+Add a build time dependency on the `gcc` crate with the following addition to
+your `Cargo.toml`:
+
+```toml
+[build-dependencies]
+gcc = "0.3"
+```
+
+The [`gcc` crate](https://crates.io/crates/gcc) abstracts a range of build
+script requirements for C code:
+
+* It invokes the appropriate compiler (MSVC for windows, `gcc` for MinGW, `cc`
+ for Unix platforms, etc.).
+* It takes the `TARGET` variable into account by passing appropriate flags to
+ the compiler being used.
+* Other environment variables, such as `OPT_LEVEL`, `DEBUG`, etc., are all
+ handled automatically.
+* The stdout output and `OUT_DIR` locations are also handled by the `gcc`
+ library.
+
+Here we can start to see some of the major benefits of farming as much
+functionality as possible out to common build dependencies rather than
+duplicating logic across all build scripts!
+
+Back to the case study though, let’s take a quick look at the contents of the
+`src` directory:
+
+```c
+// src/hello.c
+
+#include <stdio.h>
+
+void hello() {
+ printf("Hello, World!\n");
+}
+```
+
+```rust,ignore
+// src/main.rs
+
+// Note the lack of the `#[link]` attribute. We’re delegating the responsibility
+// of selecting what to link to over to the build script rather than hardcoding
+// it in the source file.
+extern { fn hello(); }
+
+fn main() {
+ unsafe { hello(); }
+}
+```
+
+And there we go! This should complete our example of building some C code from a
+Cargo package using the build script itself. This also shows why using a build
+dependency can be crucial in many situations and even much more concise!
+
+We’ve also seen a brief example of how a build script can use a crate as a
+dependency purely for the build process and not for the crate itself at runtime.
+
+### Case study: Linking to system libraries
+
+The final case study here will be investigating how a Cargo library links to a
+system library and how the build script is leveraged to support this use case.
+
+Quite frequently a Rust crate wants to link to a native library often provided
+on the system to bind its functionality or just use it as part of an
+implementation detail. This is quite a nuanced problem when it comes to
+performing this in a platform-agnostic fashion, and the purpose of a build
+script is again to farm out as much of this as possible to make this as easy as
+possible for consumers.
+
+As an example to follow, let’s take a look at one of [Cargo’s own
+dependencies][git2-rs], [libgit2][libgit2]. The C library has a number of
+constraints:
+
+[git2-rs]: https://github.com/alexcrichton/git2-rs/tree/master/libgit2-sys
+[libgit2]: https://github.com/libgit2/libgit2
+
+* It has an optional dependency on OpenSSL on Unix to implement the https
+ transport.
+* It has an optional dependency on libssh2 on all platforms to implement the ssh
+ transport.
+* It is often not installed on all systems by default.
+* It can be built from source using `cmake`.
+
+To visualize what’s going on here, let’s take a look at the manifest for the
+relevant Cargo package that links to the native C library.
+
+```toml
+[package]
+name = "libgit2-sys"
+version = "0.1.0"
+authors = ["..."]
+links = "git2"
+build = "build.rs"
+
+[dependencies]
+libssh2-sys = { git = "https://github.com/alexcrichton/ssh2-rs" }
+
+[target.'cfg(unix)'.dependencies]
+openssl-sys = { git = "https://github.com/alexcrichton/openssl-sys" }
+
+# ...
+```
+
+As the above manifests show, we’ve got a `build` script specified, but it’s
+worth noting that this example has a `links` entry which indicates that the
+crate (`libgit2-sys`) links to the `git2` native library.
+
+Here we also see that we chose to have the Rust crate have an unconditional
+dependency on `libssh2` via the `libssh2-sys` crate, as well as a
+platform-specific dependency on `openssl-sys` for \*nix (other variants elided
+for now). It may seem a little counterintuitive to express *C dependencies* in
+the *Cargo manifest*, but this is actually using one of Cargo’s conventions in
+this space.
+
+### `*-sys` Packages
+
+To alleviate linking to system libraries, Cargo has a *convention* of package
+naming and functionality. Any package named `foo-sys` will provide two major
+pieces of functionality:
+
+* The library crate will link to the native library `libfoo`. This will often
+ probe the current system for `libfoo` before resorting to building from
+ source.
+* The library crate will provide **declarations** for functions in `libfoo`,
+ but it does **not** provide bindings or higher-level abstractions.
+
+The set of `*-sys` packages provides a common set of dependencies for linking
+to native libraries. There are a number of benefits earned from having this
+convention of native-library-related packages:
+
+* Common dependencies on `foo-sys` alleviates the above rule about one package
+ per value of `links`.
+* A common dependency allows centralizing logic on discovering `libfoo` itself
+ (or building it from source).
+* These dependencies are easily overridable.
+
+### Building libgit2
+
+Now that we’ve got libgit2’s dependencies sorted out, we need to actually write
+the build script. We’re not going to look at specific snippets of code here and
+instead only take a look at the high-level details of the build script of
+`libgit2-sys`. This is not recommending all packages follow this strategy, but
+rather just outlining one specific strategy.
+
+The first step of the build script should do is to query whether libgit2 is
+already installed on the host system. To do this we’ll leverage the preexisting
+tool `pkg-config` (when its available). We’ll also use a `build-dependencies`
+section to refactor out all the `pkg-config` related code (or someone’s already
+done that!).
+
+If `pkg-config` failed to find libgit2, or if `pkg-config` just wasn’t
+installed, the next step is to build libgit2 from bundled source code
+(distributed as part of `libgit2-sys` itself). There are a few nuances when
+doing so that we need to take into account, however:
+
+* The build system of libgit2, `cmake`, needs to be able to find libgit2’s
+ optional dependency of libssh2. We’re sure we’ve already built it (it’s a
+ Cargo dependency), we just need to communicate this information. To do this
+ we leverage the metadata format to communicate information between build
+ scripts. In this example the libssh2 package printed out `cargo:root=...` to
+ tell us where libssh2 is installed at, and we can then pass this along to
+ cmake with the `CMAKE_PREFIX_PATH` environment variable.
+
+* We’ll need to handle some `CFLAGS` values when compiling C code (and tell
+ `cmake` about this). Some flags we may want to pass are `-m64` for 64-bit
+ code, `-m32` for 32-bit code, or `-fPIC` for 64-bit code as well.
+
+* Finally, we’ll invoke `cmake` to place all output into the `OUT_DIR`
+ environment variable, and then we’ll print the necessary metadata to instruct
+ rustc how to link to libgit2.
+
+Most of the functionality of this build script is easily refactorable into
+common dependencies, so our build script isn’t quite as intimidating as this
+descriptions! In reality it’s expected that build scripts are quite succinct by
+farming logic such as above to build dependencies.
--- /dev/null
+## Configuration
+
+This document will explain how Cargo’s configuration system works, as well as
+available keys or configuration. For configuration of a project through its
+manifest, see the [manifest format](reference/manifest.html).
+
+### Hierarchical structure
+
+
+Cargo allows local configuration for a particular project as well as global
+configuration, like git. Cargo extends this to a hierarchical strategy.
+If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the
+following configuration files would be probed for and unified in this order:
+
+* `/projects/foo/bar/baz/.cargo/config`
+* `/projects/foo/bar/.cargo/config`
+* `/projects/foo/.cargo/config`
+* `/projects/.cargo/config`
+* `/.cargo/config`
+* `$HOME/.cargo/config`
+
+With this structure, you can specify configuration per-project, and even
+possibly check it into version control. You can also specify personal defaults
+with a configuration file in your home directory.
+
+### Configuration format
+
+All configuration is currently in the [TOML format][toml] (like the manifest),
+with simple key-value pairs inside of sections (tables) which all get merged
+together.
+
+[toml]: https://github.com/toml-lang/toml
+
+### Configuration keys
+
+All of the following keys are optional, and their defaults are listed as their
+value unless otherwise noted.
+
+Key values that specify a tool may be given as an absolute path, a relative path
+or as a pathless tool name. Absolute paths and pathless tool names are used as
+given. Relative paths are resolved relative to the parent directory of the
+`.cargo` directory of the config file that the value resides within.
+
+```toml
+# An array of paths to local repositories which are to be used as overrides for
+# dependencies. For more information see the Specifying Dependencies guide.
+paths = ["/path/to/override"]
+
+[cargo-new]
+# This is your name/email to place in the `authors` section of a new Cargo.toml
+# that is generated. If not present, then `git` will be probed, and if that is
+# not present then `$USER` and `$EMAIL` will be used.
+name = "..."
+email = "..."
+
+# By default `cargo new` will initialize a new Git repository. This key can be
+# set to `hg` to create a Mercurial repository, or `none` to disable this
+# behavior.
+vcs = "none"
+
+# For the following sections, $triple refers to any valid target triple, not the
+# literal string "$triple", and it will apply whenever that target triple is
+# being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for
+# conditional compilation.
+[target.$triple]
+# This is the linker which is passed to rustc (via `-C linker=`) when the `$triple`
+# is being compiled for. By default this flag is not passed to the compiler.
+linker = ".."
+# Same but for the library archiver which is passed to rustc via `-C ar=`.
+ar = ".."
+# If a runner is provided, compiled targets for the `$triple` will be executed
+# by invoking the specified runner executable with actual target as first argument.
+# This applies to `cargo run`, `cargo test` and `cargo bench` commands.
+# By default compiled targets are executed directly.
+runner = ".."
+# custom flags to pass to all compiler invocations that target $triple
+# this value overrides build.rustflags when both are present
+rustflags = ["..", ".."]
+
+[target.'cfg(...)']
+# Similar for the $triple configuration, but using the `cfg` syntax.
+# If several `cfg` and $triple targets are candidates, then the rustflags
+# are concatenated. The `cfg` syntax only applies to rustflags, and not to
+# linker.
+rustflags = ["..", ".."]
+
+# Configuration keys related to the registry
+[registry]
+index = "..." # URL of the registry index (defaults to the central repository)
+token = "..." # Access token (found on the central repo’s website)
+
+[http]
+proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none)
+ # in libcurl format, e.g. "socks5h://host:port"
+timeout = 60000 # Timeout for each HTTP request, in milliseconds
+cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional)
+check-revoke = true # Indicates whether SSL certs are checked for revocation
+
+[build]
+jobs = 1 # number of parallel jobs, defaults to # of CPUs
+rustc = "rustc" # the rust compiler tool
+rustdoc = "rustdoc" # the doc generator tool
+target = "triple" # build for the target triple
+target-dir = "target" # path of where to place all generated artifacts
+rustflags = ["..", ".."] # custom flags to pass to all compiler invocations
+
+[term]
+verbose = false # whether cargo provides verbose output
+color = 'auto' # whether cargo colorizes output
+
+# Network configuration
+[net]
+retry = 2 # number of times a network call will automatically retried
+
+# Alias cargo commands. The first 3 aliases are built in. If your
+# command requires grouped whitespace use the list format.
+[alias]
+b = "build"
+t = "test"
+r = "run"
+rr = "run --release"
+space_example = ["run", "--release", "--", "\"command list\""]
+```
+
+### Environment variables
+
+Cargo can also be configured through environment variables in addition to the
+TOML syntax above. For each configuration key above of the form `foo.bar` the
+environment variable `CARGO_FOO_BAR` can also be used to define the value. For
+example the `build.jobs` key can also be defined by `CARGO_BUILD_JOBS`.
+
+Environment variables will take precedent over TOML configuration, and currently
+only integer, boolean, and string keys are supported to be defined by
+environment variables.
+
+In addition to the system above, Cargo recognizes a few other specific
+[environment variables][env].
+
+[env]: reference/environment-variables.html
--- /dev/null
+## Environment Variables
+
+Cargo sets and reads a number of environment variables which your code can detect
+or override. Here is a list of the variables Cargo sets, organized by when it interacts
+with them:
+
+### Environment variables Cargo reads
+
+You can override these environment variables to change Cargo's behavior on your
+system:
+
+* `CARGO_HOME` - Cargo maintains a local cache of the registry index and of git
+ checkouts of crates. By default these are stored under `$HOME/.cargo`, but
+ this variable overrides the location of this directory. Once a crate is cached
+ it is not removed by the clean command.
+* `CARGO_TARGET_DIR` - Location of where to place all generated artifacts,
+ relative to the current working directory.
+* `RUSTC` - Instead of running `rustc`, Cargo will execute this specified
+ compiler instead.
+* `RUSTC_WRAPPER` - Instead of simply running `rustc`, Cargo will execute this
+ specified wrapper instead, passing as its commandline arguments the rustc
+ invocation, with the first argument being rustc.
+* `RUSTDOC` - Instead of running `rustdoc`, Cargo will execute this specified
+ `rustdoc` instance instead.
+* `RUSTDOCFLAGS` - A space-separated list of custom flags to pass to all `rustdoc`
+ invocations that Cargo performs. In contrast with `cargo rustdoc`, this is
+ useful for passing a flag to *all* `rustdoc` instances.
+* `RUSTFLAGS` - A space-separated list of custom flags to pass to all compiler
+ invocations that Cargo performs. In contrast with `cargo rustc`, this is
+ useful for passing a flag to *all* compiler instances.
+
+Note that Cargo will also read environment variables for `.cargo/config`
+configuration values, as described in [that documentation][config-env]
+
+[config-env]: reference/config.html#environment-variables
+
+### Environment variables Cargo sets for crates
+
+Cargo exposes these environment variables to your crate when it is compiled.
+Note that this applies for test binaries as well.
+To get the value of any of these variables in a Rust program, do this:
+
+```rust
+let version = env!("CARGO_PKG_VERSION");
+```
+
+`version` will now contain the value of `CARGO_PKG_VERSION`.
+
+* `CARGO` - Path to the `cargo` binary performing the build.
+* `CARGO_MANIFEST_DIR` - The directory containing the manifest of your package.
+* `CARGO_PKG_VERSION` - The full version of your package.
+* `CARGO_PKG_VERSION_MAJOR` - The major version of your package.
+* `CARGO_PKG_VERSION_MINOR` - The minor version of your package.
+* `CARGO_PKG_VERSION_PATCH` - The patch version of your package.
+* `CARGO_PKG_VERSION_PRE` - The pre-release version of your package.
+* `CARGO_PKG_AUTHORS` - Colon separated list of authors from the manifest of your package.
+* `CARGO_PKG_NAME` - The name of your package.
+* `CARGO_PKG_DESCRIPTION` - The description of your package.
+* `CARGO_PKG_HOMEPAGE` - The home page of your package.
+* `OUT_DIR` - If the package has a build script, this is set to the folder where the build
+ script should place its output. See below for more information.
+
+### Environment variables Cargo sets for build scripts
+
+Cargo sets several environment variables when build scripts are run. Because these variables
+are not yet set when the build script is compiled, the above example using `env!` won't work
+and instead you'll need to retrieve the values when the build script is run:
+
+```rust
+use std::env;
+let out_dir = env::var("OUT_DIR").unwrap();
+```
+
+`out_dir` will now contain the value of `OUT_DIR`.
+
+* `CARGO` - Path to the `cargo` binary performing the build.
+* `CARGO_MANIFEST_DIR` - The directory containing the manifest for the package
+ being built (the package containing the build
+ script). Also note that this is the value of the
+ current working directory of the build script when it
+ starts.
+* `CARGO_MANIFEST_LINKS` - the manifest `links` value.
+* `CARGO_FEATURE_<name>` - For each activated feature of the package being
+ built, this environment variable will be present
+ where `<name>` is the name of the feature uppercased
+ and having `-` translated to `_`.
+* `CARGO_CFG_<cfg>` - For each [configuration option][configuration] of the
+ package being built, this environment variable will
+ contain the value of the configuration, where `<cfg>` is
+ the name of the configuration uppercased and having `-`
+ translated to `_`.
+ Boolean configurations are present if they are set, and
+ not present otherwise.
+ Configurations with multiple values are joined to a
+ single variable with the values delimited by `,`.
+* `OUT_DIR` - the folder in which all output should be placed. This folder is
+ inside the build directory for the package being built, and it is
+ unique for the package in question.
+* `TARGET` - the target triple that is being compiled for. Native code should be
+ compiled for this triple. Some more information about target
+ triples can be found in [clang’s own documentation][clang].
+* `HOST` - the host triple of the rust compiler.
+* `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can
+ be useful to pass a `-j` parameter to a system like `make`. Note
+ that care should be taken when interpreting this environment
+ variable. For historical purposes this is still provided but
+ recent versions of Cargo, for example, do not need to run `make
+ -j` as it'll automatically happen. Cargo implements its own
+ [jobserver] and will allow build scripts to inherit this
+ information, so programs compatible with GNU make jobservers will
+ already have appropriately configured parallelism.
+* `OPT_LEVEL`, `DEBUG` - values of the corresponding variables for the
+ profile currently being built.
+* `PROFILE` - `release` for release builds, `debug` for other builds.
+* `DEP_<name>_<key>` - For more information about this set of environment
+ variables, see build script documentation about [`links`][links].
+* `RUSTC`, `RUSTDOC` - the compiler and documentation generator that Cargo has
+ resolved to use, passed to the build script so it might
+ use it as well.
+
+[links]: reference/build-scripts.html#the-links-manifest-key
+[profile]: reference/manifest.html#the-profile-sections
+[configuration]: https://doc.rust-lang.org/reference/attributes.html#conditional-compilation
+[clang]:http://clang.llvm.org/docs/CrossCompilation.html#target-triple
+
+### Environment variables Cargo sets for 3rd party subcommands
+
+Cargo exposes this environment variable to 3rd party subcommands
+(ie. programs named `cargo-foobar` placed in `$PATH`):
+
+* `CARGO` - Path to the `cargo` binary performing the build.
--- /dev/null
+## External tools
+
+One of the goals of Cargo is simple integration with third-party tools, like
+IDEs and other build systems. To make integration easier, Cargo has several
+facilities:
+
+* a `cargo metadata` command, which outputs project structure and dependencies
+ information in JSON,
+
+* a `--message-format` flag, which outputs information about a particular build,
+ and
+
+* support for custom subcommands.
+
+
+### Information about project structure
+
+You can use `cargo metadata` command to get information about project structure
+and dependencies. The output of the command looks like this:
+
+```text
+{
+ // Integer version number of the format.
+ "version": integer,
+
+ // List of packages for this workspace, including dependencies.
+ "packages": [
+ {
+ // Opaque package identifier.
+ "id": PackageId,
+
+ "name": string,
+
+ "version": string,
+
+ "source": SourceId,
+
+ // A list of declared dependencies, see `resolve` field for actual dependencies.
+ "dependencies": [ Dependency ],
+
+ "targets: [ Target ],
+
+ // Path to Cargo.toml
+ "manifest_path": string,
+ }
+ ],
+
+ "workspace_members": [ PackageId ],
+
+ // Dependencies graph.
+ "resolve": {
+ "nodes": [
+ {
+ "id": PackageId,
+ "dependencies": [ PackageId ]
+ }
+ ]
+ }
+}
+```
+
+The format is stable and versioned. When calling `cargo metadata`, you should
+pass `--format-version` flag explicitly to avoid forward incompatibility
+hazard.
+
+If you are using Rust, there is [cargo_metadata] crate.
+
+[cargo_metadata]: https://crates.io/crates/cargo_metadata
+
+
+### Information about build
+
+When passing `--message-format=json`, Cargo will output the following
+information during the build:
+
+* compiler errors and warnings,
+
+* produced artifacts,
+
+* results of the build scripts (for example, native dependencies).
+
+The output goes to stdout in the JSON object per line format. The `reason` field
+distinguishes different kinds of messages.
+
+Information about dependencies in the Makefile-compatible format is stored in
+the `.d` files alongside the artifacts.
+
+
+### Custom subcommands
+
+Cargo is designed to be extensible with new subcommands without having to modify
+Cargo itself. This is achieved by translating a cargo invocation of the form
+cargo `(?<command>[^ ]+)` into an invocation of an external tool
+`cargo-${command}` that then needs to be present in one of the user's `$PATH`
+directories.
+
+Custom subcommand may use `CARGO` environment variable to call back to
+Cargo. Alternatively, it can link to `cargo` crate as a library, but this
+approach has drawbacks:
+
+* Cargo as a library is unstable, API changes without deprecation,
+
+* versions of Cargo library and Cargo binary may be different.
--- /dev/null
+## Cargo Reference
+
+Now that you have an overview of how to use Cargo and have created your first
+crate, you may be interested in more details in the following areas.
+
+The reference covers the details of various areas of Cargo.
+
+* [Specifying Dependencies](reference/specifying-dependencies.html)
+* [The Manifest Format](reference/manifest.html)
+* [Configuration](reference/config.html)
+* [Environment Variables](reference/environment-variables.html)
+* [Build Scripts](reference/build-scripts.html)
+* [Publishing on crates.io](reference/publishing.html)
+* [Package ID Specifications](reference/pkgid-spec.html)
+* [Source Replacement](reference/source-replacement.html)
+* [External Tools](reference/external-tools.html)
--- /dev/null
+## The Manifest Format
+
+The `Cargo.toml` file for each package is called its *manifest*. Every manifest
+file consists of one or more sections.
+
+### The `[package]` section
+
+The first section in a `Cargo.toml` is `[package]`.
+
+```toml
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0" # the current version, obeying semver
+authors = ["you@example.com"]
+```
+
+All three of these fields are mandatory.
+
+#### The `version` field
+
+Cargo bakes in the concept of [Semantic
+Versioning](http://semver.org/), 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 Rust, 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 tiny
+ 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.
+
+#### The `build` field (optional)
+
+This field specifies a file in the project root which is a [build script][1] for
+building native code. More information can be found in the build script
+[guide][1].
+
+[1]: reference/build-scripts.html
+
+```toml
+[package]
+# ...
+build = "build.rs"
+```
+
+#### The `documentation` field (optional)
+
+This field specifies a URL to a website hosting the crate's documentation.
+If no URL is specified in the manifest file, [crates.io][cratesio] will
+automatically link your crate to the corresponding [docs.rs][docsrs] page.
+
+Documentation links from specific hosts are blacklisted. Hosts are added
+to the blacklist if they are known to not be hosting documentation and are
+possibly of malicious intent e.g. ad tracking networks. URLs from the
+following hosts are blacklisted:
+
+* rust-ci.org
+
+Documentation URLs from blacklisted hosts will not appear on crates.io, and
+may be replaced by docs.rs links.
+
+[docsrs]: https://docs.rs/
+[cratesio]: https://crates.io/
+
+#### The `exclude` and `include` fields (optional)
+
+You can explicitly specify to Cargo that a set of [globs][globs] should be
+ignored or included for the purposes of packaging and rebuilding a package. The
+globs specified in the `exclude` field identify a set of files that are not
+included when a package is published as well as ignored for the purposes of
+detecting when to rebuild a package, and the globs in `include` specify files
+that are explicitly included.
+
+If a VCS is being used for a package, the `exclude` field will be seeded with
+the VCS’ ignore settings (`.gitignore` for git for example).
+
+```toml
+[package]
+# ...
+exclude = ["build/**/*.o", "doc/**/*.html"]
+```
+
+```toml
+[package]
+# ...
+include = ["src/**/*", "Cargo.toml"]
+```
+
+The options are mutually exclusive: setting `include` will override an
+`exclude`. Note that `include` must be an exhaustive list of files as otherwise
+necessary source files may not be included.
+
+[globs]: http://doc.rust-lang.org/glob/glob/struct.Pattern.html
+
+#### Migrating to `gitignore`-like pattern matching
+
+The current interpretation of these configs is based on UNIX Globs, as
+implemented in the [`glob` crate](https://crates.io/crates/glob). We want
+Cargo's `include` and `exclude` configs to work as similar to `gitignore` as
+possible. [The `gitignore` specification](https://git-scm.com/docs/gitignore) is
+also based on Globs, but has a bunch of additional features that enable easier
+pattern writing and more control. Therefore, we are migrating the interpretation
+for the rules of these configs to use the [`ignore`
+crate](https://crates.io/crates/ignore), and treat them each rule as a single
+line in a `gitignore` file. See [the tracking
+issue](https://github.com/rust-lang/cargo/issues/4268) for more details on the
+migration.
+
+#### The `publish` field (optional)
+
+The `publish` field can be used to prevent a package from being published to a
+package registry (like *crates.io*) by mistake.
+
+```toml
+[package]
+# ...
+publish = false
+```
+
+#### The `workspace` field (optional)
+
+The `workspace` field can be used to configure the workspace that this package
+will be a member of. If not specified this will be inferred as the first
+Cargo.toml with `[workspace]` upwards in the filesystem.
+
+```toml
+[package]
+# ...
+workspace = "path/to/workspace/root"
+```
+
+For more information, see the documentation for the workspace table below.
+
+#### Package metadata
+
+There are a number of optional metadata fields also accepted under the
+`[package]` section:
+
+```toml
+[package]
+# ...
+
+# A short blurb about the package. This is not rendered in any format when
+# uploaded to crates.io (aka this is not markdown).
+description = "..."
+
+# These URLs point to more information about the package. These are
+# intended to be webviews of the relevant data, not necessarily compatible
+# with VCS tools and the like.
+documentation = "..."
+homepage = "..."
+repository = "..."
+
+# This points to a file under the package root (relative to this `Cargo.toml`).
+# The contents of this file are stored and indexed in the registry.
+# crates.io will render this file and place the result on the crate's page.
+readme = "..."
+
+# This is a list of up to five keywords that describe this crate. Keywords
+# are searchable on crates.io, and you may choose any words that would
+# help someone find this crate.
+keywords = ["...", "..."]
+
+# This is a list of up to five categories where this crate would fit.
+# Categories are a fixed list available at crates.io/category_slugs, and
+# they must match exactly.
+categories = ["...", "..."]
+
+# This is an SPDX 2.1 license expression for this package. Currently
+# crates.io will validate the license provided against a whitelist of
+# known license and exception identifiers from the SPDX license list
+# 2.4. Parentheses are not currently supported.
+#
+# Multiple licenses can be separated with a `/`, although that usage
+# is deprecated. Instead, use a license expression with AND and OR
+# operators to get more explicit semantics.
+license = "..."
+
+# If a project is using a nonstandard license, then this key may be specified in
+# lieu of the above key and must point to a file relative to this manifest
+# (similar to the readme key).
+license-file = "..."
+
+# Optional specification of badges to be displayed on crates.io.
+#
+# - The badges pertaining to build status that are currently available are
+# Appveyor, CircleCI, GitLab, and TravisCI.
+# - Available badges pertaining to code test coverage are Codecov and
+# Coveralls.
+# - There are also maintenance-related badges basesed on isitmaintained.com
+# which state the issue resolution time, percent of open issues, and future
+# maintenance intentions.
+#
+# If a `repository` key is required, this refers to a repository in
+# `user/repo` format.
+[badges]
+
+# Appveyor: `repository` is required. `branch` is optional; default is `master`
+# `service` is optional; valid values are `github` (default), `bitbucket`, and
+# `gitlab`.
+appveyor = { repository = "...", branch = "master", service = "github" }
+
+# Circle CI: `repository` is required. `branch` is optional; default is `master`
+circle-ci = { repository = "...", branch = "master" }
+
+# GitLab: `repository` is required. `branch` is optional; default is `master`
+gitlab = { repository = "...", branch = "master" }
+
+# Travis CI: `repository` in format "<user>/<project>" is required.
+# `branch` is optional; default is `master`
+travis-ci = { repository = "...", branch = "master" }
+
+# Codecov: `repository` is required. `branch` is optional; default is `master`
+# `service` is optional; valid values are `github` (default), `bitbucket`, and
+# `gitlab`.
+codecov = { repository = "...", branch = "master", service = "github" }
+
+# Coveralls: `repository` is required. `branch` is optional; default is `master`
+# `service` is optional; valid values are `github` (default) and `bitbucket`.
+coveralls = { repository = "...", branch = "master", service = "github" }
+
+# Is it maintained resolution time: `repository` is required.
+is-it-maintained-issue-resolution = { repository = "..." }
+
+# Is it maintained percentage of open issues: `repository` is required.
+is-it-maintained-open-issues = { repository = "..." }
+
+# Maintenance: `status` is required Available options are `actively-developed`,
+# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer`
+# and `deprecated`.
+maintenance = { status = "..." }
+```
+
+The [crates.io](https://crates.io) registry will render the description, display
+the license, link to the three URLs and categorize by the keywords. These keys
+provide useful information to users of the registry and also influence the
+search ranking of a crate. It is highly discouraged to omit everything in a
+published crate.
+
+SPDX 2.1 license expressions are documented
+[here][spdx-2.1-license-expressions]. The current version of the
+license list is available [here][spdx-license-list], and version 2.4
+is available [here][spdx-license-list-2.4].
+
+#### The `metadata` table (optional)
+
+Cargo by default will warn about unused keys in `Cargo.toml` to assist in
+detecting typos and such. The `package.metadata` table, however, is completely
+ignored by Cargo and will not be warned about. This section can be used for
+tools which would like to store project configuration in `Cargo.toml`. For
+example:
+
+```toml
+[package]
+name = "..."
+# ...
+
+# Metadata used when generating an Android APK, for example.
+[package.metadata.android]
+package-name = "my-awesome-android-app"
+assets = "path/to/static"
+```
+
+### Dependency sections
+
+See the [specifying dependencies page](reference/specifying-dependencies.html) for
+information on the `[dependencies]`, `[dev-dependencies]`,
+`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
+
+### The `[profile.*]` sections
+
+Cargo supports custom configuration of how rustc is invoked through profiles at
+the top level. Any manifest may declare a profile, but only the top level
+project’s profiles are actually read. All dependencies’ profiles will be
+overridden. This is done so the top-level project has control over how its
+dependencies are compiled.
+
+There are five currently supported profile names, all of which have the same
+configuration available to them. Listed below is the configuration available,
+along with the defaults for each profile.
+
+```toml
+# The development profile, used for `cargo build`.
+[profile.dev]
+opt-level = 0 # controls the `--opt-level` the compiler builds with.
+ # 0-1 is good for debugging. 2 is well-optimized. Max is 3.
+debug = true # include debug information (debug symbols). Equivalent to
+ # `-C debuginfo=2` compiler flag.
+rpath = false # controls whether compiler should set loader paths.
+ # If true, passes `-C rpath` flag to the compiler.
+lto = false # Link Time Optimization usually reduces size of binaries
+ # and static libraries. Increases compilation time.
+ # If true, passes `-C lto` flag to the compiler.
+debug-assertions = true # controls whether debug assertions are enabled
+ # (e.g. debug_assert!() and arithmetic overflow checks)
+codegen-units = 1 # if > 1 enables parallel code generation which improves
+ # compile times, but prevents some optimizations.
+ # Passes `-C codegen-units`. Ignored when `lto = true`.
+panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
+
+# The release profile, used for `cargo build --release`.
+[profile.release]
+opt-level = 3
+debug = false
+rpath = false
+lto = false
+debug-assertions = false
+codegen-units = 1
+panic = 'unwind'
+
+# The testing profile, used for `cargo test`.
+[profile.test]
+opt-level = 0
+debug = 2
+rpath = false
+lto = false
+debug-assertions = true
+codegen-units = 1
+panic = 'unwind'
+
+# The benchmarking profile, used for `cargo bench` and `cargo test --release`.
+[profile.bench]
+opt-level = 3
+debug = false
+rpath = false
+lto = false
+debug-assertions = false
+codegen-units = 1
+panic = 'unwind'
+
+# The documentation profile, used for `cargo doc`.
+[profile.doc]
+opt-level = 0
+debug = 2
+rpath = false
+lto = false
+debug-assertions = true
+codegen-units = 1
+panic = 'unwind'
+```
+
+### The `[features]` section
+
+Cargo supports features to allow expression of:
+
+* conditional compilation options (usable through `cfg` attributes);
+* optional dependencies, which enhance a package, but are not required; and
+* clusters of optional dependencies, such as `postgres`, that would include the
+ `postgres` package, the `postgres-macros` package, and possibly other packages
+ (such as development-time mocking libraries, debugging tools, etc.).
+
+A feature of a package is either an optional dependency, or a set of other
+features. The format for specifying features is:
+
+```toml
+[package]
+name = "awesome"
+
+[features]
+# The default set of optional packages. Most people will want to use these
+# packages, but they are strictly optional. Note that `session` is not a package
+# but rather another feature listed in this manifest.
+default = ["jquery", "uglifier", "session"]
+
+# A feature with no dependencies is used mainly for conditional compilation,
+# like `#[cfg(feature = "go-faster")]`.
+go-faster = []
+
+# The `secure-password` feature depends on the bcrypt package. This aliasing
+# will allow people to talk about the feature in a higher-level way and allow
+# this package to add more requirements to the feature in the future.
+secure-password = ["bcrypt"]
+
+# Features can be used to reexport features of other packages. The `session`
+# feature of package `awesome` will ensure that the `session` feature of the
+# package `cookie` is also enabled.
+session = ["cookie/session"]
+
+[dependencies]
+# These packages are mandatory and form the core of this package’s distribution.
+cookie = "1.2.0"
+oauth = "1.1.0"
+route-recognizer = "=2.1.0"
+
+# A list of all of the optional dependencies, some of which are included in the
+# above `features`. They can be opted into by apps.
+jquery = { version = "1.0.2", optional = true }
+uglifier = { version = "1.5.3", optional = true }
+bcrypt = { version = "*", optional = true }
+civet = { version = "*", optional = true }
+```
+
+To use the package `awesome`:
+
+```toml
+[dependencies.awesome]
+version = "1.3.5"
+default-features = false # do not include the default features, and optionally
+ # cherry-pick individual features
+features = ["secure-password", "civet"]
+```
+
+#### Rules
+
+The usage of features is subject to a few rules:
+
+* Feature names must not conflict with other package names in the manifest. This
+ is because they are opted into via `features = [...]`, which only has a single
+ namespace.
+* With the exception of the `default` feature, all features are opt-in. To opt
+ out of the default feature, use `default-features = false` and cherry-pick
+ individual features.
+* Feature groups are not allowed to cyclically depend on one another.
+* Dev-dependencies cannot be optional.
+* Features groups can only reference optional dependencies.
+* When a feature is selected, Cargo will call `rustc` with `--cfg
+ feature="${feature_name}"`. If a feature group is included, it and all of its
+ individual features will be included. This can be tested in code via
+ `#[cfg(feature = "foo")]`.
+
+Note that it is explicitly allowed for features to not actually activate any
+optional dependencies. This allows packages to internally enable/disable
+features without requiring a new dependency.
+
+#### Usage in end products
+
+One major use-case for this feature is specifying optional features in
+end-products. For example, the Servo project may want to include optional
+features that people can enable or disable when they build it.
+
+In that case, Servo will describe features in its `Cargo.toml` and they can be
+enabled using command-line flags:
+
+```shell
+$ cargo build --release --features "shumway pdf"
+```
+
+Default features could be excluded using `--no-default-features`.
+
+#### Usage in packages
+
+In most cases, the concept of *optional dependency* in a library is best
+expressed as a separate package that the top-level application depends on.
+
+However, high-level packages, like Iron or Piston, may want the ability to
+curate a number of packages for easy installation. The current Cargo system
+allows them to curate a number of mandatory dependencies into a single package
+for easy installation.
+
+In some cases, packages may want to provide additional curation for optional
+dependencies:
+
+* grouping a number of low-level optional dependencies together into a single
+ high-level feature;
+* specifying packages that are recommended (or suggested) to be included by
+ users of the package; and
+* including a feature (like `secure-password` in the motivating example) that
+ will only work if an optional dependency is available, and would be difficult
+ to implement as a separate package (for example, it may be overly difficult to
+ design an IO package to be completely decoupled from OpenSSL, with opt-in via
+ the inclusion of a separate package).
+
+In almost all cases, it is an antipattern to use these features outside of
+high-level packages that are designed for curation. If a feature is optional, it
+can almost certainly be expressed as a separate package.
+
+### The `[workspace]` section
+
+Projects can define a workspace which is a set of crates that will all share the
+same `Cargo.lock` and output directory. The `[workspace]` table can be defined
+as:
+
+```toml
+[workspace]
+
+# Optional key, inferred if not present
+members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
+
+# Optional key, empty if not present
+exclude = ["path1", "path/to/dir2"]
+```
+
+Workspaces were added to Cargo as part of [RFC 1525] and have a number of
+properties:
+
+* A workspace can contain multiple crates where one of them is the *root crate*.
+* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
+ required to have other configuration.
+* Whenever any crate in the workspace is compiled, output is placed in the
+ *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`.
+* The lock file for all crates in the workspace resides in the *workspace root*.
+* The `[patch]` and `[replace]` sections in `Cargo.toml` are only recognized
+ in the *root crate*'s manifest, and ignored in member crates' manifests.
+
+[RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
+
+The *root crate* of a workspace, indicated by the presence of `[workspace]` in
+its manifest, is responsible for defining the entire workspace. All `path`
+dependencies residing in the workspace directory become members. You can add
+additional packages to the workspace by listing them in the `members` key. Note
+that members of the workspaces listed explicitly will also have their path
+dependencies included in the workspace. Sometimes a project may have a lot of
+workspace members and it can be onerous to keep up to date. The path dependency
+can also use [globs][globs] to match multiple paths. Finally, the `exclude`
+key can be used to blacklist paths from being included in a workspace. This can
+be useful if some path dependencies aren't desired to be in the workspace at
+all.
+
+The `package.workspace` manifest key (described above) is used in member crates
+to point at a workspace's root crate. If this key is omitted then it is inferred
+to be the first crate whose manifest contains `[workspace]` upwards in the
+filesystem.
+
+A crate may either specify `package.workspace` or specify `[workspace]`. That
+is, a crate cannot both be a root crate in a workspace (contain `[workspace]`)
+and also be a member crate of another workspace (contain `package.workspace`).
+
+Most of the time workspaces will not need to be dealt with as `cargo new` and
+`cargo init` will handle workspace configuration automatically.
+
+#### Virtual Manifest
+
+In workspace manifests, if the `package` table is present, the workspace root
+crate will be treated as a normal package, as well as a worksapce. If the
+`package` table is not present in a worksapce manifest, it is called a *virtual
+manifest*.
+
+When working with *virtual manifests*, package-related cargo commands, like
+`cargo build`, won't be available anymore. But, most of such commands support
+the `--all` option, will execute the command for all the non-virtual manifest in
+the workspace.
+
+#TODO: move this to a more appropriate place
+### The project layout
+
+If your project is an executable, name the main source file `src/main.rs`. If it
+is a library, name the main source file `src/lib.rs`.
+
+Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
+executable consists of more than just one source file, you might also use a directory
+inside `src/bin` containing a `main.rs` file which will be treated as an executable
+with a name of the parent directory.
+Do note, however, once you add a `[[bin]]` section ([see
+below](#configuring-a-target)), Cargo will no longer automatically build files
+located in `src/bin/*.rs`. Instead you must create a `[[bin]]` section for
+each file you want to build.
+
+Your project can optionally contain folders named `examples`, `tests`, and
+`benches`, which Cargo will treat as containing examples,
+integration tests, and benchmarks respectively.
+
+```shell
+▾ src/ # directory containing source files
+ lib.rs # the main entry point for libraries and packages
+ main.rs # the main entry point for projects producing executables
+ ▾ bin/ # (optional) directory containing additional executables
+ *.rs
+ ▾ */ # (optional) directories containing multi-file executables
+ main.rs
+▾ examples/ # (optional) examples
+ *.rs
+▾ tests/ # (optional) integration tests
+ *.rs
+▾ benches/ # (optional) benchmarks
+ *.rs
+```
+
+To structure your code after you've created the files and folders for your
+project, you should remember to use Rust's module system, which you can read
+about in [the book](https://doc.rust-lang.org/book/crates-and-modules.html).
+
+### Examples
+
+Files located under `examples` are example uses of the functionality provided by
+the library. When compiled, they are placed in the `target/examples` directory.
+
+They can compile either as executables (with a `main()` function) or libraries
+and pull in the library by using `extern crate <library-name>`. They are
+compiled when you run your tests to protect them from bitrotting.
+
+You can run individual executable examples with the command `cargo run --example
+<example-name>`.
+
+Specify `crate-type` to make an example be compiled as a library:
+
+```toml
+[[example]]
+name = "foo"
+crate-type = ["staticlib"]
+```
+
+You can build individual library examples with the command `cargo build
+--example <example-name>`.
+
+### Tests
+
+When you run `cargo test`, Cargo will:
+
+* compile and run your library’s unit tests, which are in the files reachable
+ from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
+ considered at this stage);
+* compile and run your library’s documentation tests, which are embedded inside
+ of documentation blocks;
+* compile and run your library’s [integration tests](#integration-tests); and
+* compile your library’s examples.
+
+#### Integration tests
+
+Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
+Cargo will compile each of these files as a separate crate. The crate can link
+to your library by using `extern crate <library-name>`, like any other code that
+depends on it.
+
+Cargo will not automatically compile files inside subdirectories of `tests`, but
+an integration test can import modules from these directories as usual. For
+example, if you want several integration tests to share some code, you can put
+the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
+the test files.
+
+### Configuring a target
+
+All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
+sections support similar configuration for specifying how a target should be
+built. The double-bracket sections like `[[bin]]` are array-of-table of
+[TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can
+write more than one `[[bin]]` section to make several executables in your crate.
+
+The example below uses `[lib]`, but it also applies to all other sections
+as well. All values listed are the defaults for that option unless otherwise
+specified.
+
+```toml
+[package]
+# ...
+
+[lib]
+# The name of a target is the name of the library that will be generated. This
+# is defaulted to the name of the package or project, with any dashes replaced
+# with underscores. (Rust `extern crate` declarations reference this name;
+# therefore the value must be a valid Rust identifier to be usable.)
+name = "foo"
+
+# This field points at where the crate is located, relative to the `Cargo.toml`.
+path = "src/lib.rs"
+
+# A flag for enabling unit tests for this target. This is used by `cargo test`.
+test = true
+
+# A flag for enabling documentation tests for this target. This is only relevant
+# for libraries, it has no effect on other sections. This is used by
+# `cargo test`.
+doctest = true
+
+# A flag for enabling benchmarks for this target. This is used by `cargo bench`.
+bench = true
+
+# A flag for enabling documentation of this target. This is used by `cargo doc`.
+doc = true
+
+# If the target is meant to be a compiler plugin, this field must be set to true
+# for Cargo to correctly compile it and make it available for all dependencies.
+plugin = false
+
+# If the target is meant to be a "macros 1.1" procedural macro, this field must
+# be set to true.
+proc-macro = false
+
+# If set to false, `cargo test` will omit the `--test` flag to rustc, which
+# stops it from generating a test harness. This is useful when the binary being
+# built manages the test runner itself.
+harness = true
+```
+
+#### The `required-features` field (optional)
+
+The `required-features` field specifies which features the target needs in order
+to be built. If any of the required features are not selected, the target will
+be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`,
+and `[[example]]` sections, it has no effect on `[lib]`.
+
+```toml
+[features]
+# ...
+postgres = []
+sqlite = []
+tools = []
+
+[[bin]]
+# ...
+required-features = ["postgres", "tools"]
+```
+
+#### Building dynamic or static libraries
+
+If your project produces a library, you can specify which kind of library to
+build by explicitly listing the library in your `Cargo.toml`:
+
+```toml
+# ...
+
+[lib]
+name = "..."
+crate-type = ["dylib"] # could be `staticlib` as well
+```
+
+The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and
+`proc-macro`. You should only use this option in a project. Cargo will always
+compile packages (dependencies) based on the requirements of the project that
+includes them.
+
+You can read more about the different crate types in the
+[Rust Reference Manual](https://doc.rust-lang.org/reference/linkage.html)
+
+### The `[patch]` Section
+
+This section of Cargo.toml can be used to [override dependencies][replace] with
+other copies. The syntax is similar to the `[dependencies]` section:
+
+```toml
+[patch.crates-io]
+foo = { git = 'https://github.com/example/foo' }
+bar = { path = 'my/local/bar' }
+```
+
+The `[patch]` table is made of dependency-like sub-tables. Each key after
+`[patch]` is a URL of the source that's being patched, or `crates-io` if
+you're modifying the https://crates.io registry. In the example above
+`crates-io` could be replaced with a git URL such as
+`https://github.com/rust-lang-nursery/log`.
+
+Each entry in these tables is a normal dependency specification, the same as
+found in the `[dependencies]` section of the manifest. The dependencies listed
+in the `[patch]` section are resolved and used to patch the source at the
+URL specified. The above manifest snippet patches the `crates-io` source (e.g.
+crates.io itself) with the `foo` crate and `bar` crate.
+
+Sources can be patched with versions of crates that do not exist, and they can
+also be patched with versions of crates that already exist. If a source is
+patched with a crate version that already exists in the source, then the
+source's original crate is replaced.
+
+More information about overriding dependencies can be found in the [overriding
+dependencies][replace] section of the documentation and [RFC 1969] for the
+technical specification of this feature. (Note that the `[patch]` feature will
+first become available in Rust 1.21, set to be released on 2017-10-12.)
+
+[RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
+[replace]: reference/specifying-dependencies.html#overriding-dependencies
+
+### The `[replace]` Section
+
+This section of Cargo.toml can be used to [override dependencies][replace] with
+other copies. The syntax is similar to the `[dependencies]` section:
+
+```toml
+[replace]
+"foo:0.1.0" = { git = 'https://github.com/example/foo' }
+"bar:1.0.2" = { path = 'my/local/bar' }
+```
+
+Each key in the `[replace]` table is a [package id
+specification](reference/pkgid-spec.html) which allows arbitrarily choosing a node in the
+dependency graph to override. The value of each key is the same as the
+`[dependencies]` syntax for specifying dependencies, except that you can't
+specify features. Note that when a crate is overridden the copy it's overridden
+with must have both the same name and version, but it can come from a different
+source (e.g. git or a local path).
+
+More information about overriding dependencies can be found in the [overriding
+dependencies][replace] section of the documentation.
+
+[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
+[spdx-license-list]: https://spdx.org/licenses/
+[spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4
--- /dev/null
+## Package ID Specifications
+
+### Package ID specifications
+
+Subcommands of Cargo frequently need to refer to a particular package within a
+dependency graph for various operations like updating, cleaning, building, etc.
+To solve this problem, Cargo supports Package ID Specifications. A specification
+is a string which is used to uniquely refer to one package within a graph of
+packages.
+
+#### Specification grammar
+
+The formal grammar for a Package Id Specification is:
+
+```notrust
+pkgid := pkgname
+ | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ]
+pkgname := name [ ":" semver ]
+
+proto := "http" | "git" | ...
+```
+
+Here, brackets indicate that the contents are optional.
+
+#### Example specifications
+
+These could all be references to a package `foo` version `1.2.3` from the
+registry at `crates.io`
+
+| pkgid | name | version | url |
+|:-----------------------------|:-----:|:-------:|:----------------------:|
+| `foo` | `foo` | `*` | `*` |
+| `foo:1.2.3` | `foo` | `1.2.3` | `*` |
+| `crates.io/foo` | `foo` | `*` | `*://crates.io/foo` |
+| `crates.io/foo#1.2.3` | `foo` | `1.2.3` | `*://crates.io/foo` |
+| `crates.io/bar#foo:1.2.3` | `foo` | `1.2.3` | `*://crates.io/bar` |
+| `http://crates.io/foo#1.2.3` | `foo` | `1.2.3` | `http://crates.io/foo` |
+
+#### Brevity of specifications
+
+The goal of this is to enable both succinct and exhaustive syntaxes for
+referring to packages in a dependency graph. Ambiguous references may refer to
+one or more packages. Most commands generate an error if more than one package
+could be referred to with the same specification.
--- /dev/null
+## Publishing on crates.io
+
+Once you've got a library that you'd like to share with the world, it's time to
+publish it on [crates.io]! Publishing a crate is when a specific
+version is uploaded to be hosted on [crates.io].
+
+Take care when publishing a crate, because a publish is **permanent**. The
+version can never be overwritten, and the code cannot be deleted. There is no
+limit to the number of versions which can be published, however.
+
+### Before your first publish
+
+First thing’s first, you’ll need an account on [crates.io] to acquire
+an API token. To do so, [visit the home page][crates.io] and log in via a GitHub
+account (required for now). After this, visit your [Account
+Settings](https://crates.io/me) page and run the `cargo login` command
+specified.
+
+```shell
+$ cargo login abcdefghijklmnopqrstuvwxyz012345
+```
+
+This command will inform Cargo of your API token and store it locally in your
+`~/.cargo/credentials` (previously it was `~/.cargo/config`). Note that this
+token is a **secret** and should not be shared with anyone else. If it leaks for
+any reason, you should regenerate it immediately.
+
+### Before publishing a new crate
+
+Keep in mind that crate names on [crates.io] are allocated on a first-come-first-
+serve basis. Once a crate name is taken, it cannot be used for another crate.
+
+#### Packaging a crate
+
+The next step is to package up your crate into a format that can be uploaded to
+[crates.io]. For this we’ll use the `cargo package` subcommand. This will take
+our entire crate and package it all up into a `*.crate` file in the
+`target/package` directory.
+
+```shell
+$ cargo package
+```
+
+As an added bonus, the `*.crate` will be verified independently of the current
+source tree. After the `*.crate` is created, it’s unpacked into
+`target/package` and then built from scratch to ensure that all necessary files
+are there for the build to succeed. This behavior can be disabled with the
+`--no-verify` flag.
+
+Now’s a good time to take a look at the `*.crate` file to make sure you didn’t
+accidentally package up that 2GB video asset, or large data files used for code
+generation, integration tests, or benchmarking. There is currently a 10MB
+upload size limit on `*.crate` files. So, if the size of `tests` and `benches`
+directories and their dependencies are up to a couple of MBs, you can keep them
+in your package; otherwsie, better to exclude them.
+
+Cargo will automatically ignore files ignored by your version control system
+when packaging, but if you want to specify an extra set of files to ignore you
+can use the `exclude` key in the manifest:
+
+```toml
+[package]
+# ...
+exclude = [
+ "public/assets/*",
+ "videos/*",
+]
+```
+
+The syntax of each element in this array is what
+[rust-lang/glob](https://github.com/rust-lang/glob) accepts. If you’d rather
+roll with a whitelist instead of a blacklist, Cargo also supports an `include`
+key, which if set, overrides the `exclude` key:
+
+```toml
+[package]
+# ...
+include = [
+ "**/*.rs",
+ "Cargo.toml",
+]
+```
+
+### Uploading the crate
+
+Now that we’ve got a `*.crate` file ready to go, it can be uploaded to
+[crates.io] with the `cargo publish` command. And that’s it, you’ve now published
+your first crate!
+
+```shell
+$ cargo publish
+```
+
+If you’d like to skip the `cargo package` step, the `cargo publish` subcommand
+will automatically package up the local crate if a copy isn’t found already.
+
+Be sure to check out the [metadata you can
+specify](reference/manifest.html#package-metadata) to ensure your crate can be
+discovered more easily!
+
+### Publishing a new version of an existing crate
+
+In order to release a new version, change the `version` value specified in your
+`Cargo.toml` manifest. Keep in mind [the semver
+rules](reference/manifest.html#the-version-field). Then optionally run `cargo package` if
+you want to inspect the `*.crate` file for the new version before publishing,
+and run `cargo publish` to upload the new version.
+
+### Managing a crates.io-based crate
+
+Management of crates is primarily done through the command line `cargo` tool
+rather than the [crates.io] web interface. For this, there are a few subcommands
+to manage a crate.
+
+#### `cargo yank`
+
+Occasions may arise where you publish a version of a crate that actually ends up
+being broken for one reason or another (syntax error, forgot to include a file,
+etc.). For situations such as this, Cargo supports a “yank” of a version of a
+crate.
+
+```shell
+$ cargo yank --vers 1.0.1
+$ cargo yank --vers 1.0.1 --undo
+```
+
+A yank **does not** delete any code. This feature is not intended for deleting
+accidentally uploaded secrets, for example. If that happens, you must reset
+those secrets immediately.
+
+The semantics of a yanked version are that no new dependencies can be created
+against that version, but all existing dependencies continue to work. One of the
+major goals of [crates.io] is to act as a permanent archive of crates that does
+not change over time, and allowing deletion of a version would go against this
+goal. Essentially a yank means that all projects with a `Cargo.lock` will not
+break, while any future `Cargo.lock` files generated will not list the yanked
+version.
+
+#### `cargo owner`
+
+A crate is often developed by more than one person, or the primary maintainer
+may change over time! The owner of a crate is the only person allowed to publish
+new versions of the crate, but an owner may designate additional owners.
+
+```shell
+$ cargo owner --add my-buddy
+$ cargo owner --remove my-buddy
+$ cargo owner --add github:rust-lang:owners
+$ cargo owner --remove github:rust-lang:owners
+```
+
+The owner IDs given to these commands must be GitHub user names or GitHub teams.
+
+If a user name is given to `--add`, that user becomes a “named” owner, with
+full rights to the crate. In addition to being able to publish or yank versions
+of the crate, they have the ability to add or remove owners, *including* the
+owner that made *them* an owner. Needless to say, you shouldn’t make people you
+don’t fully trust into a named owner. In order to become a named owner, a user
+must have logged into [crates.io] previously.
+
+If a team name is given to `--add`, that team becomes a “team” owner, with
+restricted right to the crate. While they have permission to publish or yank
+versions of the crate, they *do not* have the ability to add or remove owners.
+In addition to being more convenient for managing groups of owners, teams are
+just a bit more secure against owners becoming malicious.
+
+The syntax for teams is currently `github:org:team` (see examples above).
+In order to add a team as an owner one must be a member of that team. No
+such restriction applies to removing a team as an owner.
+
+### GitHub permissions
+
+Team membership is not something GitHub provides simple public access to, and it
+is likely for you to encounter the following message when working with them:
+
+> It looks like you don’t have permission to query a necessary property from
+GitHub to complete this request. You may need to re-authenticate on [crates.io]
+to grant permission to read GitHub org memberships. Just go to
+https://crates.io/login
+
+This is basically a catch-all for “you tried to query a team, and one of the
+five levels of membership access control denied this”. That is not an
+exaggeration. GitHub’s support for team access control is Enterprise Grade.
+
+The most likely cause of this is simply that you last logged in before this
+feature was added. We originally requested *no* permissions from GitHub when
+authenticating users, because we didn’t actually ever use the user’s token for
+anything other than logging them in. However to query team membership on your
+behalf, we now require
+[the `read:org` scope](https://developer.github.com/v3/oauth/#scopes).
+
+You are free to deny us this scope, and everything that worked before teams
+were introduced will keep working. However you will never be able to add a team
+as an owner, or publish a crate as a team owner. If you ever attempt to do this,
+you will get the error above. You may also see this error if you ever try to
+publish a crate that you don’t own at all, but otherwise happens to have a team.
+
+If you ever change your mind, or just aren’t sure if [crates.io] has sufficient
+permission, you can always go to https://crates.io/login, which will prompt you
+for permission if [crates.io] doesn’t have all the scopes it would like to.
+
+An additional barrier to querying GitHub is that the organization may be
+actively denying third party access. To check this, you can go to:
+
+ https://github.com/organizations/:org/settings/oauth_application_policy
+
+where `:org` is the name of the organization (e.g. rust-lang). You may see
+something like:
+
+
+
+Where you may choose to explicitly remove [crates.io] from your organization’s
+blacklist, or simply press the “Remove Restrictions” button to allow all third
+party applications to access this data.
+
+Alternatively, when [crates.io] requested the `read:org` scope, you could have
+explicitly whitelisted [crates.io] querying the org in question by pressing
+the “Grant Access” button next to its name:
+
+
+
+[crates.io]: https://crates.io/
--- /dev/null
+## Source Replacement
+
+Cargo supports the ability to **replace one source with another** to express
+strategies along the lines of mirrors or vendoring dependencies. Configuration
+is currently done through the [`.cargo/config` configuration][config] mechanism,
+like so:
+
+[config]: reference/config.html
+
+```toml
+# The `source` table is where all keys related to source-replacement
+# are stored.
+[source]
+
+# Under the `source` table are a number of other tables whose keys are a
+# name for the relevant source. For example this section defines a new
+# source, called `my-awesome-source`, which comes from a directory
+# located at `vendor` relative to the directory containing this `.cargo/config`
+# file
+[source.my-awesome-source]
+directory = "vendor"
+
+# The crates.io default source for crates is available under the name
+# "crates-io", and here we use the `replace-with` key to indicate that it's
+# replaced with our source above.
+[source.crates-io]
+replace-with = "my-awesome-source"
+```
+
+With this configuration Cargo attempts to look up all crates in the directory
+"vendor" rather than querying the online registry at crates.io. Using source
+replacement Cargo can express:
+
+* Vendoring - custom sources can be defined which represent crates on the local
+ filesystem. These sources are subsets of the source that they're replacing and
+ can be checked into projects if necessary.
+
+* Mirroring - sources can be replaced with an equivalent version which acts as a
+ cache for crates.io itself.
+
+Cargo has a core assumption about source replacement that the source code is
+exactly the same from both sources. In our above example Cargo assumes that all
+of the crates coming from `my-awesome-source` are the exact same as the copies
+from `crates-io`. Note that this also means that `my-awesome-source` is not
+allowed to have crates which are not present in the `crates-io` source.
+
+As a consequence, source replacement is not appropriate for situations such as
+patching a dependency or a private registry. Cargo supports patching
+dependencies through the usage of [the `[replace]` key][replace-section], and
+private registry support is planned for a future version of Cargo.
+
+[replace-section]: reference/manifest.html#the-replace-section
+
+### Configuration
+
+Configuration of replacement sources is done through [`.cargo/config`][config]
+and the full set of available keys are:
+
+```toml
+# Each source has its own table where the key is the name of the source
+[source.the-source-name]
+
+# Indicate that `the-source-name` will be replaced with `another-source`,
+# defined elsewhere
+replace-with = "another-source"
+
+# Available kinds of sources that can be specified (described below)
+registry = "https://example.com/path/to/index"
+local-registry = "path/to/registry"
+directory = "path/to/vendor"
+```
+
+The `crates-io` represents the crates.io online registry (default source of
+crates) and can be replaced with:
+
+```toml
+[source.crates-io]
+replace-with = 'another-source'
+```
+
+### Registry Sources
+
+A "registry source" is one that is the same as crates.io itself. That is, it has
+an index served in a git repository which matches the format of the
+[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
+then has configuration indicating where to download crates from.
+
+Currently there is not an already-available project for setting up a mirror of
+crates.io. Stay tuned though!
+
+### Local Registry Sources
+
+A "local registry source" is intended to be a subset of another registry
+source, but available on the local filesystem (aka vendoring). Local registries
+are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are
+made up of a set of `*.crate` files and an index like the normal registry is.
+
+The primary way to manage and crate local registry sources is through the
+[`cargo-local-registry`][cargo-local-registry] subcommand, available on
+crates.io and can be installed with `cargo install cargo-local-registry`.
+
+[cargo-local-registry]: https://crates.io/crates/cargo-local-registry
+
+Local registries are contained within one directory and contain a number of
+`*.crate` files downloaded from crates.io as well as an `index` directory with
+the same format as the crates.io-index project (populated with just entries for
+the crates that are present).
+
+### Directory Sources
+
+A "directory source" is similar to a local registry source where it contains a
+number of crates available on the local filesystem, suitable for vendoring
+dependencies. Also like local registries, directory sources can primarily be
+managed by an external subcommand, [`cargo-vendor`][cargo-vendor], which can be
+installed with `cargo install cargo-vendor`.
+
+[cargo-vendor]: https://crates.io/crates/cargo-vendor
+
+Directory sources are distinct from local registries though in that they contain
+the unpacked version of `*.crate` files, making it more suitable in some
+situations to check everything into source control. A directory source is just a
+directory containing a number of other directories which contain the source code
+for crates (the unpacked version of `*.crate` files). Currently no restriction
+is placed on the name of each directory.
+
+Each crate in a directory source also has an associated metadata file indicating
+the checksum of each file in the crate to protect against accidental
+modifications.
--- /dev/null
+## Specifying Dependencies
+
+Your crates can depend on other libraries from [crates.io], `git` repositories, or
+subdirectories on your local file system. You can also temporarily override the
+location of a dependency— for example, to be able to test out a bug fix in the
+dependency that you are working on locally. You can have different
+dependencies for different platforms, and dependencies that are only used during
+development. Let's take a look at how to do each of these.
+
+### Specifying dependencies from crates.io
+
+Cargo is configured to look for dependencies on [crates.io] by default. Only
+the name and a version string are required in this case. In [the cargo
+guide](guide/index.html), we specified a dependency on the `time` crate:
+
+```toml
+[dependencies]
+time = "0.1.12"
+```
+
+The string `"0.1.12"` is a [semver] version requirement. Since this
+string does not have any operators in it, it is interpreted the same way as
+if we had specified `"^0.1.12"`, which is called a caret requirement.
+
+[semver]: https://github.com/steveklabnik/semver#requirements
+
+### Caret requirements
+
+**Caret requirements** allow SemVer compatible updates to a specified version.
+An update is allowed if the new version number does not modify the left-most
+non-zero digit in the major, minor, patch grouping. In this case, if we ran
+`cargo update -p time`, cargo would update us to version `0.1.13` if it was
+available, but would not update us to `0.2.0`. If instead we had specified the
+version string as `^1.0`, cargo would update to `1.1` but not `2.0`. The version
+`0.0.x` is not considered compatible with any other version.
+
+Here are some more examples of caret requirements and the versions that would
+be allowed with them:
+
+```notrust
+^1.2.3 := >=1.2.3 <2.0.0
+^1.2 := >=1.2.0 <2.0.0
+^1 := >=1.0.0 <2.0.0
+^0.2.3 := >=0.2.3 <0.3.0
+^0.0.3 := >=0.0.3 <0.0.4
+^0.0 := >=0.0.0 <0.1.0
+^0 := >=0.0.0 <1.0.0
+```
+
+This compatibility convention is different from SemVer in the way it treats
+versions before 1.0.0. While SemVer says there is no compatibility before
+1.0.0, Cargo considers `0.x.y` to be compatible with `0.x.z`, where `y ≥ z`
+and `x > 0`.
+
+### Tilde requirements
+
+**Tilde requirements** specify a minimal version with some ability to update.
+If you specify a major, minor, and patch version or only a major and minor
+version, only patch-level changes are allowed. If you only specify a major
+version, then minor- and patch-level changes are allowed.
+
+`~1.2.3` is an example of a tilde requirement.
+
+```notrust
+~1.2.3 := >=1.2.3 <1.3.0
+~1.2 := >=1.2.0 <1.3.0
+~1 := >=1.0.0 <2.0.0
+```
+
+### Wildcard requirements
+
+**Wildcard requirements** allow for any version where the wildcard is
+positioned.
+
+`*`, `1.*` and `1.2.*` are examples of wildcard requirements.
+
+```notrust
+* := >=0.0.0
+1.* := >=1.0.0 <2.0.0
+1.2.* := >=1.2.0 <1.3.0
+```
+
+### Inequality requirements
+
+**Inequality requirements** allow manually specifying a version range or an
+exact version to depend on.
+
+Here are some examples of inequality requirements:
+
+```notrust
+>= 1.2.0
+> 1
+< 2
+= 1.2.3
+```
+
+### Multiple requirements
+
+Multiple version requirements can also be separated with a comma, e.g. `>= 1.2,
+< 1.5`.
+
+### Specifying dependencies from `git` repositories
+
+To depend on a library located in a `git` repository, the minimum information
+you need to specify is the location of the repository with the `git` key:
+
+```toml
+[dependencies]
+rand = { git = "https://github.com/rust-lang-nursery/rand" }
+```
+
+Cargo will fetch the `git` repository at this location then look for a
+`Cargo.toml` for the requested crate anywhere inside the `git` repository
+(not necessarily at the root).
+
+Since we haven’t specified any other information, Cargo assumes that
+we intend to use the latest commit on the `master` branch to build our project.
+You can combine the `git` key with the `rev`, `tag`, or `branch` keys to
+specify something else. Here's an example of specifying that you want to use
+the latest commit on a branch named `next`:
+
+```toml
+[dependencies]
+rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }
+```
+
+### Specifying path dependencies
+
+Over time, our `hello_world` project from [the guide](guide/index.html) has
+grown significantly in size! It’s gotten to the point that we probably want to
+split out a separate crate for others to use. To do this Cargo supports **path
+dependencies** which are typically sub-crates that live within one repository.
+Let’s start off by making a new crate inside of our `hello_world` project:
+
+```shell
+# inside of hello_world/
+$ cargo new hello_utils
+```
+
+This will create a new folder `hello_utils` inside of which a `Cargo.toml` and
+`src` folder are ready to be configured. In order to tell Cargo about this, open
+up `hello_world/Cargo.toml` and add `hello_utils` to your dependencies:
+
+```toml
+[dependencies]
+hello_utils = { path = "hello_utils" }
+```
+
+This tells Cargo that we depend on a crate called `hello_utils` which is found
+in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in).
+
+And that’s it! The next `cargo build` will automatically build `hello_utils` and
+all of its own dependencies, and others can also start using the crate as well.
+However, crates that use dependencies specified with only a path are not
+permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we
+would need to publish a version of `hello_utils` to [crates.io](https://crates.io)
+and specify its version in the dependencies line as well:
+
+```toml
+[dependencies]
+hello_utils = { path = "hello_utils", version = "0.1.0" }
+```
+
+### Overriding dependencies
+
+There are a number of methods in Cargo to support overriding dependencies and
+otherwise controlling the dependency graph. These options are typically, though,
+only available at the workspace level and aren't propagated through
+dependencies. In other words, "applications" have the ability to override
+dependencies but "libraries" do not.
+
+The desire to override a dependency or otherwise alter some dependencies can
+arise through a number of scenarios. Most of them, however, boil down to the
+ability to work with a crate before it's been published to crates.io. For
+example:
+
+* A crate you're working on is also used in a much larger application you're
+ working on, and you'd like to test a bug fix to the library inside of the
+ larger application.
+* An upstream crate you don't work on has a new feature or a bug fix on the
+ master branch of its git repository which you'd like to test out.
+* You're about to publish a new major version of your crate, but you'd like to
+ do integration testing across an entire project to ensure the new major
+ version works.
+* You've submitted a fix to an upstream crate for a bug you found, but you'd
+ like to immediately have your application start depending on the fixed version
+ of the crate to avoid blocking on the bug fix getting merged.
+
+These scenarios are currently all solved with the [`[patch]` manifest
+section][patch-section]. Note that the `[patch]` feature is not yet currently
+stable and will be released on 2017-08-31. Historically some of these scenarios
+have been solved with [the `[replace]` section][replace-section], but we'll
+document the `[patch]` section here.
+
+[patch-section]: reference/manifest.html#the-patch-section
+[replace-section]: reference/manifest.html#the-replace-section
+
+### Testing a bugfix
+
+Let's say you're working with the [`uuid`] crate but while you're working on it
+you discover a bug. You are, however, quite enterprising so you decide to also
+try out to fix the bug! Originally your manifest will look like:
+
+[`uuid`](https://crates.io/crates/uuid)
+
+```toml
+[package]
+name = "my-library"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+uuid = "1.0"
+```
+
+First thing we'll do is to clone the [`uuid` repository][uuid-repository]
+locally via:
+
+```shell
+$ git clone https://github.com/rust-lang-nursery/uuid
+```
+
+Next we'll edit the manifest of `my-library` to contain:
+
+```toml
+[patch.crates-io]
+uuid = { path = "../path/to/uuid" }
+```
+
+Here we declare that we're *patching* the source `crates-io` with a new
+dependency. This will effectively add the local checked out version of `uuid` to
+the crates.io registry for our local project.
+
+Next up we need to ensure that our lock file is updated to use this new version
+of `uuid` so our project uses the locally checked out copy instead of one from
+crates.io. The way `[patch]` works is that it'll load the dependency at
+`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid`
+it'll *also* return the local version.
+
+This means that the version number of the local checkout is significant and will
+affect whether the patch is used. Our manifest declared `uuid = "1.0"` which
+means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution
+algorithm also means that we'll resolve to the maximum version within that
+range. Typically this doesn't matter as the version of the git repository will
+already be greater or match the maximum version published on crates.io, but it's
+important to keep this in mind!
+
+In any case, typically all you need to do now is:
+
+```shell
+$ cargo build
+ Compiling uuid v1.0.0 (file://.../uuid)
+ Compiling my-library v0.1.0 (file://.../my-library)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
+```
+
+And that's it! You're now building with the local version of `uuid` (note the
+`file://` in the build output). If you don't see the `file://` version getting
+built then you may need to run `cargo update -p uuid --precise $version` where
+`$version` is the version of the locally checked out copy of `uuid`.
+
+Once you've fixed the bug you originally found the next thing you'll want to do
+is to likely submit that as a pull request to the `uuid` crate itself. Once
+you've done this then you can also update the `[patch]` section. The listing
+inside of `[patch]` is just like the `[dependencies]` section, so once your pull
+request is merged you could change your `path` dependency to:
+
+```toml
+[patch.crates-io]
+uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
+```
+
+[uuid-repository]: https://github.com/rust-lang-nursery/uuid
+
+### Working with an unpublished minor version
+
+Let's now shift gears a bit from bug fixes to adding features. While working on
+`my-library` you discover that a whole new feature is needed in the `uuid`
+crate. You've implemented this feature, tested it locally above with `[patch]`,
+and submitted a pull request. Let's go over how you continue to use and test it
+before it's actually published.
+
+Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but
+since then the master branch of the git repository has updated to `1.0.1`. This
+branch includes your new feature you submitted previously. To use this
+repository we'll edit our `Cargo.toml` to look like
+
+```toml
+[package]
+name = "my-library"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+uuid = "1.0.1"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
+```
+
+Note that our local dependency on `uuid` has been updated to `1.0.1` as it's
+what we'll actually require once the crate is published. This version doesn't
+exist on crates.io, though, so we provide it with the `[patch]` section of the
+manifest.
+
+Now when our library is built it'll fetch `uuid` from the git repository and
+resolve to 1.0.1 inside the repository instead of trying to download a version
+from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can
+be deleted.
+
+It's also worth nothing that `[patch]` applies *transitively*. Let's say you use
+`my-library` in a larger project, such as:
+
+```toml
+[package]
+name = "my-binary"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+my-library = { git = 'https://example.com/git/my-library' }
+uuid = "1.0"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
+```
+
+Remember that `[patch]` is only applicable at the *top level* so we consumers of
+`my-library` have to repeat the `[patch]` section if necessary. Here, though,
+the new `uuid` crate applies to *both* our dependency on `uuid` and the
+`my-library -> uuid` dependency. The `uuid` crate will be resolved to one
+version for this entire crate graph, 1.0.1, and it'll be pulled from the git
+repository.
+
+### Prepublishing a breaking change
+
+As a final scenario, let's take a look at working with a new major version of a
+crate, typically accompanied with breaking changes. Sticking with our previous
+crates, this means that we're going to be creating version 2.0.0 of the `uuid`
+crate. After we've submitted all changes upstream we can update our manifest for
+`my-library` to look like:
+
+```toml
+[dependencies]
+uuid = "2.0"
+
+[patch.crates-io]
+uuid = { git = "https://github.com/rust-lang-nursery/uuid", branch = "2.0.0" }
+```
+
+And that's it! Like with the previous example the 2.0.0 version doesn't actually
+exist on crates.io but we can still put it in through a git dependency through
+the usage of the `[patch]` section. As a thought exercise let's take another
+look at the `my-binary` manifest from above again as well:
+
+```toml
+[package]
+name = "my-binary"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+my-library = { git = 'https://example.com/git/my-library' }
+uuid = "1.0"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/rust-lang-nursery/uuid', version = '2.0.0' }
+```
+
+Note that this will actually resolve to two versions of the `uuid` crate. The
+`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but
+the `my-library` crate will use the 2.0.0 version of `uuid`. This will allow you
+to gradually roll out breaking changes to a crate through a dependency graph
+without being force to update everything all at once.
+
+### Overriding with local dependencies
+
+Sometimes you're only temporarily working on a crate and you don't want to have
+to modify `Cargo.toml` like with the `[patch]` section above. For this use
+case Cargo offers a much more limited version of overrides called **path
+overrides**.
+
+Path overrides are specified through `.cargo/config` instead of `Cargo.toml`,
+and you can find [more documentation about this configuration][config-docs].
+Inside of `.cargo/config` you'll specify a key called `paths`:
+
+[config-docs]: reference/config.html
+
+```toml
+paths = ["/path/to/uuid"]
+```
+
+This array should be filled with directories that contain a `Cargo.toml`. In
+this instance, we’re just adding `uuid`, so it will be the only one that’s
+overridden. This path can be either absolute or relative to the directory that
+contains the `.cargo` folder.
+
+Path overrides are more restricted than the `[patch]` section, however, in
+that they cannot change the structure of the dependency graph. When a
+path replacement is used then the previous set of dependencies
+must all match exactly to the new `Cargo.toml` specification. For example this
+means that path overrides cannot be used to test out adding a dependency to a
+crate, instead `[patch]` must be used in that situation. As a result usage of a
+path override is typically isolated to quick bug fixes rather than larger
+changes.
+
+Note: using a local configuration to override paths will only work for crates
+that have been published to [crates.io]. You cannot use this feature to tell
+Cargo how to find local unpublished crates.
+
+### Platform specific dependencies
+
+
+Platform-specific dependencies take the same format, but are listed under a
+`target` section. Normally Rust-like `#[cfg]` syntax will be used to define
+these sections:
+
+```toml
+[target.'cfg(windows)'.dependencies]
+winhttp = "0.4.0"
+
+[target.'cfg(unix)'.dependencies]
+openssl = "1.0.1"
+
+[target.'cfg(target_arch = "x86")'.dependencies]
+native = { path = "native/i686" }
+
+[target.'cfg(target_arch = "x86_64")'.dependencies]
+native = { path = "native/x86_64" }
+```
+
+Like with Rust, the syntax here supports the `not`, `any`, and `all` operators
+to combine various cfg name/value pairs. Note that the `cfg` syntax has only
+been available since Cargo 0.9.0 (Rust 1.8.0).
+
+In addition to `#[cfg]` syntax, Cargo also supports listing out the full target
+the dependencies would apply to:
+
+```toml
+[target.x86_64-pc-windows-gnu.dependencies]
+winhttp = "0.4.0"
+
+[target.i686-unknown-linux-gnu.dependencies]
+openssl = "1.0.1"
+```
+
+If you’re using a custom target specification, quote the full path and file
+name:
+
+```toml
+[target."x86_64/windows.json".dependencies]
+winhttp = "0.4.0"
+
+[target."i686/linux.json".dependencies]
+openssl = "1.0.1"
+native = { path = "native/i686" }
+
+[target."x86_64/linux.json".dependencies]
+openssl = "1.0.1"
+native = { path = "native/x86_64" }
+```
+
+### Development dependencies
+
+You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format
+is equivalent to `[dependencies]`:
+
+```toml
+[dev-dependencies]
+tempdir = "0.3"
+```
+
+Dev-dependencies are not used when compiling
+a package for building, but are used for compiling tests, examples, and
+benchmarks.
+
+These dependencies are *not* propagated to other packages which depend on this
+package.
+
+You can also have target-specific development dependencies by using
+`dev-dependencies` in the target section header instead of `dependencies`. For
+example:
+
+```toml
+[target.'cfg(unix)'.dev-dependencies]
+mio = "0.0.1"
+```
+
+[crates.io]: https://crates.io/
+
+### Build dependencies
+
+You can depend on other Cargo-based crates for use in your build scripts.
+Dependencies are declared through the `build-dependencies` section of the
+manifest:
+
+```toml
+[build-dependencies]
+gcc = "0.3"
+```
+
+The build script **does not** have access to the dependencies listed
+in the `dependencies` or `dev-dependencies` section. Build
+dependencies will likewise not be available to the package itself
+unless listed under the `dependencies` section as well. A package
+itself and its build script are built separately, so their
+dependencies need not coincide. Cargo is kept simpler and cleaner by
+using independent dependencies for independent purposes.
+
+### Choosing features
+
+If a package you depend on offers conditional features, you can
+specify which to use:
+
+```toml
+[dependencies.awesome]
+version = "1.3.5"
+default-features = false # do not include the default features, and optionally
+ # cherry-pick individual features
+features = ["secure-password", "civet"]
+```
+
+More information about features can be found in the
+[manifest documentation](reference/manifest.html#the-features-section).
+++ /dev/null
-html {
- background: url("../images/noise.png");
- background-color: #3b6837;
-}
-
-main, #header { width: 900px; }
-
-* {
- box-sizing: border-box;
-}
-
-body {
- display: -webkit-flex;
- display: flex;
- -webkit-flex-direction: column;
- flex-direction: column;
- -webkit-align-items: center;
- align-items: center;
- font-family: sans-serif;
- font-size: 16px;
-}
-
-a { color: #00ac5b; text-decoration: none; }
-a:hover { color: #00793f; }
-
-h1 {
- font-size: 24px;
- margin: 20px 0 10px 0;
- font-weight: bold;
- color: #b64790;
-}
-
-h1 code:not(.highlight) {
- color: #d9a700;
- vertical-align: bottom;
-}
-h1 a, h2 a { color: #b64790; text-decoration: none; }
-h1:hover a, h2:hover a { color: #A03D7E; }
-h1:hover a:after,
-h2:hover a:after { content: '\2002\00a7\2002'; }
-:target { background: rgba(239, 242, 178, 1); padding: 5px; }
-
-h1.title { /* style rustdoc-generated title */
- width: 100%;
- padding: 40px 20px 40px 60px;
- background-color: #edebdd;
- margin-bottom: 20px;
- -webkit-border-radius: 5px;
- -moz-border-radius: 5px;
- -ms-border-radius: 5px;
- border-radius: 5px;
- margin: 0;
- color: #383838;
- font-size: 2em;
- background-image: url(../images/circle-with-i.png);
- background-repeat: no-repeat;
- background-position: 20px center;
-}
-
-h2 {
- font-size: 18px;
- margin: 15px 0 5px 0;
- color: #b64790;
- font-weight: bold;
-}
-
-h2 code:not(.highlight) { color: #d9a700; }
-
-code:not(.highlight) {
- font-family: monospace;
- color: #b64790;
-}
-
-main {
- display: -webkit-flex;
- display: flex;
- -webkit-flex-direction: column;
- flex-direction: column;
-
- width: 100%;
- max-width: 900px;
- margin-bottom: 10px;
-
- background-color: #f9f7ec;
- padding: 15px;
-
- -webkit-border-radius: 10px;
- -moz-border-radius: 10px;
- -ms-border-radius: 10px;
- border-radius: 10px;
- box-shadow: 0px 0px 5px 2px #3b6837;
- border: 5px solid #62865f;
- color: #383838;
-}
-
-main > p:first-child {
- font-weight: 500;
- margin-top: 3px;
- padding-bottom: 15px;
- border-bottom: 1px solid #62865f;
- text-align: center;
-}
-
-main p:first-child a { color: #3b6837; }
-main p:first-child a:hover { color: #62865f; }
-
-main p, main ul {
- /* color: #3b6837; */
- margin: 10px 0;
- line-height: 150%;
-}
-
-main ul { margin-left: 20px; }
-main li { list-style-type: disc; }
-main strong { font-weight: bold; }
-
-img.logo {
- align-self: center;
- margin-bottom: 10px;
-}
-
-pre {
- padding: 10px;
- margin: 10px 0;
- /* border: 1px solid #cad0d0; */
- border-radius: 4px;
- max-width: calc(100vw - 45px);
- overflow-x: auto;
-
- background: #383838 !important;
- color: white;
- padding: 20px;
-
- /* override prism.js styles */
- font-size: 1em !important;
- border: none !important;
- box-shadow: none !important;
- text-shadow: none !important;
-}
-
-pre code {
- text-shadow: none !important;
-}
-
-footer {
- padding: 40px;
- width: 900px;
-}
-footer a {
- color: white;
-}
-footer a:hover {
- color: #e6e6e6;
-}
-footer .sep, #header .sep { color: #284725; }
-footer .sep { margin: 0 10px; }
-#header .sep { margin-left: 10px; }
-
-.headerlink {
- display: none;
- text-decoration: none;
-}
-.fork-me {
- position:absolute;
- top:0;
- right:0;
-}
-
-.token.toml-section { color: #CB4B16; }
-.token.toml-key { color: #268BD2; }
-
-/* Rust code highlighting */
-pre.rust .kw { color: #8959A8; }
-pre.rust .kw-2, pre.rust .prelude-ty { color: #4271AE; }
-pre.rust .number, pre.rust .string { color: #718C00; }
-pre.rust .self, pre.rust .boolval, pre.rust .prelude-val,
-pre.rust .attribute, pre.rust .attribute .ident { color: #C82829; }
-pre.rust .comment { color: #8E908C; }
-pre.rust .doccomment { color: #4D4D4C; }
-pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; }
-pre.rust .lifetime { color: #B76514; }
-code span.s1 { color: #2AA198; }
-
-table th { border-bottom: 1px solid black; }
-table td, table th { padding: 5px 10px; }
-
-#header {
- color: white;
- position: relative;
- height: 100px;
- display: -webkit-flex;
- display: flex;
- -webkit-align-items: center;
- align-items: center;
-}
-#header h1 { font-size: 2em; }
-#header a, #header h1 { color: white; text-decoration: none; }
-#header a:hover { color: #d9d9d9; }
-
-#header input.search {
- border: none;
- color: black;
- outline: 0;
- margin-left: 30px;
- padding: 5px 5px 5px 25px;
- background-image: url(../images/search.png);
- background-repeat: no-repeat;
- background-position: 6px 6px;
- -webkit-border-radius: 15px;
- -moz-border-radius: 15px;
- -ms-border-radius: 15px;
- border-radius: 15px;
-}
-
-#header .nav {
- -webkit-flex-grow: 2;
- flex-grow: 2;
- text-align: right;
-}
-
-button.dropdown, a.dropdown { cursor: pointer; }
-button.dropdown .arrow, a.dropdown .arrow {
- font-size: 50%; display: inline-block; vertical-align: middle;
-}
-button.dropdown .arrow::after, a.dropdown .arrow::after { content: "▼"; }
-button.active.dropdown .arrow::after, a.active.dropdown .arrow::after {
- content: "▲";
-}
-
-button {
- background: none;
- outline: 0;
- border: 0;
- padding: 10px;
- color: white;
-}
-
-button.active {
- background:#2a4f27;
- box-shadow:inset -2px 2px 4px 0 #243d26
-}
-
-ul.dropdown {
- display: none;
- visibility: none;
- position: absolute;
- top: 100%;
- right: 0;
- width: 100%;
- min-width: 150px;
- opacity: 0;
- margin: 0;
- text-align: left;
- padding: 0;
- background: white;
- border: 1px solid #d5d3cb;
- list-style: none;
- z-index: 10;
- -webkit-border-radius: 5px;
- -moz-border-radius: 5px;
- -ms-border-radius: 5px;
- border-radius: 5px;
-}
-
-ul.dropdown li a {
- font-size: 90%;
- width: 100%;
- display: inline-block;
- padding: 8px 10px;
- text-decoration: none;
- color: #383838 !important;
-}
-
-ul.dropdown li a:hover {
- background: #5e5e5e;
- color: white !important;
-}
-ul.dropdown li.last { border-top: 1px solid #d5d3cb; }
-ul.dropdown.open {
- display: block;
- visibility: visible;
- opacity: 1;
-}
-.dropdown-container {
- display: inline-block;
- position: relative;
-}
-
-p > img {
- max-width: 100%;
-}
+++ /dev/null
-/*! normalize.css v2.0.1 | MIT License | git.io/normalize */
-
-/* ==========================================================================
- HTML5 display definitions
- ========================================================================== */
-
-/*
- * Corrects `block` display not defined in IE 8/9.
- */
-
-article,
-aside,
-details,
-figcaption,
-figure,
-footer,
-header,
-hgroup,
-nav,
-section,
-summary {
- display: block;
-}
-
-/*
- * Corrects `inline-block` display not defined in IE 8/9.
- */
-
-audio,
-canvas,
-video {
- display: inline-block;
-}
-
-/*
- * Prevents modern browsers from displaying `audio` without controls.
- * Remove excess height in iOS 5 devices.
- */
-
-audio:not([controls]) {
- display: none;
- height: 0;
-}
-
-/*
- * Addresses styling for `hidden` attribute not present in IE 8/9.
- */
-
-[hidden] {
- display: none;
-}
-
-/* ==========================================================================
- Base
- ========================================================================== */
-
-/*
- * 1. Sets default font family to sans-serif.
- * 2. Prevents iOS text size adjust after orientation change, without disabling
- * user zoom.
- */
-
-html {
- font-family: sans-serif; /* 1 */
- -webkit-text-size-adjust: 100%; /* 2 */
- -ms-text-size-adjust: 100%; /* 2 */
-}
-
-/*
- * Removes default margin.
- */
-
-body {
- margin: 0;
-}
-
-/* ==========================================================================
- Links
- ========================================================================== */
-
-/*
- * Addresses `outline` inconsistency between Chrome and other browsers.
- */
-
-a:focus {
- outline: thin dotted;
-}
-
-/*
- * Improves readability when focused and also mouse hovered in all browsers.
- */
-
-a:active,
-a:hover {
- outline: 0;
-}
-
-/* ==========================================================================
- Typography
- ========================================================================== */
-
-/*
- * Addresses `h1` font sizes within `section` and `article` in Firefox 4+,
- * Safari 5, and Chrome.
- */
-
-h1 {
- font-size: 2em;
-}
-
-/*
- * Addresses styling not present in IE 8/9, Safari 5, and Chrome.
- */
-
-abbr[title] {
- border-bottom: 1px dotted;
-}
-
-/*
- * Addresses style set to `bolder` in Firefox 4+, Safari 5, and Chrome.
- */
-
-b,
-strong {
- font-weight: bold;
-}
-
-/*
- * Addresses styling not present in Safari 5 and Chrome.
- */
-
-dfn {
- font-style: italic;
-}
-
-/*
- * Addresses styling not present in IE 8/9.
- */
-
-mark {
- background: #ff0;
- color: #000;
-}
-
-
-/*
- * Corrects font family set oddly in Safari 5 and Chrome.
- */
-
-code,
-kbd,
-pre,
-samp {
- font-family: monospace, serif;
- font-size: 1em;
-}
-
-/*
- * Improves readability of pre-formatted text in all browsers.
- */
-
-pre {
- white-space: pre;
- white-space: pre-wrap;
- word-wrap: break-word;
-}
-
-/*
- * Sets consistent quote types.
- */
-
-q {
- quotes: "\201C" "\201D" "\2018" "\2019";
-}
-
-/*
- * Addresses inconsistent and variable font size in all browsers.
- */
-
-small {
- font-size: 80%;
-}
-
-/*
- * Prevents `sub` and `sup` affecting `line-height` in all browsers.
- */
-
-sub,
-sup {
- font-size: 75%;
- line-height: 0;
- position: relative;
- vertical-align: baseline;
-}
-
-sup {
- top: -0.5em;
-}
-
-sub {
- bottom: -0.25em;
-}
-
-/* ==========================================================================
- Embedded content
- ========================================================================== */
-
-/*
- * Removes border when inside `a` element in IE 8/9.
- */
-
-img {
- border: 0;
-}
-
-/*
- * Corrects overflow displayed oddly in IE 9.
- */
-
-svg:not(:root) {
- overflow: hidden;
-}
-
-/* ==========================================================================
- Figures
- ========================================================================== */
-
-/*
- * Addresses margin not present in IE 8/9 and Safari 5.
- */
-
-figure {
- margin: 0;
-}
-
-/* ==========================================================================
- Forms
- ========================================================================== */
-
-/*
- * Define consistent border, margin, and padding.
- */
-
-fieldset {
- border: 1px solid #c0c0c0;
- margin: 0 2px;
- padding: 0.35em 0.625em 0.75em;
-}
-
-/*
- * 1. Corrects color not being inherited in IE 8/9.
- * 2. Remove padding so people aren't caught out if they zero out fieldsets.
- */
-
-legend {
- border: 0; /* 1 */
- padding: 0; /* 2 */
-}
-
-/*
- * 1. Corrects font family not being inherited in all browsers.
- * 2. Corrects font size not being inherited in all browsers.
- * 3. Addresses margins set differently in Firefox 4+, Safari 5, and Chrome
- */
-
-button,
-input,
-select,
-textarea {
- font-family: inherit; /* 1 */
- font-size: 100%; /* 2 */
- margin: 0; /* 3 */
-}
-
-/*
- * Addresses Firefox 4+ setting `line-height` on `input` using `!important` in
- * the UA stylesheet.
- */
-
-button,
-input {
- line-height: normal;
-}
-
-/*
- * 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
- * and `video` controls.
- * 2. Corrects inability to style clickable `input` types in iOS.
- * 3. Improves usability and consistency of cursor style between image-type
- * `input` and others.
- */
-
-button,
-html input[type="button"], /* 1 */
-input[type="reset"],
-input[type="submit"] {
- -webkit-appearance: button; /* 2 */
- cursor: pointer; /* 3 */
-}
-
-/*
- * Re-set default cursor for disabled elements.
- */
-
-button[disabled],
-input[disabled] {
- cursor: default;
-}
-
-/*
- * 1. Addresses box sizing set to `content-box` in IE 8/9.
- * 2. Removes excess padding in IE 8/9.
- */
-
-input[type="checkbox"],
-input[type="radio"] {
- box-sizing: border-box; /* 1 */
- padding: 0; /* 2 */
-}
-
-/*
- * 1. Addresses `appearance` set to `searchfield` in Safari 5 and Chrome.
- * 2. Addresses `box-sizing` set to `border-box` in Safari 5 and Chrome
- * (include `-moz` to future-proof).
- */
-
-input[type="search"] {
- -webkit-appearance: textfield; /* 1 */
- -moz-box-sizing: content-box;
- -webkit-box-sizing: content-box; /* 2 */
- box-sizing: content-box;
-}
-
-/*
- * Removes inner padding and search cancel button in Safari 5 and Chrome
- * on OS X.
- */
-
-input[type="search"]::-webkit-search-cancel-button,
-input[type="search"]::-webkit-search-decoration {
- -webkit-appearance: none;
-}
-
-/*
- * Removes inner padding and border in Firefox 4+.
- */
-
-button::-moz-focus-inner,
-input::-moz-focus-inner {
- border: 0;
- padding: 0;
-}
-
-/*
- * 1. Removes default vertical scrollbar in IE 8/9.
- * 2. Improves readability and alignment in all browsers.
- */
-
-textarea {
- overflow: auto; /* 1 */
- vertical-align: top; /* 2 */
-}
-
-/* ==========================================================================
- Tables
- ========================================================================== */
-
-/*
- * Remove most spacing between table cells.
- */
-
-table {
- border-collapse: collapse;
- border-spacing: 0;
-}
\ No newline at end of file
+++ /dev/null
-/* http://prismjs.com/download.html?themes=prism-twilight&languages=markup+css+clike+javascript */
-/**
- * prism.js Twilight theme
- * Based (more or less) on the Twilight theme originally of Textmate fame.
- * @author Remy Bach
- */
-code[class*="language-"],
-pre[class*="language-"] {
- color: white;
- direction: ltr;
- font-family: Consolas, Monaco, 'Andale Mono', monospace;
- text-align: left;
- text-shadow: 0 -.1em .2em black;
- white-space: pre;
- word-spacing: normal;
- word-break: normal;
- line-height: 1.5;
-
- -moz-tab-size: 4;
- -o-tab-size: 4;
- tab-size: 4;
-
- -webkit-hyphens: none;
- -moz-hyphens: none;
- -ms-hyphens: none;
- hyphens: none;
-}
-
-pre[class*="language-"],
-:not(pre) > code[class*="language-"] {
- background: hsl(0, 0%, 8%); /* #141414 */
-}
-
-/* Code blocks */
-pre[class*="language-"] {
- border-radius: .5em;
- border: .3em solid hsl(0, 0%, 33%); /* #282A2B */
- box-shadow: 1px 1px .5em black inset;
- margin: .5em 0;
- overflow: auto;
- padding: 1em;
-}
-
-pre[class*="language-"]::selection {
- /* Safari */
- background: hsl(200, 4%, 16%); /* #282A2B */
-}
-
-pre[class*="language-"]::selection {
- /* Firefox */
- background: hsl(200, 4%, 16%); /* #282A2B */
-}
-
-/* Text Selection colour */
-pre[class*="language-"]::-moz-selection, pre[class*="language-"] ::-moz-selection,
-code[class*="language-"]::-moz-selection, code[class*="language-"] ::-moz-selection {
- text-shadow: none;
- background: hsla(0, 0%, 93%, 0.15); /* #EDEDED */
-}
-
-pre[class*="language-"]::selection, pre[class*="language-"] ::selection,
-code[class*="language-"]::selection, code[class*="language-"] ::selection {
- text-shadow: none;
- background: hsla(0, 0%, 93%, 0.15); /* #EDEDED */
-}
-
-/* Inline code */
-:not(pre) > code[class*="language-"] {
- border-radius: .3em;
- border: .13em solid hsl(0, 0%, 33%); /* #545454 */
- box-shadow: 1px 1px .3em -.1em black inset;
- padding: .15em .2em .05em;
-}
-
-.token.comment,
-.token.prolog,
-.token.doctype,
-.token.cdata {
- color: hsl(0, 0%, 47%); /* #777777 */
-}
-
-.token.punctuation {
- opacity: .7;
-}
-
-.namespace {
- opacity: .7;
-}
-
-.token.tag,
-.token.boolean,
-.token.number,
-.token.deleted {
- color: hsl(14, 58%, 55%); /* #CF6A4C */
-}
-
-.token.keyword,
-.token.property,
-.token.selector,
-.token.constant,
-.token.symbol,
-.token.builtin {
- color: hsl(53, 89%, 79%); /* #F9EE98 */
-}
-
-.token.attr-name,
-.token.attr-value,
-.token.string,
-.token.char,
-.token.operator,
-.token.entity,
-.token.url,
-.language-css .token.string,
-.style .token.string,
-.token.variable,
-.token.inserted {
- color: hsl(76, 21%, 52%); /* #8F9D6A */
-}
-
-.token.atrule {
- color: hsl(218, 22%, 55%); /* #7587A6 */
-}
-
-.token.regex,
-.token.important {
- color: hsl(42, 75%, 65%); /* #E9C062 */
-}
-
-.token.important {
- font-weight: bold;
-}
-
-.token.entity {
- cursor: help;
-}
-
-pre[data-line] {
- padding: 1em 0 1em 3em;
- position: relative;
-}
-
-/* Markup */
-.language-markup .token.tag,
-.language-markup .token.attr-name,
-.language-markup .token.punctuation {
- color: hsl(33, 33%, 52%); /* #AC885B */
-}
-
-/* Make the tokens sit above the line highlight so the colours don't look faded. */
-.token {
- position: relative;
- z-index: 1;
-}
-
-.line-highlight {
- background: -moz-linear-gradient(left, hsla(0, 0%, 33%, .1) 70%, hsla(0, 0%, 33%, 0)); /* #545454 */
- background: -o-linear-gradient(left, hsla(0, 0%, 33%, .1) 70%, hsla(0, 0%, 33%, 0)); /* #545454 */
- background: -webkit-linear-gradient(left, hsla(0, 0%, 33%, .1) 70%, hsla(0, 0%, 33%, 0)); /* #545454 */
- background: hsla(0, 0%, 33%, 0.25); /* #545454 */
- background: linear-gradient(left, hsla(0, 0%, 33%, .1) 70%, hsla(0, 0%, 33%, 0)); /* #545454 */
- border-bottom: 1px dashed hsl(0, 0%, 33%); /* #545454 */
- border-top: 1px dashed hsl(0, 0%, 33%); /* #545454 */
- left: 0;
- line-height: inherit;
- margin-top: 0.75em; /* Same as .prism’s padding-top */
- padding: inherit 0;
- pointer-events: none;
- position: absolute;
- right: 0;
- white-space: pre;
- z-index: 0;
-}
-
-.line-highlight:before,
-.line-highlight[data-end]:after {
- background-color: hsl(215, 15%, 59%); /* #8794A6 */
- border-radius: 999px;
- box-shadow: 0 1px white;
- color: hsl(24, 20%, 95%); /* #F5F2F0 */
- content: attr(data-start);
- font: bold 65%/1.5 sans-serif;
- left: .6em;
- min-width: 1em;
- padding: 0 .5em;
- position: absolute;
- text-align: center;
- text-shadow: none;
- top: .4em;
- vertical-align: .3em;
-}
-
-.line-highlight[data-end]:after {
- bottom: .4em;
- content: attr(data-end);
- top: auto;
-}
-
projects / cargo.git / commitdiff
