]>
Commit | Line | Data |
---|---|---|
0a29b90c FG |
1 | // For various reasons, some idioms are still allow'ed, but we would like to |
2 | // test and enforce them. | |
3 | #![warn(rust_2018_idioms)] | |
4 | // Due to some of the default clippy lints being somewhat subjective and not | |
5 | // necessarily an improvement, we prefer to not use them at this time. | |
6 | #![allow(clippy::all)] | |
7 | #![warn(clippy::disallowed_methods)] | |
8 | #![warn(clippy::self_named_module_files)] | |
9 | #![allow(rustdoc::private_intra_doc_links)] | |
10 | ||
11 | //! # Cargo as a library | |
12 | //! | |
13 | //! There are two places you can find API documentation of cargo-the-library, | |
14 | //! | |
15 | //! - <https://docs.rs/cargo>: targeted at external tool developers using cargo-the-library | |
16 | //! - Released with every rustc release | |
17 | //! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>: targeted at cargo contributors | |
18 | //! - Updated on each update of the `cargo` submodule in `rust-lang/rust` | |
19 | //! | |
20 | //! **WARNING:** Using Cargo as a library has drawbacks, particulary the API is unstable, | |
21 | //! and there is no clear path to stabilize it soon at the time of writing. See [The Cargo Book: | |
22 | //! External tools] for more on this topic. | |
23 | //! | |
24 | //! ## Overview | |
25 | //! | |
26 | //! Major components of cargo include: | |
27 | //! | |
28 | //! - [`ops`]: | |
29 | //! Every major operation is implemented here. Each command is a thin wrapper around ops. | |
30 | //! - [`ops::cargo_compile`]: | |
31 | //! This is the entry point for all the compilation commands. This is a | |
32 | //! good place to start if you want to follow how compilation starts and | |
33 | //! flows to completion. | |
34 | //! - [`ops::resolve`]: | |
35 | //! Top-level API for dependency and feature resolver (e.g. [`ops::resolve_ws`]) | |
36 | //! - [`core::resolver`]: The core algorithm | |
37 | //! - [`core::compiler`]: | |
38 | //! This is the code responsible for running `rustc` and `rustdoc`. | |
39 | //! - [`core::compiler::build_context`]: | |
49aad941 | 40 | //! The [`BuildContext`][core::compiler::BuildContext] is the result of the "front end" of the |
0a29b90c FG |
41 | //! build process. This contains the graph of work to perform and any settings necessary for |
42 | //! `rustc`. After this is built, the next stage of building is handled in | |
43 | //! [`Context`][core::compiler::Context]. | |
44 | //! - [`core::compiler::context`]: | |
45 | //! The `Context` is the mutable state used during the build process. This | |
46 | //! is the core of the build process, and everything is coordinated through | |
47 | //! this. | |
48 | //! - [`core::compiler::fingerprint`]: | |
49 | //! The `fingerprint` module contains all the code that handles detecting | |
50 | //! if a crate needs to be recompiled. | |
51 | //! - [`core::source`]: | |
52 | //! The [`core::Source`] trait is an abstraction over different sources of packages. | |
53 | //! Sources are uniquely identified by a [`core::SourceId`]. Sources are implemented in the [`sources`] | |
54 | //! directory. | |
55 | //! - [`util`]: | |
56 | //! This directory contains generally-useful utility modules. | |
57 | //! - [`util::config`]: | |
58 | //! This directory contains the config parser. It makes heavy use of | |
59 | //! [serde](https://serde.rs/) to merge and translate config values. The | |
60 | //! [`util::Config`] is usually accessed from the | |
61 | //! [`core::Workspace`] | |
62 | //! though references to it are scattered around for more convenient access. | |
63 | //! - [`util::toml`]: | |
64 | //! This directory contains the code for parsing `Cargo.toml` files. | |
65 | //! - [`ops::lockfile`]: | |
66 | //! This is where `Cargo.lock` files are loaded and saved. | |
67 | //! | |
68 | //! Related crates: | |
69 | //! - [`cargo-platform`](https://crates.io/crates/cargo-platform) | |
70 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_platform)): | |
71 | //! This library handles parsing `cfg` expressions. | |
72 | //! - [`cargo-util`](https://crates.io/crates/cargo-util) | |
73 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_util)): | |
74 | //! This contains general utility code that is shared between cargo and the testsuite | |
75 | //! - [`crates-io`](https://crates.io/crates/crates-io) | |
76 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/crates_io)): | |
77 | //! This contains code for accessing the crates.io API. | |
78 | //! - [`home`](https://crates.io/crates/home): | |
79 | //! This library is shared between cargo and rustup and is used for finding their home directories. | |
80 | //! This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io. | |
81 | //! It is intended to be versioned and published independently of Rust's release system. | |
82 | //! Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version. | |
83 | //! - [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support) | |
84 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_support/index.html)): | |
85 | //! This contains a variety of code to support writing tests | |
86 | //! - [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro) | |
87 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_macro/index.html)): | |
88 | //! This is the `#[cargo_test]` proc-macro used by the test suite to define tests. | |
49aad941 | 89 | //! - [`credential`](https://github.com/rust-lang/cargo/tree/master/credential) |
0a29b90c FG |
90 | //! This subdirectory contains several packages for implementing the |
91 | //! experimental | |
92 | //! [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process) | |
93 | //! feature. | |
94 | //! - [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman) | |
95 | //! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/mdman/index.html)): | |
96 | //! This is a utility for generating cargo's man pages. See [Building the man | |
97 | //! pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages) | |
98 | //! for more information. | |
99 | //! - [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests) | |
100 | //! This is a dedicated package that defines tests for the [dependency | |
101 | //! resolver][core::resolver]. | |
102 | //! | |
103 | //! ### File Overview | |
104 | //! | |
105 | //! Files that interact with cargo include | |
106 | //! | |
107 | //! - Package | |
108 | //! - `Cargo.toml`: User-written project manifest, loaded with [`util::toml::TomlManifest`] and then | |
109 | //! translated to [`core::manifest::Manifest`] which maybe stored in a [`core::Package`]. | |
110 | //! - This is editable with [`util::toml_mut::manifest::LocalManifest`] | |
111 | //! - `Cargo.lock`: Generally loaded with [`ops::resolve_ws`] or a variant of it into a [`core::resolver::Resolve`] | |
112 | //! - At the lowest level, [`ops::load_pkg_lockfile`] and [`ops::write_pkg_lockfile`] are used | |
113 | //! - See [`core::resolver::encode`] for versioning of `Cargo.lock` | |
114 | //! - `target/`: Used for build artifacts and abstracted with [`core::compiler::layout`]. `Layout` handles locking the target directory and providing paths to parts inside. There is a separate `Layout` for each build `target`. | |
115 | //! - `target/debug/.fingerprint`: Tracker whether nor not a crate needs to be rebuilt. See [`core::compiler::fingerprint`] | |
116 | //! - `$CARGO_HOME/`: | |
117 | //! - `registry/`: Package registry cache which is managed in [`sources::registry`]. Be careful | |
118 | //! as the lock [`util::Config::acquire_package_cache_lock`] must be manually acquired. | |
119 | //! - `index`/: Fast-to-access crate metadata (no need to download / extract `*.crate` files) | |
120 | //! - `cache/*/*.crate`: Local cache of published crates | |
121 | //! - `src/*/*`: Extracted from `*.crate` by [`sources::registry::RegistrySource`] | |
122 | //! - `git/`: Git source cache. See [`sources::git`]. | |
123 | //! - `**/.cargo/config.toml`: Environment dependent (env variables, files) configuration. See | |
124 | //! [`util::config`] | |
125 | //! | |
126 | //! ## Contribute to Cargo documentations | |
127 | //! | |
128 | //! The Cargo team always continues improving all external and internal documentations. | |
129 | //! If you spot anything could be better, don't hesitate to discuss with the team on | |
130 | //! Zulip [`t-cargo` stream], or [submit an issue] right on GitHub. | |
131 | //! There is also an issue label [`A-documenting-cargo-itself`], | |
132 | //! which is generally for documenting user-facing [The Cargo Book], | |
133 | //! but the Cargo team is welcome any form of enhancement for the [Cargo Contributor Guide] | |
134 | //! and this API documentation as well. | |
135 | //! | |
136 | //! [The Cargo Book: External tools]: https://doc.rust-lang.org/stable/cargo/reference/external-tools.html | |
137 | //! [Cargo Architecture Overview]: https://doc.crates.io/contrib/architecture | |
138 | //! [`t-cargo` stream]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo | |
139 | //! [submit an issue]: https://github.com/rust-lang/cargo/issues/new/choose | |
140 | //! [`A-documenting-cargo-itself`]: https://github.com/rust-lang/cargo/labels/A-documenting-cargo-itself | |
141 | //! [The Cargo Book]: https://doc.rust-lang.org/cargo/ | |
142 | //! [Cargo Contributor Guide]: https://doc.crates.io/contrib/ | |
143 | ||
144 | use crate::core::shell::Verbosity::Verbose; | |
145 | use crate::core::Shell; | |
146 | use anyhow::Error; | |
147 | use log::debug; | |
148 | ||
149 | pub use crate::util::errors::{AlreadyPrintedError, InternalError, VerboseError}; | |
150 | pub use crate::util::{indented_lines, CargoResult, CliError, CliResult, Config}; | |
151 | pub use crate::version::version; | |
152 | ||
153 | pub const CARGO_ENV: &str = "CARGO"; | |
154 | ||
155 | #[macro_use] | |
156 | mod macros; | |
157 | ||
158 | pub mod core; | |
159 | pub mod ops; | |
160 | pub mod sources; | |
161 | pub mod util; | |
162 | mod version; | |
163 | ||
164 | pub fn exit_with_error(err: CliError, shell: &mut Shell) -> ! { | |
165 | debug!("exit_with_error; err={:?}", err); | |
166 | ||
167 | if let Some(ref err) = err.error { | |
168 | if let Some(clap_err) = err.downcast_ref::<clap::Error>() { | |
169 | let exit_code = if clap_err.use_stderr() { 1 } else { 0 }; | |
170 | let _ = clap_err.print(); | |
171 | std::process::exit(exit_code) | |
172 | } | |
173 | } | |
174 | ||
175 | let CliError { error, exit_code } = err; | |
176 | if let Some(error) = error { | |
177 | display_error(&error, shell); | |
178 | } | |
179 | ||
180 | std::process::exit(exit_code) | |
181 | } | |
182 | ||
183 | /// Displays an error, and all its causes, to stderr. | |
184 | pub fn display_error(err: &Error, shell: &mut Shell) { | |
185 | debug!("display_error; err={:?}", err); | |
186 | _display_error(err, shell, true); | |
187 | if err | |
188 | .chain() | |
189 | .any(|e| e.downcast_ref::<InternalError>().is_some()) | |
190 | { | |
191 | drop(shell.note("this is an unexpected cargo internal error")); | |
192 | drop( | |
193 | shell.note( | |
194 | "we would appreciate a bug report: https://github.com/rust-lang/cargo/issues/", | |
195 | ), | |
196 | ); | |
197 | drop(shell.note(format!("cargo {}", version()))); | |
198 | // Once backtraces are stabilized, this should print out a backtrace | |
199 | // if it is available. | |
200 | } | |
201 | } | |
202 | ||
203 | /// Displays a warning, with an error object providing detailed information | |
204 | /// and context. | |
205 | pub fn display_warning_with_error(warning: &str, err: &Error, shell: &mut Shell) { | |
206 | drop(shell.warn(warning)); | |
207 | drop(writeln!(shell.err())); | |
208 | _display_error(err, shell, false); | |
209 | } | |
210 | ||
211 | fn _display_error(err: &Error, shell: &mut Shell, as_err: bool) -> bool { | |
212 | for (i, err) in err.chain().enumerate() { | |
213 | // If we're not in verbose mode then only print cause chain until one | |
214 | // marked as `VerboseError` appears. | |
215 | // | |
216 | // Generally the top error shouldn't be verbose, but check it anyways. | |
217 | if shell.verbosity() != Verbose && err.is::<VerboseError>() { | |
218 | return true; | |
219 | } | |
220 | if err.is::<AlreadyPrintedError>() { | |
221 | break; | |
222 | } | |
223 | if i == 0 { | |
224 | if as_err { | |
225 | drop(shell.error(&err)); | |
226 | } else { | |
227 | drop(writeln!(shell.err(), "{}", err)); | |
228 | } | |
229 | } else { | |
230 | drop(writeln!(shell.err(), "\nCaused by:")); | |
231 | drop(write!(shell.err(), "{}", indented_lines(&err.to_string()))); | |
232 | } | |
233 | } | |
234 | false | |
235 | } |