mirror of https://github.com/rust-lang/cargo
Update contributing documentation for running tests and building docs.
This commit is contained in:
Eric Huss
parent
e70a37634a
commit
bfcc6d6529
|
|
@ -88,19 +88,59 @@ in `test/` provide templates on how to test Cargo's behavior in a
|
|||
sandbox-environment. The internal module `crates/cargo-test-support` provides a vast amount
|
||||
of helpers to minimize boilerplate. See [`crates/cargo-test-support/src/lib.rs`] for an
|
||||
introduction to writing tests.
|
||||
* Make sure `cargo test` passes. If you do not have the cross-compilers
|
||||
installed locally, install them using the instructions returned by
|
||||
`cargo test cross_compile::cross_tests` (twice, with `--toolchain nightly`
|
||||
added to get the nightly cross target too); alternatively just
|
||||
ignore the cross-compile test failures or disable them by
|
||||
using `CFG_DISABLE_CROSS_TESTS=1 cargo test`. Note that some tests are enabled
|
||||
only on `nightly` toolchain. If you can, test both toolchains.
|
||||
* Make sure `cargo test` passes. See [Running tests](#running-tests) below
|
||||
for details on running tests.
|
||||
* All code changes are expected to comply with the formatting suggested by `rustfmt`.
|
||||
You can use `rustup component add --toolchain nightly rustfmt` to install `rustfmt` and use
|
||||
`rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code.
|
||||
You can use `rustup component add rustfmt` to install `rustfmt` and use
|
||||
`cargo fmt` to automatically format your code.
|
||||
* Push your commits to GitHub and create a pull request against Cargo's
|
||||
`master` branch.
|
||||
|
||||
## Running tests
|
||||
|
||||
Most of the tests are found in the `testsuite` integration test. This can be
|
||||
run with a simple `cargo test`.
|
||||
|
||||
Some tests only run on the nightly toolchain, and will be ignored on other
|
||||
channels. It is recommended that you run tests with both nightly and stable to
|
||||
ensure everything is working as expected.
|
||||
|
||||
Some tests exercise cross compiling to a different target. This will require
|
||||
you to install the appropriate target. This typically is the 32-bit target of
|
||||
your host platform. For example, if your host is a 64-bit
|
||||
`x86_64-unknown-linux-gnu`, then you should install the 32-bit target with
|
||||
`rustup target add i686-unknown-linux-gnu`. If you don't have the alternate
|
||||
target installed, there should be an error message telling you what to do. You
|
||||
may also need to install additional tools for the target. For example, on Ubuntu
|
||||
you should install the `gcc-multilib` package.
|
||||
|
||||
If you can't install an alternate target, you can set the
|
||||
`CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests.
|
||||
Unfortunately 32-bit support on macOS is going away, so you may not be able to
|
||||
run these tests on macOS. The Windows cross tests only support the MSVC
|
||||
toolchain.
|
||||
|
||||
Some of the nightly tests require the `rustc-dev` component installed. This
|
||||
component includes the compiler as a library. This may already be installed
|
||||
with your nightly toolchain, but it if isn't, run `rustup component add
|
||||
rustc-dev --toolchain=nightly`.
|
||||
|
||||
There are several other packages in the repo for running specialized tests,
|
||||
and you will need to run these tests separately by changing into its directory
|
||||
and running `cargo test`:
|
||||
|
||||
* [`crates/resolver-tests`] – This package runs tests on the dependency resolver.
|
||||
* [`crates/cargo-platform`] – This is a standalone `cfg()` expression parser.
|
||||
|
||||
The `build-std` tests are disabled by default, but you can run them by setting
|
||||
the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test
|
||||
--test build-std`. This requires the nightly channel, and also requires the
|
||||
`rust-src` component installed with `rustup component add rust-src
|
||||
--toolchain=nightly`.
|
||||
|
||||
[`crates/resolver-tests`]: crates/resolver-tests
|
||||
[`crates/cargo-platform`]: crates/cargo-platform
|
||||
|
||||
## Pull requests
|
||||
|
||||
After the pull request is made, a friendly bot will automatically assign a
|
||||
|
|
@ -124,18 +164,8 @@ and [merges][mergequeue] it into Cargo's `master` branch.
|
|||
|
||||
## Contributing to the documentation
|
||||
|
||||
To contribute to the documentation, all you need to do is change the markdown
|
||||
files in the `src/doc` directory. To view the rendered version of changes you
|
||||
have made locally, make sure you have `mdbook` installed and run:
|
||||
|
||||
```sh
|
||||
cd src/doc
|
||||
mdbook build
|
||||
open book/index.html
|
||||
```
|
||||
|
||||
To install `mdbook` run `cargo install mdbook`.
|
||||
|
||||
See the [documentation README](src/doc/README.md) for details on building the
|
||||
documentation.
|
||||
|
||||
## Issue Triage
|
||||
|
||||
|
|
@ -184,6 +214,7 @@ adding labels to triage issues:
|
|||
* The light orange **relnotes** label marks issues that should be documented in
|
||||
the release notes of the next release.
|
||||
|
||||
* Dark blue, **Z**-prefixed labels are for unstable, nightly features.
|
||||
|
||||
[githelp]: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html
|
||||
[development-models]: https://help.github.com/articles/about-collaborative-development-models/
|
||||
|
|
@ -197,6 +228,6 @@ adding labels to triage issues:
|
|||
[I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
|
||||
[Code of Conduct]: https://www.rust-lang.org/conduct.html
|
||||
[Discord]: https://discordapp.com/invite/rust-lang
|
||||
[`crates/cargo-test-support/src/lib.rs`]: https://github.com/rust-lang/cargo/blob/master/crates/cargo-test-support/src/lib.rs
|
||||
[`crates/cargo-test-support/src/lib.rs`]: crates/cargo-test-support/src/lib.rs
|
||||
[irlo]: https://internals.rust-lang.org/
|
||||
[subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands
|
||||
|
|
|
|||
|
|
@ -20,7 +20,6 @@ locally you probably also have `cargo` installed locally.
|
|||
Cargo requires the following tools and packages to build:
|
||||
|
||||
* `git`
|
||||
* `python`
|
||||
* `curl` (on Unix)
|
||||
* `pkg-config` (on Unix, used to figure out the `libssl` headers/libraries)
|
||||
* OpenSSL headers (only for Unix, this is the `libssl-dev` package on ubuntu)
|
||||
|
|
|
|||
|
|
@ -1,47 +1,65 @@
|
|||
# The Cargo Book
|
||||
# Cargo documentation
|
||||
|
||||
This directory contains Cargo's documentation. There are two parts, [The Cargo Book]
|
||||
which is built with [mdbook] and the man pages, which are built with [Asciidoctor].
|
||||
The man pages are also included in The Cargo Book as HTML.
|
||||
|
||||
### Requirements
|
||||
[The Cargo Book]: https://doc.rust-lang.org/cargo/
|
||||
|
||||
### Building the book
|
||||
|
||||
Building the book requires [mdBook]. To get it:
|
||||
|
||||
[mdBook]: https://github.com/rust-lang-nursery/mdBook
|
||||
[mdBook]: https://github.com/rust-lang/mdBook
|
||||
|
||||
```console
|
||||
$ cargo install mdbook
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
To build the book:
|
||||
|
||||
```console
|
||||
$ mdbook build
|
||||
```
|
||||
|
||||
The output will be in the `book` subdirectory. To check it out, open it in
|
||||
your web browser.
|
||||
`mdbook` provides a variety of different commands and options to help you work
|
||||
on the book:
|
||||
|
||||
* `mdbook build --open`: Build the book and open it in a web browser.
|
||||
* `mdbook serve`: Launches a web server on localhost. It also automatically
|
||||
rebuilds the book whenever any file changes and automatically reloads your
|
||||
web browser.
|
||||
|
||||
The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and
|
||||
every file must be linked there.
|
||||
|
||||
### Building the man pages
|
||||
|
||||
Building the man pages requires [Asciidoctor]. See the linked page for
|
||||
installation instructions. It also requires the `make` build tool and `ruby`.
|
||||
|
||||
[Asciidoctor]: https://asciidoctor.org/
|
||||
|
||||
The source files are located in the [`src/doc/man`](man) directory. The
|
||||
[`Makefile`](Makefile) is used to rebuild the man pages. It outputs the man
|
||||
pages into [`src/etc/man`](../etc/man) and the HTML versions into
|
||||
[`src/doc/man/generated`](man/generated). The Cargo Book has some markdown
|
||||
stub files in [`src/doc/src/commands`](src/commands) which load the generated
|
||||
HTML files.
|
||||
|
||||
To build the man pages, run `make` in the `src/doc` directory:
|
||||
|
||||
_Firefox:_
|
||||
```console
|
||||
$ 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:_
|
||||
```console
|
||||
$ 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)
|
||||
$ make
|
||||
```
|
||||
|
||||
The build script uses a few Asciidoctor extensions. See
|
||||
[`asciidoc-extension.rb`](asciidoc-extension.rb) for details.
|
||||
|
||||
## 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.
|
||||
We'd love your help with improving the documentation! Please feel free to
|
||||
[open issues](https://github.com/rust-lang/cargo/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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue