From 4518d897f60a89326bb8235eb283c9318007ad87 Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Mon, 7 Aug 2017 11:11:36 -0700 Subject: [PATCH 1/2] [docs] Update language regarding repository vs package root In the current documentation, there are many places with language that assumes a *repository* (as in VCS) is the same as *package root* (the directory where `Cargo.toml` sits). With the new workspace features, this is far from true now, and the inaccurate language makes it difficault for newbies or developers without much familiarity with the cargo internals with authoring their manifest files. This diff tries to use the right terms for places any of these concepts is referred to: * Package root, * Workspace root, * VCS repository, and * Package repository/index, like crates.io. --- src/doc/guide.md | 3 ++- src/doc/manifest.md | 45 ++++++++++++++++++++++++++------------------- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f6437ab50fe..897db6575f3 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -232,7 +232,8 @@ 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`. diff --git a/src/doc/manifest.md b/src/doc/manifest.md index 25bdf388ffe..308d716b4a0 100644 --- a/src/doc/manifest.md +++ b/src/doc/manifest.md @@ -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]. @@ -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 @@ -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] @@ -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. @@ -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 @@ -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 "/" 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" } @@ -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 From e774367afc7d25bb356a956711715293013be782 Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Mon, 7 Aug 2017 11:26:53 -0700 Subject: [PATCH 2/2] [docs] Wrap long lines --- src/doc/guide.md | 18 ++++++++++++------ src/doc/manifest.md | 12 ++++++++---- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 897db6575f3..39b25c2f46a 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -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 @@ -89,7 +90,8 @@ 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: +Once you’re ready for release, you can use `cargo build --release` to compile +your files with optimizations turned on: 
$ cargo build --release
 `. 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 `. 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
 `.
@@ -547,7 +550,8 @@ name = "foo"
 crate-type = ["staticlib"]
 ```
 
-You can build individual library examples with the command `cargo build --example `.
+You can build individual library examples with the command
+`cargo build --example `.
 
 # Tests