]>
Commit | Line | Data |
---|---|---|
2547b059 BN |
1 | # Cargo |
2 | ||
b4e86302 YK |
3 | Cargo downloads your Rust project’s dependencies and compiles your project. |
4 | ||
2d06e570 WL |
5 | **To start using Cargo**, learn more at [The Cargo Book]. |
6 | ||
7 | **To start developing Cargo itself**, read the [Cargo Contributor Guide]. | |
8 | ||
9 | [The Cargo Book]: https://doc.rust-lang.org/cargo/ | |
10 | [Cargo Contributor Guide]: https://rust-lang.github.io/cargo/contrib/ | |
b4e86302 | 11 | |
41ecf3b2 | 12 | ## Code Status |
2547b059 | 13 | |
8fa41202 | 14 | [![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) |
15 | ||
ddffe606 MK |
16 | Code documentation: https://docs.rs/cargo/ |
17 | ||
cfb69ad2 | 18 | ## Installing Cargo |
ffd985f1 | 19 | |
cfb69ad2 AC |
20 | Cargo is distributed by default with Rust, so if you've got `rustc` installed |
21 | locally you probably also have `cargo` installed locally. | |
ffd985f1 | 22 | |
cfb69ad2 | 23 | ## Compiling from Source |
41a4df26 | 24 | |
c2a5be76 EH |
25 | ### Requirements |
26 | ||
5ef03758 AC |
27 | Cargo requires the following tools and packages to build: |
28 | ||
ea182b83 | 29 | * `cargo` and `rustc` |
c2a5be76 EH |
30 | * A C compiler [for your platform](https://github.com/rust-lang/cc-rs#compile-time-requirements) |
31 | * `git` (to clone this repository) | |
32 | ||
33 | **Other requirements:** | |
34 | ||
35 | The following are optional based on your platform and needs. | |
36 | ||
37 | * `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. | |
38 | * OpenSSL — Only needed on Unix-like systems and only if the `vendored-openssl` Cargo feature is not used. | |
39 | ||
40 | 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. | |
41 | ||
42 | If using the `vendored-openssl` Cargo feature, then a static copy of OpenSSL will be built from source instead of using the system OpenSSL. | |
43 | This may require additional tools such as `perl` and `make`. | |
44 | ||
45 | On macOS, common installation directories from Homebrew, MacPorts, or pkgsrc will be checked. Otherwise it will fall back to `pkg-config`. | |
46 | ||
47 | On Windows, the system-provided Schannel will be used instead. | |
48 | ||
49 | LibreSSL is also supported. | |
50 | ||
51 | **Optional system libraries:** | |
52 | ||
53 | 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: | |
54 | ||
55 | * [`libcurl`](https://curl.se/libcurl/) — Used for network transfers. | |
56 | * [`libgit2`](https://libgit2.org/) — Used for fetching git dependencies. | |
57 | * [`libssh2`](https://www.libssh2.org/) — Used for SSH access to git repositories. | |
58 | * [`libz`](https://zlib.net/) (aka zlib) — Used for data compression. | |
59 | ||
60 | It is recommended to use the vendored versions as they are the versions that are tested to work with Cargo. | |
61 | ||
62 | ### Compiling | |
5ef03758 | 63 | |
d261ffda | 64 | First, you'll want to check out this repository |
c1bbc721 | 65 | |
d261ffda | 66 | ``` |
e2f81ec8 | 67 | git clone https://github.com/rust-lang/cargo |
a39a331a | 68 | cd cargo |
d261ffda AC |
69 | ``` |
70 | ||
ea182b83 | 71 | With `cargo` already installed, you can simply run: |
d261ffda AC |
72 | |
73 | ``` | |
74 | cargo build --release | |
75 | ``` | |
76 | ||
1e5f7063 J |
77 | ## Adding new subcommands to Cargo |
78 | ||
cfb69ad2 AC |
79 | Cargo is designed to be extensible with new subcommands without having to modify |
80 | Cargo itself. See [the Wiki page][third-party-subcommands] for more details and | |
81 | a list of known community-developed subcommands. | |
1e5f7063 J |
82 | |
83 | [third-party-subcommands]: https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands | |
84 | ||
fe624014 | 85 | |
c41a680e CNG |
86 | ## Releases |
87 | ||
c41a680e | 88 | Cargo releases coincide with Rust releases. |
aea965c2 EH |
89 | High level release notes are available as part of [Rust's release notes][rel]. |
90 | Detailed release notes are available in this repo at [CHANGELOG.md]. | |
c41a680e CNG |
91 | |
92 | [rel]: https://github.com/rust-lang/rust/blob/master/RELEASES.md | |
aea965c2 | 93 | [CHANGELOG.md]: CHANGELOG.md |
c41a680e | 94 | |
3970ccd2 | 95 | ## Reporting issues |
c1bbc721 AC |
96 | |
97 | Found a bug? We'd love to know about it! | |
98 | ||
43914c53 | 99 | Please report all issues on the GitHub [issue tracker][issues]. |
c1bbc721 AC |
100 | |
101 | [issues]: https://github.com/rust-lang/cargo/issues | |
102 | ||
d11a429d AK |
103 | ## Contributing |
104 | ||
4d40ef4e EH |
105 | See the **[Cargo Contributor Guide]** for a complete introduction |
106 | to contributing to Cargo. | |
107 | ||
c6fc2f58 AC |
108 | ## License |
109 | ||
110 | Cargo is primarily distributed under the terms of both the MIT license | |
111 | and the Apache License (Version 2.0). | |
112 | ||
c130148d | 113 | See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details. |
74705a05 AC |
114 | |
115 | ### Third party software | |
116 | ||
117 | This product includes software developed by the OpenSSL Project | |
0c3851c0 | 118 | for use in the OpenSSL Toolkit (https://www.openssl.org/). |
74705a05 AC |
119 | |
120 | In binary form, this product includes software that is licensed under the | |
121 | terms of the GNU General Public License, version 2, with a linking exception, | |
122 | which can be obtained from the [upstream repository][1]. | |
123 | ||
c130148d | 124 | See [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) for details. |
2547b059 | 125 | |
74705a05 AC |
126 | [1]: https://github.com/libgit2/libgit2 |
127 |