cargo/README.md

128 lines
4.4 KiB
Markdown
Raw Normal View History

2017-10-31 20:37:45 +00:00
# Cargo
2014-06-24 00:02:22 +00:00
Cargo downloads your Rust projects 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/
2014-06-24 00:02:22 +00:00
## Code Status
2017-10-31 20:37:45 +00:00
[![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://doc.rust-lang.org/nightly/nightly-rustc/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
2014-04-11 10:11:45 +00:00
2022-08-29 23:07:17 +00:00
### Requirements
Cargo requires the following tools and packages to build:
2016-12-26 01:02:04 +00:00
* `cargo` and `rustc`
2022-08-29 23:07:17 +00:00
* 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
```
2016-12-26 01:02:04 +00:00
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
2014-06-24 20:37:28 +00:00
## Releases
Cargo releases coincide with Rust releases.
2019-05-27 23:39:29 +00:00
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
2019-05-27 23:39:29 +00:00
[CHANGELOG.md]: CHANGELOG.md
## Reporting issues
Found a bug? We'd love to know about it!
2018-04-17 20:14:41 +00:00
Please report all issues on the GitHub [issue tracker][issues].
[issues]: https://github.com/rust-lang/cargo/issues
2017-09-03 09:47:49 +00:00
## Contributing
2020-09-18 20:17:58 +00:00
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).
2019-12-03 07:03:49 +00:00
See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
### Third party software
This product includes software developed by the OpenSSL Project
2019-01-30 20:34:37 +00:00
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].
2019-12-03 07:03:49 +00:00
See [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) for details.
2017-10-31 20:37:45 +00:00
[1]: https://github.com/libgit2/libgit2