diff options
Diffstat (limited to 'src/tools/cargo/README.md')
| -rw-r--r-- | src/tools/cargo/README.md | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/src/tools/cargo/README.md b/src/tools/cargo/README.md new file mode 100644 index 000000000..423555e62 --- /dev/null +++ b/src/tools/cargo/README.md @@ -0,0 +1,127 @@ +# Cargo + +Cargo downloads your Rust project’s dependencies and compiles your project. + +**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 + +[](https://github.com/rust-lang/cargo/actions/workflows/main.yml) + +Code documentation: https://docs.rs/cargo/ + +## Installing Cargo + +Cargo is distributed by default with Rust, so if you've got `rustc` installed +locally you probably also have `cargo` installed locally. + +## Compiling from Source + +### Requirements + +Cargo requires the following tools and packages to build: + +* `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 + +``` +git clone https://github.com/rust-lang/cargo.git +cd cargo +``` + +With `cargo` already installed, you can simply run: + +``` +cargo build --release +``` + +## Adding new subcommands to Cargo + +Cargo is designed to be extensible with new subcommands without having to modify +Cargo itself. See [the Wiki page][third-party-subcommands] for more details and +a list of known community-developed subcommands. + +[third-party-subcommands]: https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands + + +## Releases + +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 + +Found a bug? We'd love to know about it! + +Please report all issues on the GitHub [issue tracker][issues]. + +[issues]: https://github.com/rust-lang/cargo/issues + +## Contributing + +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](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 (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](LICENSE-THIRD-PARTY) for details. + +[1]: https://github.com/libgit2/libgit2 + |