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 command. cargo msrv --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.

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"]}]}}

The cargo-msrv Book 🦀