Patch test macro to work around qemu vfork bug when command not found

[cargo.git] / README.md

diff --git a/README.md b/README.md
index d38aefa23f997c482ec5e403608d38d8a5b2b108..71b2fd0a9027c6d493272e2a0452627c97fb3a00 100644 (file)
--- a/README.md
+++ b/README.md
@@ -2,12 +2,16 @@
 
 Cargo downloads your Rust project’s dependencies and compiles your project.
 
-Learn more at https://doc.rust-lang.org/cargo/
+**To start using Cargo**, learn more at [The Cargo Book].
+
+**To start developing Cargo itself**, read the [Cargo Contributor Guide].
+
+[The Cargo Book]: https://doc.rust-lang.org/cargo/
+[Cargo Contributor Guide]: https://rust-lang.github.io/cargo/contrib/
 
 ## Code Status
 
-[![Build Status](https://travis-ci.com/rust-lang/cargo.svg?branch=master)](https://travis-ci.com/rust-lang/cargo)
-[![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-lang/cargo?branch=master&svg=true)](https://ci.appveyor.com/project/rust-lang-libs/cargo)
+[![CI](https://github.com/rust-lang/cargo/actions/workflows/main.yml/badge.svg?branch=auto-cargo)](https://github.com/rust-lang/cargo/actions/workflows/main.yml)
 
 Code documentation: https://docs.rs/cargo/
 
@@ -18,13 +22,44 @@ locally you probably also have `cargo` installed locally.
 
 ## Compiling from Source
 
+### Requirements
+
 Cargo requires the following tools and packages to build:
 
-* `git`
-* `python`
-* `curl` (on Unix)
-* OpenSSL headers (only for Unix, this is the `libssl-dev` package on ubuntu)
 * `cargo` and `rustc`
+* A C compiler [for your platform](https://github.com/rust-lang/cc-rs#compile-time-requirements)
+* `git` (to clone this repository)
+
+**Other requirements:**
+
+The following are optional based on your platform and needs.
+
+* `pkg-config` — This is used to help locate system packages, such as `libssl` headers/libraries. This may not be required in all cases, such as using vendored OpenSSL, or on Windows.
+* OpenSSL — Only needed on Unix-like systems and only if the `vendored-openssl` Cargo feature is not used.
+
+  This requires the development headers, which can be obtained from the `libssl-dev` package on Ubuntu or `openssl-devel` with apk or yum or the `openssl` package from Homebrew on macOS.
+
+  If using the `vendored-openssl` Cargo feature, then a static copy of OpenSSL will be built from source instead of using the system OpenSSL.
+  This may require additional tools such as `perl` and `make`.
+
+  On macOS, common installation directories from Homebrew, MacPorts, or pkgsrc will be checked. Otherwise it will fall back to `pkg-config`.
+
+  On Windows, the system-provided Schannel will be used instead.
+
+  LibreSSL is also supported.
+
+**Optional system libraries:**
+
+The build will automatically use vendored versions of the following libraries. However, if they are provided by the system and can be found with `pkg-config`, then the system libraries will be used instead:
+
+* [`libcurl`](https://curl.se/libcurl/) — Used for network transfers.
+* [`libgit2`](https://libgit2.org/) — Used for fetching git dependencies.
+* [`libssh2`](https://www.libssh2.org/) — Used for SSH access to git repositories.
+* [`libz`](https://zlib.net/) (aka zlib) — Used for data compression.
+
+It is recommended to use the vendored versions as they are the versions that are tested to work with Cargo.
+
+### Compiling
 
 First, you'll want to check out this repository
 
@@ -50,10 +85,12 @@ a list of known community-developed subcommands.
 
 ## Releases
 
-High level release notes are available as part of [Rust's release notes][rel].
 Cargo releases coincide with Rust releases.
+High level release notes are available as part of [Rust's release notes][rel].
+Detailed release notes are available in this repo at [CHANGELOG.md].
 
 [rel]: https://github.com/rust-lang/rust/blob/master/RELEASES.md
+[CHANGELOG.md]: CHANGELOG.md
 
 ## Reporting issues
 
@@ -65,26 +102,26 @@ Please report all issues on the GitHub [issue tracker][issues].
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). You may also find the architecture
-documentation useful ([ARCHITECTURE.md](ARCHITECTURE.md)).
+See the **[Cargo Contributor Guide]** for a complete introduction
+to contributing to Cargo.
 
 ## License
 
 Cargo is primarily distributed under the terms of both the MIT license
 and the Apache License (Version 2.0).
 
-See LICENSE-APACHE and LICENSE-MIT for details.
+See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
 
 ### Third party software
 
 This product includes software developed by the OpenSSL Project
-for use in the OpenSSL Toolkit (http://www.openssl.org/).
+for use in the OpenSSL Toolkit (https://www.openssl.org/).
 
 In binary form, this product includes software that is licensed under the
 terms of the GNU General Public License, version 2, with a linking exception,
 which can be obtained from the [upstream repository][1].
 
-See LICENSE-THIRD-PARTY for details.
+See [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) for details.
 
 [1]: https://github.com/libgit2/libgit2