## File: README.md

# 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/

> The Cargo binary distributed through with Rust is maintained by the Cargo
> team for use by the wider ecosystem.
> For all other uses of this crate (as a binary or library) this is maintained
> by the Cargo team, primarily for use by Cargo and not intended for external
> use (except as a transitive dependency). This crate may make major changes to
> its APIs.

## Code Status

[](https://github.com/rust-lang/cargo/actions/workflows/main.yml)

Code documentation: <https://doc.rust-lang.org/nightly/nightly-rustc/cargo/>

## 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 by the above C libraries for data compression. (Rust code uses [`zlib-rs`](https://github.com/trifectatechfoundation/zlib-rs) instead.)

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 the [changelog].

[rel]: https://github.com/rust-lang/rust/blob/master/RELEASES.md
[changelog]: https://doc.rust-lang.org/nightly/cargo/CHANGELOG.html

## 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

---

## File: benches/benchsuite/README.md

> This crate is maintained by the Cargo team, primarily for use by Cargo
> and not intended for external use. This
> crate may make major changes to its APIs or be deprecated without warning.

---

## File: benches/README.md

# Cargo Benchmarking

This directory contains some benchmarks for cargo itself. This uses
[Criterion] for running benchmarks. It is recommended to read the Criterion
book to get familiar with how to use it. A basic usage would be:

```sh
cd benches/benchsuite
cargo bench
```

However, running all benchmarks would take many minutes, so in most cases it
is recommended to just run the benchmarks relevant to whatever section of code
you are working on.

## Benchmarks

There are several different kinds of benchmarks in the `benchsuite/benches` directory:

* `global_cache_tracker` — Benchmarks saving data to the global cache tracker
  database using samples of real-world data.
* `resolve` — Benchmarks the resolver against simulations of real-world workspaces.
* `workspace_initialization` — Benchmarks initialization of a workspace
  against simulations of real-world workspaces.

### Resolve benchmarks

The resolve benchmarks involve downloading the index and benchmarking against some
real-world and artificial workspaces located in the [`workspaces`](workspaces)
directory.

**Beware** that the initial download can take a fairly long amount of time (10
minutes minimum on an extremely fast network) and require significant disk
space (around 4.5GB). The benchsuite will cache the index and downloaded
crates in the `target/tmp/bench` directory, so subsequent runs should be
faster. You can (and probably should) specify individual benchmarks to run to
narrow it down to a more reasonable set, for example:

```sh
cargo bench -p benchsuite --bench resolve -- resolve_ws/rust
```

This will only download what's necessary for the rust-lang/rust workspace
(which is about 330MB) and run the benchmarks against it (which should take
about a minute). To get a list of all the benchmarks, run:

```sh
cargo bench -p benchsuite --bench resolve -- --list
```

### Global cache tracker

The `global_cache_tracker` benchmark tests saving data to the global cache
tracker database using samples of real-world data. This benchmark should run
relatively quickly.

The real-world data is based on a capture of my personal development
environment which has accumulated a large cache. So it is somewhat arbitrary,
but hopefully representative of a challenging environment. Capturing of the
data is done with the `capture-last-use` binary, which you can run if you need
to rebuild the database. Just try to run on a system with a relatively full
cache in your cargo home directory.

```sh
cargo bench -p benchsuite --bench global_cache_tracker
```

## Viewing reports

The benchmarks display some basic information on the command-line while they
run. A more complete HTML report can be found at
`target/criterion/report/index.html` which contains links to all the
benchmarks and summaries. Check out the Criterion book for more information on
the extensive reporting capabilities.

## Comparing implementations

Knowing the raw numbers can be useful, but what you're probably most
interested in is checking if your changes help or hurt performance. To do
that, you need to run the benchmarks multiple times.

First, run the benchmarks from the master branch of cargo without any changes.
To make it easier to compare, Criterion supports naming the baseline so that
you can iterate on your code and compare against it multiple times.

```sh
cargo bench -- --save-baseline master
```

Now you can switch to your branch with your changes. Re-run the benchmarks
compared against the baseline:

```sh
cargo bench -- --baseline master
```

You can repeat the last command as you make changes to re-compare against the
master baseline.

Without the baseline arguments, it will compare against the last run, which
can be helpful for comparing incremental changes.

## Capturing workspaces

The [`workspaces`](workspaces) directory contains several workspaces that
provide a variety of different workspaces intended to provide good exercises
for benchmarks. Some of these are shadow copies of real-world workspaces. This
is done with the tool in the [`capture`](capture) directory. The tool will
copy `Cargo.lock` and all of the `Cargo.toml` files of the workspace members.
It also adds an empty `lib.rs` so Cargo won't error, and sanitizes the
`Cargo.toml` to some degree, removing unwanted elements. Finally, it
compresses everything into a `tgz`.

To run it, do:

```sh
cd benches/capture
cargo run -- /path/to/workspace/foo
```

The resolver benchmarks also support the `CARGO_BENCH_WORKSPACES` environment
variable, which you can point to a Cargo workspace if you want to try
different workspaces. For example:

```sh
CARGO_BENCH_WORKSPACES=/path/to/some/workspace cargo bench
```

## TODO

This is just a start for establishing a benchmarking suite for Cargo. There's
a lot that can be added. Some ideas:

* Fix the benchmarks so that the resolver setup doesn't run every iteration.
* Benchmark [this section of
  code](https://github.com/rust-lang/cargo/blob/a821e2cb24d7b6013433f069ab3bad53d160e100/src/ops/cargo_compile.rs#L470-L549)
  which builds the unit graph. The performance there isn't great, and it would
  be good to keep an eye on it. Unfortunately that would mean doing a bit of
  work to make `generate_targets` publicly visible, and there is a bunch of
  setup code that may need to be duplicated.
* Benchmark the fingerprinting code.
* Benchmark running the `cargo` executable. Running something like `cargo
  build` or `cargo check` with everything "Fresh" would be a good end-to-end
  exercise to measure the overall overhead of Cargo.
* Benchmark pathological resolver scenarios. There might be some cases where
  the resolver can spend a significant amount of time. It would be good to
  identify if these exist, and create benchmarks for them. This may require
  creating an artificial index, similar to the `resolver-tests`. This should
  also consider scenarios where the resolver ultimately fails.
* Benchmark without `Cargo.lock`. I'm not sure if this is particularly
  valuable, since we are mostly concerned with incremental builds which will
  always have a lock file.
* Benchmark just
  [`resolve::resolve`](https://github.com/rust-lang/cargo/blob/a821e2cb24d7b6013433f069ab3bad53d160e100/src/resolver/mod.rs#L122)
  without anything else. This can help focus on just the resolver.

[Criterion]: https://bheisler.github.io/criterion.rs/book/

---

## File: crates/rustfix/README.md

# rustfix

[](https://crates.io/crates/rustfix)
[](https://docs.rs/rustfix)

Rustfix is a library defining useful structures that represent fix suggestions from rustc.

This is a low-level library. You pass it the JSON output from `rustc`, and you can then use it to apply suggestions to in-memory strings. This library doesn't execute commands, or read or write from the filesystem.

If you are looking for the [`cargo fix`] implementation, the core of it is located in [`cargo::ops::fix`].

> This crate is maintained by the Cargo team, primarily for use by Cargo and Rust compiler test suite
> and not intended for external use (except as a transitive dependency). This
> crate may make major changes to its APIs or be deprecated without warning.

[`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html
[`cargo::ops::fix`]: https://github.com/rust-lang/cargo/blob/master/src/ops/fix.rs

## License

Licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.

---

## File: crates/resolver-tests/README.md

# resolver-tests

## The aim

This crate aims to test the resolution of Cargo's resolver. It implements a [SAT solver](https://en.wikipedia.org/wiki/SAT_solver) to compare with resolution of Cargo's resolver.
This ensures that Cargo's dependency resolution is proven valid by lowering to [SAT problem](https://en.wikipedia.org/wiki/Boolean_satisfiability_problem).

> This crate is maintained by the Cargo team, primarily for use by Cargo
> and not intended for external use (except as a transitive dependency). This
> crate may make major changes to its APIs or be deprecated without warning.

## About the test

The Cargo's resolver is very sensitive to what order it tries to evaluate constraints. This makes it incredibly difficult
to be sure that a handful of tests actually covers all the important permutations of decision-making. The tests not only needs
to hit all the corner cases, it needs to try all of the orders of evaluation. So we use fuzz testing to cover more permutations.

---

## File: crates/mdman/doc/out/mdman.md

# mdman(1)

## NAME

mdman - Converts markdown to a man page

## SYNOPSIS

`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._

## DESCRIPTION

Converts a markdown file to a man page.

The source file is first processed as a
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
markdown into the target format. This supports different output formats,
such as troff or plain text.

Every man page should start with a level-1 header with the man name and
section, such as `# mdman(1)`.

The handlebars template has several special tags to assist with generating the
man page:

- Every block of command-line options must be wrapped between `{{#options}}`
  and `{{/options}}` tags. This tells the processor where the options start
  and end.
- Each option must be expressed with a `{{#option}}` block. The parameters to
  the block are a sequence of strings indicating the option. For example,
  ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
  has two different forms. The text within the string is processed as markdown.
  It is recommended to use formatting similar to this example.

  The content of the `{{#option}}` block should contain a detailed description
  of the option.

  Use the `{{/option}}` tag to end the option block.
- References to other man pages should use the `{{man name section}}`
  expression. For example, `{{man "mdman" 1}}` will generate a reference to
  the `mdman(1)` man page. For non-troff output, the `--man` option will tell
  `mdman` how to create links to the man page. If there is no matching `--man`
  option, then it links to a file named _name_`.md` in the same directory.
- Variables can be set with `{{*set name="value"}}`. These variables can
  then be referenced with `{{name}}` expressions.
- Partial templates should be placed in a directory named `includes`
  next to the source file. Templates can be included with an expression like
  `{{> template-name}}`.
- Other helpers include:
    - `{{lower value}}` Converts the given value to lowercase.

## OPTIONS

<dl>

<dt class="option-term" id="option-mdman--t"><a class="option-anchor" href="#option-mdman--t">`-t` *type*</a></dt>
<dd class="option-desc">Specifies the output type. The following output types are supported:

<li>`man` — A troff-style man page. Outputs with a numbered extension (like
`.1`) matching the man page section.</li>
<li>`md` — A markdown file, after all handlebars processing has been finished.
Outputs with the `.md` extension.</li>
<li>`txt` — A text file, rendered for situations where a man page viewer isn’t
available. Outputs with the `.txt` extension.</li>

</dd>


<dt class="option-term" id="option-mdman--o"><a class="option-anchor" href="#option-mdman--o">`-o` *outdir*</a></dt>
<dd class="option-desc">Specifies the directory where to save the output.
</dd>


<dt class="option-term" id="option-mdman---url"><a class="option-anchor" href="#option-mdman---url">`--url` *base_url*</a></dt>
<dd class="option-desc">Specifies a base URL to use for relative URLs within the document. Any
relative URL will be joined with this URL.
</dd>


<dt class="option-term" id="option-mdman---man"><a class="option-anchor" href="#option-mdman---man">`--man` *name*`:`*section*`=`*url*</a></dt>
<dd class="option-desc">Specifies a URL to use for the given man page. When the `{{man name section}}` expression is used, the given URL will be inserted as a link. This
may be specified multiple times. If a man page reference does not have a
matching `--man` entry, then a relative link to a file named *name*`.md` will
be used.
</dd>


<dt class="option-term" id="option-mdman-sources…"><a class="option-anchor" href="#option-mdman-sources…">*sources…*</a></dt>
<dd class="option-desc">The source input filename, may be specified multiple times.
</dd>


</dl>

## EXAMPLES

1. Convert the given documents to man pages:

       mdman -t man -o doc doc/mdman.md

---

## File: crates/mdman/doc/mdman.md

# mdman(1)

## NAME

mdman - Converts markdown to a man page

## SYNOPSIS

`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._

## DESCRIPTION

Converts a markdown file to a man page.

The source file is first processed as a
[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
markdown into the target format. This supports different output formats,
such as troff or plain text.

Every man page should start with a level-1 header with the man name and
section, such as `# mdman(1)`.

The handlebars template has several special tags to assist with generating the
man page:

{{{{raw}}}}
- Every block of command-line options must be wrapped between `{{#options}}`
  and `{{/options}}` tags. This tells the processor where the options start
  and end.
- Each option must be expressed with a `{{#option}}` block. The parameters to
  the block are a sequence of strings indicating the option. For example,
  ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
  has two different forms. The text within the string is processed as markdown.
  It is recommended to use formatting similar to this example.

  The content of the `{{#option}}` block should contain a detailed description
  of the option.

  Use the `{{/option}}` tag to end the option block.
- References to other man pages should use the `{{man name section}}`
  expression. For example, `{{man "mdman" 1}}` will generate a reference to
  the `mdman(1)` man page. For non-troff output, the `--man` option will tell
  `mdman` how to create links to the man page. If there is no matching `--man`
  option, then it links to a file named _name_`.md` in the same directory.
- Variables can be set with `{{*set name="value"}}`. These variables can
  then be referenced with `{{name}}` expressions.
- Partial templates should be placed in a directory named `includes`
  next to the source file. Templates can be included with an expression like
  `{{> template-name}}`.
- Other helpers include:
    - `{{lower value}}` Converts the given value to lowercase.
{{{{/raw}}}}

## OPTIONS

{{#options}}

{{#option "`-t` _type_"}}
Specifies the output type. The following output types are supported:
- `man` — A troff-style man page. Outputs with a numbered extension (like
  `.1`) matching the man page section.
- `md` — A markdown file, after all handlebars processing has been finished.
  Outputs with the `.md` extension.
- `txt` — A text file, rendered for situations where a man page viewer isn't
  available. Outputs with the `.txt` extension.
{{/option}}

{{#option "`-o` _outdir_"}}
Specifies the directory where to save the output.
{{/option}}

{{#option "`--url` _base_url_"}}
Specifies a base URL to use for relative URLs within the document. Any
relative URL will be joined with this URL.
{{/option}}

{{#option "`--man` _name_`:`_section_`=`_url_"}}
Specifies a URL to use for the given man page. When the `\{{man name
section}}` expression is used, the given URL will be inserted as a link. This
may be specified multiple times. If a man page reference does not have a
matching `--man` entry, then a relative link to a file named _name_`.md` will
be used.
{{/option}}

{{#option "_sources..._"}}
The source input filename, may be specified multiple times.
{{/option}}

{{/options}}

## EXAMPLES

1. Convert the given documents to man pages:

       mdman -t man -o doc doc/mdman.md

---

## File: crates/mdman/README.md

# mdman

mdman is a small utility for creating man pages from markdown text files.

> This crate is maintained by the Cargo team, primarily for use by Cargo
> and not intended for external use (except as a transitive dependency). This
> crate may make major changes to its APIs or be deprecated without warning.

## Usage

See the [man page](doc/out/mdman.md) generated by this tool.

---

## File: crates/home/README.md

[](https://docs.rs/home)
[](https://crates.io/crates/home)

Canonical definitions of `home_dir`, `cargo_home`, and `rustup_home`.

This provides the definition of `home_dir` used by Cargo and rustup,
as well functions to find the correct value of `CARGO_HOME` and
`RUSTUP_HOME`.

This crate previously used its own definition of `home_dir` on Windows to avoid
[rust-lang/rust#43321], but this was fixed in [1.85.0] so this crate now
simply forwards to [`home_dir`].

This crate further provides two functions, `cargo_home` and
`rustup_home`, which are the canonical way to determine the location
that Cargo and rustup store their data.

> This crate is maintained by the Cargo team, primarily for use by Cargo and Rustup
> and not intended for external use. This
> crate may make major changes to its APIs or be deprecated without warning.

[rust-lang/rust#43321]: https://github.com/rust-lang/rust/issues/43321
[`home_dir`]: https://doc.rust-lang.org/nightly/std/env/fn.home_dir.html
[1.85.0]: https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/#updates-to-std-env-home-dir

## License

MIT OR Apache-2.0

---

## File: crates/crates-io/README.md

> This crate is maintained by the Cargo team for use by the wider
> ecosystem. This crate follows semver compatibility for its APIs.