Migration Guide: v0.15 to v0.16 with the JSON output format
Enabling json output
In v0.15, json lines output could be enabled by providing the --output-format json
option as part of
the top level cargo msrv
(find) command. cargo msrv find --output-format json verify
was a valid way to specify
the output-format option, while cargo msrv verify --output-format json
would not work (because --output-format
was
not defined for the subcommand, verify
in this example).
This is no longer required; --output-format
is now a global option, so in the above examples, both cases will now
work.
NB: To determine the MSRV for a project, you should now run cargo msrv find
instead of just cargo msrv
. The top
level command was moved to its own subcommand for consistency and more correct CLI argument parsing.
Message type tag
In v0.15, json messages were tagged using a field named reason
. From v0.16 onwards, this field has been renamed
to type
instead. Please refer to the JSON output format page for a list of supported
messages.
Message replacements
In this section, we will discuss the previously supported json messages, and provide suggestions of their replacements.
Mode
A json message with reason mode
reported what command was running. Its direct replacement is the subcommand_init
message. The v0.15 mode
message also reported about the toolchain used, and which rustup run command was used
to check for compatibility. These however are only relevant when running a command which checks for compatibility.
Since we now also have command which do not check for compatibility, such as cargo msrv show
and cargo msrv set
,
this was a good moment to move these fields out of this type of message. The new check_method
message can tell you
both about the toolchain used for compatibility checks, and about the compatibility check method via its method
field.
If this method has type rustup_run
, then the args will contain the compatibility check arguments, previously known
as the check_cmd
.
The v0.15 mode
message consisted of:
{
"reason": "mode",
// The mode in which cargo-msrv will operate
"mode": "determine-msrv" /* OR */ "mode": "verify-msrv" /* OR */ "list-msrv" ,
// The toolchain that will be used
"toolchain":"x86_64-unknown-linux-gnu",
// Command used to check a version. The key will be absent for mode 'list'
"check_cmd":"cargo check"
}
Examples of messages which replace the information reported by the v0.15 mode
message:
...
{
"type": "subcommand_init",
"subcommand_id": "find"
}
...
{
"type": "check_method",
"toolchain": {
"version": "1.38.0",
"target": "x86_64-pc-windows-msvc"
},
"method": {
"type": "rustup_run",
"args": [
"1.38.0-x86_64-pc-windows-msvc",
"cargo",
"check"
],
"path": "..\\air3"
}
}
...
Installing and Checking
The installing
and checking
messages reported respectively about locating or installing a specific Rust toolchain
and checking that toolchain for compatibility. The former has been replaced by the setup_toolchain
event, while the
latter has been replaced by the check_toolchain
event. Reporting about the progress has been replaced by the
progress
event.
Previously, you would receive the following event:
{
"reason": "installing", /* OR */ "reason": "checking",
// The current version being installed or checked
"version": "1.25.0",
// The number of versions checked before this
"step": 0,
// The total number of versions to be checked
"total": 55,
// The toolchain that is being used
"toolchain": "x86_64-unknown-linux-gnu",
// The command used to check each version. The key will be absent for mode 'list'
"check_cmd": "cargo check"
}
And now, you instead receive these events:
...
{
"type": "progress",
"current": 25,
"search_space_size": 34,
"iteration": 2
}
...
{
"type": "setup_toolchain",
"toolchain": {
"version": "1.38.0",
"target": "x86_64-pc-windows-msvc"
},
"scope": {
"id": 2,
"marker": "start"
}
}
{
"type": "setup_toolchain",
"toolchain": {
"version": "1.38.0",
"target": "x86_64-pc-windows-msvc"
},
"scope": {
"id": 2,
"marker": "end"
}
}
...
{
"type": "check_toolchain",
"toolchain": {
"version": "1.39.0",
"target": "x86_64-pc-windows-msvc"
},
"scope": {
"id": 4,
"marker": "start"
}
}
{
"type": "check_toolchain",
"toolchain": {
"version": "1.39.0",
"target": "x86_64-pc-windows-msvc"
},
"scope": {
"id": 4,
"marker": "end"
}
}
Check complete
The check-complete
message would be reported when a check, which determined whether the toolchain version under test
is compatible, completed. It has been replaced by the check_result
event. The result of the compatibility check is now
reported via the is_compatible
field, instead of the success
field. The progress report can be followed via the
progress
event, and the check_cmd
may be found by inspecting the check_method
event, via the method.args
field,
assuming that the rustup_run
method (method.type
) is used.
Previously, you would receive the following event:
{
"reason": "check-complete",
// The version that was just checked
"version": "1.25.0",
// The number of versions checked before this
"step": 0,
// The total number of versions to be checked
"total": 55,
// true if this version is supported
"success": false,
// The toolchain that is being used
"toolchain": "x86_64-unknown-linux-gnu",
// The command used to check each version
"check_cmd": "cargo check"
}
And now, you instead receive these events, if the toolchain is compatible:
...
{
"type": "progress",
"current": 26,
"search_space_size": 34,
"iteration": 27
}
...
{
"type": "check_method",
"toolchain": {
"version": "1.38.0",
"target": "x86_64-pc-windows-msvc"
},
"method": {
"type": "rustup_run",
"args": [
"1.38.0-x86_64-pc-windows-msvc",
"cargo",
"check"
],
"path": "..\\air3"
}
}
...
{
"type": "check_result",
"toolchain": {
"version": "1.38.0",
"target": "x86_64-pc-windows-msvc"
},
"is_compatible": true
}
Or, if the toolchain is deemed incompatible:
{
"type": "progress",
"current": 27,
"search_space_size": 34,
"iteration": 28
}
...
{
"type": "check_method",
"toolchain": {
"version": "1.37.0",
"target": "x86_64-pc-windows-msvc"
},
"method": {
"type": "rustup_run",
"args": [
"1.37.0-x86_64-pc-windows-msvc",
"cargo",
"check"
],
"path": "..\\air3"
}
}
...
{
"type": "check_result",
"toolchain": {
"version": "1.37.0",
"target": "x86_64-pc-windows-msvc"
},
"is_compatible": false,
"error": "error: failed to parse lock file at: ..\\air3\\Cargo.lock\n\nCaused by:\n invalid serialized PackageId for key `package.dependencies`\n"
}
MSRV completed
When the find msrv command or the verify command would be completed, they would report about their result.
The success field would respectively be used to report whether an MSRV had been found, or whether the MSRV being
verified
was compatible or not. These messages, msrv-complete
and verify-complete
have been replaced by the
subcommand_result
event. Please refer to the subcommand_result event for the complete
description of output per command.
The v0.15 output had the following format:
{
"reason": "msrv-complete" /* OR */ "reason": "verify-complete",
// true if a msrv was found
"success": true,
// the msrv if found. The key will be absent if msrv wasn't found
"msrv": "1.42.0",
// The toolchain that is being used
"toolchain": "x86_64-unknown-linux-gnu",
// The command used to check each version. The key will be absent for mode 'list'
"check_cmd": "cargo check"
}
Below, you can find an example of the new output when finding the MSRV, where one is found:
{
"type": "subcommand_result",
"subcommand_id": "find",
"result": {
"version": "1.38.0",
"success": true
}
}
And another example for the output of the verify command, where the verification failed:
{
"type": "subcommand_result",
"subcommand_id": "verify",
"result": {
"toolchain": {
"version": "1.60.0",
"target": "x86_64-pc-windows-msvc"
},
"is_compatible": false,
"error": " Checking air v0.0.0 (..\\air)\nerror: expected one of `:`, `<`, `=`, `where`, or `{`, found `<eof>`\n --> src\\lib.rs:24:11\n |\n24 | pub trait DisplayEvent\n | ^^^^^^^^^^^^ expected one of `:`, `<`, `=`, `where`, or `{`\n\nerror: could not compile `air` due to previous error\n"
}
}
List MSRV's specified by crate authors
This event is contains the output of the list command, which reports about the MSRV of the dependencies of the given
crate.
The exact output depends on which variant is used, either ordered-by-msrv
(default) or direct-deps
.
The output of the list command is almost the same as it was before. The event is no longer called list
; instead
the output is given via the subcommand_result
event, where the value of subcommand_id
is list
. The output of the
command (variant
and list
fields) can now be found as part of the result
field. The success
field has been
removed.
{
"reason": "list",
// output variant
"variant": "ordered-by-msrv" /* OR */ "direct-deps",
// always success when returning a result
"success": true,
// The output of the list subcommand
"list": [
/* when variant = 'ordered-by-msrv */
{
"msrv": "<msrv>",
"dependencies": ["<dependencies which have this msrv>", ...]
}
/* OR, when variant = direct-deps */
{
"dependency": "<dependency crate name>",
"version": "<dependency crate version>",
"msrv": "<dependency crate msrv>",
"depends_on": ["<dependencies of direct dependency crate>", ...]
}
],
}
An example of the ordered-by-msrv
variant:
{
"type": "subcommand_result",
"subcommand_id": "list",
"result": {
"variant": "ordered-by-msrv",
"list": [
{
"msrv": "1.38.0",
"dependencies": [
"storyteller"
]
},
{
"msrv": "1.36.0",
"dependencies": [
"crossbeam-channel",
"crossbeam-utils"
]
},
{
"msrv": null,
"dependencies": [
"cfg-if",
"lazy_static"
]
}
]
}
}
An example of the direct-deps
variant:
{
"type": "subcommand_result",
"subcommand_id": "list",
"result": {
"variant": "direct-deps",
"list": [
{
"name": "crossbeam-channel",
"version": "0.5.4",
"msrv": "1.36.0",
"dependencies": [
"cfg-if",
"crossbeam-utils",
"num_cpus",
"rand",
"signal-hook"
]
}
]
}
}