Module future_incompat

Support for future-incompatible warning reporting.

Here is an overview of how Cargo handles future-incompatible reports.

Receive reports from the compiler

When receiving a compiler message during a build, if it is effectively a FutureIncompatReport, Cargo gathers and forwards it as a Message::FutureIncompatReport to the main thread.

To have the correct layout of strucutures for deserializing a report emitted by the compiler, most of structure definitions, for example FutureIncompatReport, are copied either partially or entirely from compiler/rustc_errors/src/json.rs in rust-lang/rust repository.

Persist reports on disk

When a build comes to an end, by calling save_and_display_report Cargo saves the report on disk, and displays it directly if requested via command line or configuration. The information of the on-disk file can be found in FUTURE_INCOMPAT_FILE.

During the persistent process, Cargo will attempt to query the source of each package emitting the report, for the sake of providing an upgrade information as a solution to fix the incompatibility.

Display reports to users

Users can run cargo report future-incompat to retrieve a report. This is done by OnDiskReports::load. Cargo simply prints reports to the standard output.

Structs

Diagnostic

A diagnostic emitted by the compiler as a JSON message. We only care about the ‘rendered’ field

FutureBreakageItem

A single future-incompatible warning emitted by rustc.

FutureIncompatReport

The future incompatibility report, emitted by the compiler as a JSON message.

FutureIncompatReportPackage

Structure used for collecting reports in-memory.

OnDiskReport 🔒

A single report for a given compilation session.

OnDiskReports

The structure saved to disk containing the reports.

Constants

FUTURE_INCOMPAT_FILE 🔒

The filename in the top-level target directory where we store the report

MAX_REPORTS 🔒

Max number of reports to save on disk.

ON_DISK_VERSION 🔒

Current version of the on-disk format.

REPORT_PREAMBLE

Functions

get_updates 🔒

Returns a user-readable message explaining which of the packages in package_ids have updates available. This is best-effort - if an error occurs, None will be returned.

render_report 🔒

save_and_display_report

Writes a future-incompat report to disk, using the per-package reports gathered during the build. If requested by the user, a message is also displayed in the build output.