README.md

   1 # Cargo
   2
   3 Cargo downloads your Rust project’s dependencies and compiles your project.
   4
   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/
  11
  12 ## Code Status
  13
  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
  16 Code documentation: https://docs.rs/cargo/
  17
  18 ## Installing Cargo
  19
  20 Cargo is distributed by default with Rust, so if you've got `rustc` installed
  21 locally you probably also have `cargo` installed locally.
  22
  23 ## Compiling from Source
  24
  25 ### Requirements
  26
  27 Cargo requires the following tools and packages to build:
  28
  29 * `cargo` and `rustc`
  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
  63
  64 First, you'll want to check out this repository
  65
  66 ```
  67 git clone https://github.com/rust-lang/cargo
  68 cd cargo
  69 ```
  70
  71 With `cargo` already installed, you can simply run:
  72
  73 ```
  74 cargo build --release
  75 ```
  76
  77 ## Adding new subcommands to Cargo
  78
  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.
  82
  83 [third-party-subcommands]: https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands
  84
  85
  86 ## Releases
  87
  88 Cargo releases coincide with Rust releases.
  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].
  91
  92 [rel]: https://github.com/rust-lang/rust/blob/master/RELEASES.md
  93 [CHANGELOG.md]: CHANGELOG.md
  94
  95 ## Reporting issues
  96
  97 Found a bug? We'd love to know about it!
  98
  99 Please report all issues on the GitHub [issue tracker][issues].
 100
 101 [issues]: https://github.com/rust-lang/cargo/issues
 102
 103 ## Contributing
 104
 105 See the **[Cargo Contributor Guide]** for a complete introduction
 106 to contributing to Cargo.
 107
 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
 113 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
 114
 115 ### Third party software
 116
 117 This product includes software developed by the OpenSSL Project
 118 for use in the OpenSSL Toolkit (https://www.openssl.org/).
 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
 124 See [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) for details.
 125
 126 [1]: https://github.com/libgit2/libgit2
 127