Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Update language regarding repository vs package root #4375

Merged
merged 2 commits into from
Aug 8, 2017
Merged

[docs] Update language regarding repository vs package root #4375

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4518d89
[docs] Update language regarding repository vs package root
behnam Aug 7, 2017
e774367
[docs] Wrap long lines
behnam Aug 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions src/doc/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ 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.
* 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
Expand Down Expand Up @@ -89,7 +90,8 @@ Hello, world!</code></pre>
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:
Once you’re ready for release, you can use `cargo build --release` to compile
your files with optimizations turned on:

<pre><code class="language-shell"><span class="gp">$</span> cargo build --release
<span style="font-weight: bold"
Expand Down Expand Up @@ -232,12 +234,14 @@ Cargo project:
└── some-integration-tests.rs
```

* `Cargo.toml` and `Cargo.lock` are stored in the root of your project.
* `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).
* 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.

Expand All @@ -249,8 +253,10 @@ description](manifest.html#the-project-layout).
`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.
* `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
Expand Down Expand Up @@ -410,7 +416,8 @@ information.

# Further reading

Now that you have an overview of how to use cargo and have created your first crate, you may be interested in:
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)
Expand Down
57 changes: 34 additions & 23 deletions src/doc/manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Versioning](http://semver.org/), so make sure you follow some basic rules:

## The `build` field (optional)

This field specifies a file in the repository which is a [build script][1] for
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].

Expand All @@ -48,9 +48,9 @@ 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
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

Expand Down Expand Up @@ -107,7 +107,7 @@ migration.
## The `publish` field (optional)

The `publish` field can be used to prevent a package from being published to a
repository by mistake.
package repository (like *crates.io*) by mistake.

```toml
[package]
Expand All @@ -124,7 +124,7 @@ Cargo.toml with `[workspace]` upwards in the filesystem.
```toml
[package]
# ...
workspace = "path/to/root"
workspace = "path/to/workspace/root"
```

For more information, see the documentation for the workspace table below.
Expand All @@ -142,15 +142,15 @@ There are a number of optional metadata fields also accepted under the
# uploaded to crates.io (aka this is not markdown).
description = "..."

# These URLs point to more information about the repository. These are
# 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 in the repository (relative to this `Cargo.toml`). The
# contents of this file are stored and indexed in the registry.
# 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.
readme = "..."

# This is a list of up to five keywords that describe this crate. Keywords
Expand Down Expand Up @@ -178,25 +178,33 @@ license-file = "..."
# currently available are Travis CI, Appveyor, and GitLab latest build status,
# specified using the following parameters:
[badges]

# Travis CI: `repository` in format "<user>/<project>" is required.
# `branch` is optional; default is `master`
travis-ci = { repository = "...", branch = "master" }

# 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" }

# GitLab: `repository` is required. `branch` is optional; default is `master`
gitlab = { repository = "...", branch = "master" }

# Circle CI: `repository` is required. `branch` is optiona; default is `master`
circle-ci = { repository = "...", branch = "master" }

# 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 = "..." }

# 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" }
Expand Down Expand Up @@ -446,23 +454,22 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
exclude = ["path1", "path/to/dir2"]
```

Workspaces were added to Cargo as part [RFC 1525] and have a number of
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
* 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 next to the
root crate's `Cargo.toml`.
* The lock file for all crates in the workspace resides next to the root crate's
`Cargo.toml`.
* 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
at the workspace root crate, they are ignored in member crates' manifests.
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`
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
Expand Down Expand Up @@ -519,15 +526,18 @@ integration tests, and benchmarks respectively.
*.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).
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.
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>`.
Expand All @@ -540,7 +550,8 @@ name = "foo"
crate-type = ["staticlib"]
```

You can build individual library examples with the command `cargo build --example <example-name>`.
You can build individual library examples with the command
`cargo build --example <example-name>`.

# Tests

Expand Down