mirror of
https://github.com/rust-lang/cargo.git
synced 2025-09-28 11:20:36 +00:00
Auto merge of #4455 - behnam:book-enh, r=alexcrichton
[doc/book] Add introduction page and other enhancements Preview: http://code.behnam.es/rust-cargo/book/ * Reorganize files to use folders instead of numbered files. This will allow us to add new sections and pages without breaking a numbering system or the URLs. * Rename "Cargo In Depth" to "Cargo Reference", as those pages are considered *the* reference for cargo behaviors. * Add `introduction.md`, as the landing page with the book title and Cargo logo on top. * Expand `installation.md`: Import install text and links from <https://crates.io/install>, as we want to drop that page and redirect it to here. (See <https://github.com/rust-lang/crates.io/issues/1029>) * Sync `SUMMARY.md` titles (and sub-pages lists in section pages) with page titles and fix some wordings and casings. * Expand Introduction and section pages with some intro text. * Set lang for some of the code blocks. * Add `book.toml` to get the title in HTML head title, etc. Tracker: <https://github.com/rust-lang/cargo/issues/4040>
This commit is contained in:
bors
commit
61ca3022bc
@ -1,13 +1,13 @@
|
||||
build-script.md book/src/03-05-build-scripts.md
|
||||
config.md book/src/03-03-config.md
|
||||
crates-io.md book/src/03-06-crates-io.md
|
||||
environment-variables.md book/src/03-04-environment-variables.md
|
||||
external-tools.md book/src/03-09-external-tools.md
|
||||
index.md book/src/SUMMARY.md book/src/getting-started.md book/src/getting-started/*.md
|
||||
guide.md book/src/guide.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/crates-io.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
|
||||
policies.md book/src/reference/policies.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
|
||||
guide.md book/src/guide.md book/src/02-*.md
|
||||
index.md book/src/SUMMARY.md book/src/01-*.md
|
||||
manifest.md book/src/03-02-manifest.md
|
||||
pkgid-spec.md book/src/03-07-pkgid-spec.md
|
||||
policies.md book/src/03-10-policies.md
|
||||
source-replacement.md book/src/03-08-source-replacement.md
|
||||
specifying-dependencies.md book/src/03-01-specifying-dependencies.md
|
||||
|
||||
@ -7,7 +7,7 @@ Building the book requires [mdBook]. To get it:
|
||||
|
||||
[mdBook]: https://github.com/azerupi/mdBook
|
||||
|
||||
```bash
|
||||
```shell
|
||||
$ cargo install mdbook
|
||||
```
|
||||
|
||||
@ -15,7 +15,7 @@ $ cargo install mdbook
|
||||
|
||||
To build the book:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
$ mdbook build
|
||||
```
|
||||
|
||||
@ -23,7 +23,7 @@ The output will be in the `book` subdirectory. To check it out, open it in
|
||||
your web browser.
|
||||
|
||||
_Firefox:_
|
||||
```bash
|
||||
```shell
|
||||
$ firefox book/index.html # Linux
|
||||
$ open -a "Firefox" book/index.html # OS X
|
||||
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
|
||||
@ -31,7 +31,7 @@ $ start firefox.exe .\book\index.html # Windows (Cmd)
|
||||
```
|
||||
|
||||
_Chrome:_
|
||||
```bash
|
||||
```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)
|
||||
|
||||
2
src/doc/book/book.toml
Normal file
2
src/doc/book/book.toml
Normal file
@ -0,0 +1,2 @@
|
||||
title = "The Cargo Manual"
|
||||
author = "Alex Crichton, Steve Klabnik and Carol Nichols, with Contributions from the Rust Community"
|
||||
@ -1,21 +0,0 @@
|
||||
## Installation
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
This will get you the current stable release of Rust for your platform along
|
||||
with the latest Cargo.
|
||||
|
||||
If you are on Windows, you can directly download the latest stable Rust and nightly Cargo:
|
||||
|
||||
- [Rust (32-bit)](https://static.rust-lang.org/dist/rust-1.17.0-i686-pc-windows-gnu.msi)
|
||||
- [Cargo (32-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)
|
||||
|
||||
- [Rust (64-bit)](https://static.rust-lang.org/dist/rust-1.17.0-x86_64-pc-windows-gnu.msi)
|
||||
- [Cargo (64-bit)](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)
|
||||
|
||||
Alternatively, you can [build Cargo from source](https://github.com/rust-lang/cargo#compiling-from-source).
|
||||
@ -1,140 +0,0 @@
|
||||
## 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](03-02-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
|
||||
[root]
|
||||
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](03-07-pkgid-spec.html) and `rand` is just a short
|
||||
specification.
|
||||
@ -1,29 +1,31 @@
|
||||
# Summary
|
||||
|
||||
[Introduction](introduction.md)
|
||||
|
||||
* [Getting Started](getting-started.md)
|
||||
* [Installation](01-01-installation.md)
|
||||
* [First Steps with Cargo](01-02-first-steps.md)
|
||||
* [Installation](getting-started/installation.md)
|
||||
* [First Steps with Cargo](getting-started/first-steps.md)
|
||||
|
||||
* [Cargo Guide](guide.md)
|
||||
* [Why Cargo Exists](02-01-why-cargo-exists.md)
|
||||
* [Creating a New Project](02-02-creating-a-new-project.md)
|
||||
* [Working on an Existing Project](02-03-working-on-an-existing-project.md)
|
||||
* [Dependencies](02-04-dependencies.md)
|
||||
* [Project Layout](02-05-project-layout.md)
|
||||
* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.md)
|
||||
* [Tests](02-07-tests.md)
|
||||
* [Continuous Integration](02-08-continuous-integration.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 In Depth](cargo-in-depth.md)
|
||||
* [Specifying Dependencies](03-01-specifying-dependencies.md)
|
||||
* [Cargo.toml Format](03-02-manifest.md)
|
||||
* [Configuration](03-03-config.md)
|
||||
* [Environment Variables](03-04-environment-variables.md)
|
||||
* [Build Scripts](03-05-build-scripts.md)
|
||||
* [Publishing on crates.io](03-06-crates-io.md)
|
||||
* [Package ID specs](03-07-pkgid-spec.md)
|
||||
* [Source Replacement](03-08-source-replacement.md)
|
||||
* [External Tools](03-09-external-tools.md)
|
||||
* [Policies](03-10-policies.md)
|
||||
* [Cargo Reference](reference.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/crates-io.md)
|
||||
* [Package ID Specifications](reference/pkgid-spec.md)
|
||||
* [Source Replacement](reference/source-replacement.md)
|
||||
* [External Tools](reference/external-tools.md)
|
||||
* [Crates.io Package Policies](reference/policies.md)
|
||||
|
||||
* [FAQ](faq.md)
|
||||
|
||||
@ -1,18 +0,0 @@
|
||||
## Cargo In Depth
|
||||
|
||||
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](03-06-crates-io.html)
|
||||
* [Reading about all the possible ways of specifying dependencies](03-01-specifying-dependencies.html)
|
||||
* [Learning more details about what you can specify in your `Cargo.toml` manifest](03-02-manifest.html)
|
||||
* [Specifying Dependencies](03-01-specifying-dependencies.html)
|
||||
* [Cargo.toml Format](03-02-manifest.html)
|
||||
* [Configuration](03-03-config.html)
|
||||
* [Environment Variables](03-04-environment-variables.html)
|
||||
* [Build Scripts](03-05-build-scripts.html)
|
||||
* [Publishing on crates.io](03-06-crates-io.html)
|
||||
* [Package ID specs](03-07-pkgid-spec.html)
|
||||
* [Source Replacement](03-08-source-replacement.html)
|
||||
* [External Tools](03-09-external-tools.html)
|
||||
* [Policies](03-10-policies.html)
|
||||
@ -50,7 +50,7 @@ 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](03-05-build-scripts.html)
|
||||
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.
|
||||
@ -74,7 +74,7 @@ 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]: 03-02-manifest.html#the-dependencies-section
|
||||
[target-deps]: reference/manifest.html#the-dependencies-section
|
||||
|
||||
In the longer-term, we’re looking at ways to conveniently cross-compile
|
||||
projects using Cargo.
|
||||
@ -83,7 +83,7 @@ projects using Cargo.
|
||||
|
||||
We support environments through the use of [profiles][profile] to support:
|
||||
|
||||
[profile]: 03-02-manifest.html#the-profile-sections
|
||||
[profile]: reference/manifest.html#the-profile-sections
|
||||
|
||||
* environment-specific flags (like `-g --opt-level=0` for development
|
||||
and `--opt-level=3` for production).
|
||||
@ -190,4 +190,4 @@ shouldn't be necessary.
|
||||
For more information about vendoring, see documentation on [source
|
||||
replacement][replace].
|
||||
|
||||
[replace]: 03-08-source-replacement.html
|
||||
[replace]: reference/source-replacement.html
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
## Getting Started
|
||||
|
||||
* [Installation](01-01-installation.html)
|
||||
* [First steps with Cargo](01-02-first-steps.html)
|
||||
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)
|
||||
|
||||
@ -36,7 +36,7 @@ needs to compile your project.
|
||||
|
||||
Here’s what’s in `src/main.rs`:
|
||||
|
||||
```
|
||||
```rust
|
||||
fn main() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
@ -65,6 +65,6 @@ $ cargo run
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
## Going further
|
||||
### Going further
|
||||
|
||||
For more details on using Cargo, check out the [Cargo Guide](guide.html)
|
||||
38
src/doc/book/src/getting-started/installation.md
Normal file
38
src/doc/book/src/getting-started/installation.md
Normal file
@ -0,0 +1,38 @@
|
||||
## 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
|
||||
@ -1,13 +1,13 @@
|
||||
## 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.
|
||||
This guide will give you all that you need to know about how to use Cargo to
|
||||
develop Rust projects.
|
||||
|
||||
* [Why Cargo exists](02-01-why-cargo-exists.html)
|
||||
* [Creating a new project](02-02-creating-a-new-project.html)
|
||||
* [Working on an existing Cargo project](02-03-working-on-an-existing-project.html)
|
||||
* [Dependencies](02-04-dependencies.html)
|
||||
* [Project layout](02-05-project-layout.html)
|
||||
* [Cargo.toml vs Cargo.lock](02-06-cargo-toml-vs-cargo-lock.html)
|
||||
* [Tests](02-07-tests.html)
|
||||
* [Continuous Integration](02-08-continuous-integration.html)
|
||||
* [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)
|
||||
|
||||
@ -82,7 +82,6 @@ dependencies = [
|
||||
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
|
||||
@ -100,5 +99,5 @@ $ 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](03-07-pkgid-spec.html) and `rand` is just a short
|
||||
[Package ID Specification](reference/pkgid-spec.html) and `rand` is just a short
|
||||
specification.
|
||||
@ -39,7 +39,7 @@ needs to compile your project.
|
||||
|
||||
Here’s what’s in `src/main.rs`:
|
||||
|
||||
```
|
||||
```rust
|
||||
fn main() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
@ -20,7 +20,7 @@ time = "0.1.12"
|
||||
```
|
||||
|
||||
The version string is a [semver] version requirement. The [specifying
|
||||
dependencies](03-01-specifying-dependencies.html) docs have more information about
|
||||
dependencies](reference/specifying-dependencies.html) docs have more information about
|
||||
the options you have here.
|
||||
|
||||
[semver]: https://github.com/steveklabnik/semver#requirements
|
||||
35
src/doc/book/src/guide/project-layout.md
Normal file
35
src/doc/book/src/guide/project-layout.md
Normal file
@ -0,0 +1,35 @@
|
||||
## 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).
|
||||
28
src/doc/book/src/introduction.md
Normal file
28
src/doc/book/src/introduction.md
Normal file
@ -0,0 +1,28 @@
|
||||
# The Cargo Manual
|
||||
|
||||
|
||||
|
||||
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 *package registry*.
|
||||
|
||||
|
||||
### Sections
|
||||
|
||||
**[Getting Started](getting-started.html)**
|
||||
|
||||
To get started with Cargo, install Cargo (and Rust) and set up your first crate.
|
||||
|
||||
**[Cargo Guide](guide.html)**
|
||||
|
||||
The guide will give you all you need to know about how to use Cargo to develop
|
||||
Rust projects.
|
||||
|
||||
**[Cargo Reference](reference.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/
|
||||
17
src/doc/book/src/reference.md
Normal file
17
src/doc/book/src/reference.md
Normal file
@ -0,0 +1,17 @@
|
||||
## 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/crates-io.html)
|
||||
* [Package ID Specifications](reference/pkgid-spec.html)
|
||||
* [Source Replacement](reference/source-replacement.html)
|
||||
* [External Tools](reference/external-tools.html)
|
||||
* [Crates.io Package Policies](reference/policies.html)
|
||||
@ -1,4 +1,4 @@
|
||||
## Build Script Support
|
||||
## 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
|
||||
@ -40,7 +40,7 @@ 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]: 03-04-environment-variables.html
|
||||
[env]: reference/environment-variables.html
|
||||
|
||||
### Outputs of the Build Script
|
||||
|
||||
@ -49,7 +49,7 @@ All the lines printed to stdout by a build script are written to a file like
|
||||
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:
|
||||
|
||||
```notrust
|
||||
```shell
|
||||
# specially recognized by Cargo
|
||||
cargo:rustc-link-lib=static=foo
|
||||
cargo:rustc-link-search=native=/path/to/foo
|
||||
@ -184,7 +184,7 @@ 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](03-03-config.html).
|
||||
Cargo [configuration location](reference/config.html).
|
||||
|
||||
```toml
|
||||
[target.x86_64-unknown-linux-gnu.foo]
|
||||
@ -212,7 +212,7 @@ library call as part of the build script.
|
||||
|
||||
First, let’s take a look at the directory structure of this package:
|
||||
|
||||
```notrust
|
||||
```shell
|
||||
.
|
||||
├── Cargo.toml
|
||||
├── build.rs
|
||||
@ -298,7 +298,7 @@ a Rust library which calls into C to print “Hello, World!”.
|
||||
|
||||
Like above, let’s first take a look at the project layout:
|
||||
|
||||
```notrust
|
||||
```shell
|
||||
.
|
||||
├── Cargo.toml
|
||||
├── build.rs
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
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](03-02-manifest.html).
|
||||
manifest, see the [manifest format](reference/manifest.html).
|
||||
|
||||
### Hierarchical structure
|
||||
|
||||
@ -134,4 +134,4 @@ environment variables.
|
||||
In addition to the system above, Cargo recognizes a few other specific
|
||||
[environment variables][env].
|
||||
|
||||
[env]: 03-04-environment-variables.html
|
||||
[env]: reference/environment-variables.html
|
||||
@ -16,7 +16,7 @@ account (required for now). After this, visit your [Account
|
||||
Settings](https://crates.io/me) page and run the `cargo login` command
|
||||
specified.
|
||||
|
||||
```notrust
|
||||
```shell
|
||||
$ cargo login abcdefghijklmnopqrstuvwxyz012345
|
||||
```
|
||||
|
||||
@ -37,7 +37,7 @@ The next step is to package up your crate into a format that can be uploaded to
|
||||
our entire crate and package it all up into a `*.crate` file in the
|
||||
`target/package` directory.
|
||||
|
||||
```notrust
|
||||
```shell
|
||||
$ cargo package
|
||||
```
|
||||
|
||||
@ -87,7 +87,7 @@ 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
|
||||
```shell
|
||||
$ cargo publish
|
||||
```
|
||||
|
||||
@ -95,14 +95,14 @@ 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](03-02-manifest.html#package-metadata) to ensure your crate can be
|
||||
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](03-02-manifest.html#the-version-field). Then optionally run `cargo package` if
|
||||
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.
|
||||
|
||||
@ -119,7 +119,7 @@ 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
|
||||
```shell
|
||||
$ cargo yank --vers 1.0.1
|
||||
$ cargo yank --vers 1.0.1 --undo
|
||||
```
|
||||
@ -142,7 +142,7 @@ 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
|
||||
```shell
|
||||
$ cargo owner --add my-buddy
|
||||
$ cargo owner --remove my-buddy
|
||||
$ cargo owner --add github:rust-lang:owners
|
||||
@ -32,7 +32,7 @@ system:
|
||||
Note that Cargo will also read environment variables for `.cargo/config`
|
||||
configuration values, as described in [that documentation][config-env]
|
||||
|
||||
[config-env]: 03-03-config.html#environment-variables
|
||||
[config-env]: reference/config.html#environment-variables
|
||||
|
||||
### Environment variables Cargo sets for crates
|
||||
|
||||
@ -40,7 +40,7 @@ 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");
|
||||
```
|
||||
|
||||
@ -66,7 +66,7 @@ Cargo sets several environment variables when build scripts are run. Because the
|
||||
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();
|
||||
```
|
||||
@ -117,8 +117,8 @@ let out_dir = env::var("OUT_DIR").unwrap();
|
||||
resolved to use, passed to the build script so it might
|
||||
use it as well.
|
||||
|
||||
[links]: 03-05-build-scripts.html#the-links-manifest-key
|
||||
[profile]: 03-02-manifest.html#the-profile-sections
|
||||
[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
|
||||
|
||||
@ -1,5 +1,8 @@
|
||||
## 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]`.
|
||||
@ -34,7 +37,7 @@ 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]: 03-05-build-scripts.html
|
||||
[1]: reference/build-scripts.html
|
||||
|
||||
```toml
|
||||
[package]
|
||||
@ -246,7 +249,7 @@ assets = "path/to/static"
|
||||
|
||||
### Dependency sections
|
||||
|
||||
See the [specifying dependencies page](03-01-specifying-dependencies.html) for
|
||||
See the [specifying dependencies page](reference/specifying-dependencies.html) for
|
||||
information on the `[dependencies]`, `[dev-dependencies]`,
|
||||
`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
|
||||
|
||||
@ -414,7 +417,7 @@ 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"
|
||||
```
|
||||
|
||||
@ -532,7 +535,7 @@ Your project can optionally contain folders named `examples`, `tests`, and
|
||||
`benches`, which Cargo will treat as containing examples,
|
||||
integration tests, and benchmarks respectively.
|
||||
|
||||
```notrust
|
||||
```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
|
||||
@ -728,7 +731,7 @@ technical specification of this feature. Note that the `[patch]` feature will
|
||||
first become available in Rust 1.20, set to be released on 2017-08-31.
|
||||
|
||||
[RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
|
||||
[replace]: 03-01-specifying-dependencies.html#overriding-dependencies
|
||||
[replace]: reference/specifying-dependencies.html#overriding-dependencies
|
||||
|
||||
### The `[replace]` Section
|
||||
|
||||
@ -742,7 +745,7 @@ other copies. The syntax is similar to the `[dependencies]` section:
|
||||
```
|
||||
|
||||
Each key in the `[replace]` table is a [package id
|
||||
specification](03-07-pkgid-spec.html) which allows arbitrarily choosing a node in the
|
||||
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
|
||||
@ -1,4 +1,4 @@
|
||||
## Crates.io package policies
|
||||
## Crates.io Package Policies
|
||||
|
||||
In general, these policies are guidelines. Problems are often contextual, and
|
||||
exceptional circumstances sometimes require exceptional measures. We plan to
|
||||
@ -1,11 +1,11 @@
|
||||
## Replacing sources
|
||||
## 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]: 03-03-config.html
|
||||
[config]: reference/config.html
|
||||
|
||||
```toml
|
||||
# The `source` table is where all keys related to source-replacement
|
||||
@ -49,7 +49,7 @@ 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]: 03-02-manifest.html#the-replace-section
|
||||
[replace-section]: reference/manifest.html#the-replace-section
|
||||
|
||||
### Configuration
|
||||
|
||||
@ -194,8 +194,8 @@ 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]: 03-02-manifest.html#the-patch-section
|
||||
[replace-section]: 03-02-manifest.html#the-replace-section
|
||||
[patch-section]: reference/manifest.html#the-patch-section
|
||||
[replace-section]: reference/manifest.html#the-replace-section
|
||||
|
||||
### Testing a bugfix
|
||||
|
||||
@ -523,4 +523,4 @@ features = ["secure-password", "civet"]
|
||||
```
|
||||
|
||||
More information about features can be found in the
|
||||
[manifest documentation](03-02-manifest.html#the-features-section).
|
||||
[manifest documentation](reference/manifest.html#the-features-section).
|
||||
@ -57,7 +57,7 @@ needs to compile your project.
|
||||
|
||||
Here’s what’s in `src/main.rs`:
|
||||
|
||||
```
|
||||
```rust
|
||||
fn main() {
|
||||
println!("Hello, world!");
|
||||
}
|
||||
@ -201,7 +201,7 @@ 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;
|
||||
@ -339,7 +339,6 @@ dependencies = [
|
||||
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
|
||||
|
||||
@ -1,21 +1,41 @@
|
||||
% 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
|
||||
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
|
||||
```
|
||||
|
||||
This will get you the current stable release of Rust for your platform along
|
||||
with the latest Cargo.
|
||||
After this, you can use the `rustup` command to also install `beta` or `nightly`
|
||||
channels for Rust and Cargo.
|
||||
|
||||
If you are on Windows, you can directly download the latest 32bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-i686-pc-windows-gnu.msi)
|
||||
and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-windows-gnu.tar.gz)) or 64bit ([Rust](https://static.rust-lang.org/dist/rust-1.0.0-x86_64-pc-windows-gnu.msi) and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-x86_64-pc-windows-gnu.tar.gz)) Rust stable releases or Cargo nightlies.
|
||||
### Install Nightly Cargo
|
||||
|
||||
Alternatively, you can build Cargo from source.
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user