| # cargo-metadata(1) |
| |
| ## NAME |
| |
| cargo-metadata --- Machine-readable metadata about the current package |
| |
| ## SYNOPSIS |
| |
| `cargo metadata` [_options_] |
| |
| ## DESCRIPTION |
| |
| Output JSON to stdout containing information about the workspace members and |
| resolved dependencies of the current package. |
| |
| The output format is subject to change in future versions of Cargo. It |
| is recommended to include the `--format-version` flag to future-proof your code |
| and ensure the output is in the format you are expecting. For more on the |
| expectations, see ["Compatibility"](#compatibility). |
| |
| See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) |
| for a Rust API for reading the metadata. |
| |
| ## OUTPUT FORMAT |
| |
| ### Compatibility |
| |
| Within the same output format version, the compatibility is maintained, except |
| some scenarios. The following is a non-exhaustive list of changes that are not |
| considered as incompatible: |
| |
| * **Adding new fields** — New fields will be added when needed. Reserving this |
| helps Cargo evolve without bumping the format version too often. |
| * **Adding new values for enum-like fields** — Same as adding new fields. It |
| keeps metadata evolving without stagnation. |
| * **Changing opaque representations** — The inner representations of some |
| fields are implementation details. For example, fields related to |
| "Source ID" are treated as opaque identifiers to differentiate packages or |
| sources. Consumers shouldn't rely on those representations unless specified. |
| |
| ### JSON format |
| |
| The JSON output has the following format: |
| |
| ```javascript |
| { |
| /* Array of all packages in the workspace. |
| It also includes all feature-enabled dependencies unless --no-deps is used. |
| */ |
| "packages": [ |
| { |
| /* The name of the package. */ |
| "name": "my-package", |
| /* The version of the package. */ |
| "version": "0.1.0", |
| /* The Package ID for referring to the |
| package within the document and as the `--package` argument to many commands |
| */ |
| "id": "file:///path/to/my-package#0.1.0", |
| /* The license value from the manifest, or null. */ |
| "license": "MIT/Apache-2.0", |
| /* The license-file value from the manifest, or null. */ |
| "license_file": "LICENSE", |
| /* The description value from the manifest, or null. */ |
| "description": "Package description.", |
| /* The source ID of the package, an "opaque" identifier representing |
| where a package is retrieved from. See "Compatibility" above for |
| the stability guarantee. |
| |
| This is null for path dependencies and workspace members. |
| |
| For other dependencies, it is a string with the format: |
| - "registry+URL" for registry-based dependencies. |
| Example: "registry+https://github.com/rust-lang/crates.io-index" |
| - "git+URL" for git-based dependencies. |
| Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" |
| - "sparse+URL" for dependencies from a sparse registry |
| Example: "sparse+https://my-sparse-registry.org" |
| |
| The value after the `+` is not explicitly defined, and may change |
| between versions of Cargo and may not directly correlate to other |
| things, such as registry definitions in a config file. New source |
| kinds may be added in the future which will have different `+` |
| prefixed identifiers. |
| */ |
| "source": null, |
| /* Array of dependencies declared in the package's manifest. */ |
| "dependencies": [ |
| { |
| /* The name of the dependency. */ |
| "name": "bitflags", |
| /* The source ID of the dependency. May be null, see |
| description for the package source. |
| */ |
| "source": "registry+https://github.com/rust-lang/crates.io-index", |
| /* The version requirement for the dependency. |
| Dependencies without a version requirement have a value of "*". |
| */ |
| "req": "^1.0", |
| /* The dependency kind. |
| "dev", "build", or null for a normal dependency. |
| */ |
| "kind": null, |
| /* If the dependency is renamed, this is the new name for |
| the dependency as a string. null if it is not renamed. |
| */ |
| "rename": null, |
| /* Boolean of whether or not this is an optional dependency. */ |
| "optional": false, |
| /* Boolean of whether or not default features are enabled. */ |
| "uses_default_features": true, |
| /* Array of features enabled. */ |
| "features": [], |
| /* The target platform for the dependency. |
| null if not a target dependency. |
| */ |
| "target": "cfg(windows)", |
| /* The file system path for a local path dependency. |
| not present if not a path dependency. |
| */ |
| "path": "/path/to/dep", |
| /* A string of the URL of the registry this dependency is from. |
| If not specified or null, the dependency is from the default |
| registry (crates.io). |
| */ |
| "registry": null, |
| /* (unstable) Boolean flag of whether or not this is a pulbic |
| dependency. This field is only present when |
| `-Zpublic-dependency` is enabled. |
| */ |
| "public": false |
| } |
| ], |
| /* Array of Cargo targets. */ |
| "targets": [ |
| { |
| /* Array of target kinds. |
| - lib targets list the `crate-type` values from the |
| manifest such as "lib", "rlib", "dylib", |
| "proc-macro", etc. (default ["lib"]) |
| - binary is ["bin"] |
| - example is ["example"] |
| - integration test is ["test"] |
| - benchmark is ["bench"] |
| - build script is ["custom-build"] |
| */ |
| "kind": [ |
| "bin" |
| ], |
| /* Array of crate types. |
| - lib and example libraries list the `crate-type` values |
| from the manifest such as "lib", "rlib", "dylib", |
| "proc-macro", etc. (default ["lib"]) |
| - all other target kinds are ["bin"] |
| */ |
| "crate_types": [ |
| "bin" |
| ], |
| /* The name of the target. |
| For lib targets, dashes will be replaced with underscores. |
| */ |
| "name": "my-package", |
| /* Absolute path to the root source file of the target. */ |
| "src_path": "/path/to/my-package/src/main.rs", |
| /* The Rust edition of the target. |
| Defaults to the package edition. |
| */ |
| "edition": "2018", |
| /* Array of required features. |
| This property is not included if no required features are set. |
| */ |
| "required-features": ["feat1"], |
| /* Whether the target should be documented by `cargo doc`. */ |
| "doc": true, |
| /* Whether or not this target has doc tests enabled, and |
| the target is compatible with doc testing. |
| */ |
| "doctest": false, |
| /* Whether or not this target should be built and run with `--test` |
| */ |
| "test": true |
| } |
| ], |
| /* Set of features defined for the package. |
| Each feature maps to an array of features or dependencies it |
| enables. |
| */ |
| "features": { |
| "default": [ |
| "feat1" |
| ], |
| "feat1": [], |
| "feat2": [] |
| }, |
| /* Absolute path to this package's manifest. */ |
| "manifest_path": "/path/to/my-package/Cargo.toml", |
| /* Package metadata. |
| This is null if no metadata is specified. |
| */ |
| "metadata": { |
| "docs": { |
| "rs": { |
| "all-features": true |
| } |
| } |
| }, |
| /* List of registries to which this package may be published. |
| Publishing is unrestricted if null, and forbidden if an empty array. */ |
| "publish": [ |
| "crates-io" |
| ], |
| /* Array of authors from the manifest. |
| Empty array if no authors specified. |
| */ |
| "authors": [ |
| "Jane Doe <user@example.com>" |
| ], |
| /* Array of categories from the manifest. */ |
| "categories": [ |
| "command-line-utilities" |
| ], |
| /* Optional string that is the default binary picked by cargo run. */ |
| "default_run": null, |
| /* Optional string that is the minimum supported rust version */ |
| "rust_version": "1.56", |
| /* Array of keywords from the manifest. */ |
| "keywords": [ |
| "cli" |
| ], |
| /* The readme value from the manifest or null if not specified. */ |
| "readme": "README.md", |
| /* The repository value from the manifest or null if not specified. */ |
| "repository": "https://github.com/rust-lang/cargo", |
| /* The homepage value from the manifest or null if not specified. */ |
| "homepage": "https://rust-lang.org", |
| /* The documentation value from the manifest or null if not specified. */ |
| "documentation": "https://doc.rust-lang.org/stable/std", |
| /* The default edition of the package. |
| Note that individual targets may have different editions. |
| */ |
| "edition": "2018", |
| /* Optional string that is the name of a native library the package |
| is linking to. |
| */ |
| "links": null, |
| } |
| ], |
| /* Array of members of the workspace. |
| Each entry is the Package ID for the package. |
| */ |
| "workspace_members": [ |
| "file:///path/to/my-package#0.1.0", |
| ], |
| /* Array of default members of the workspace. |
| Each entry is the Package ID for the package. |
| */ |
| "workspace_default_members": [ |
| "file:///path/to/my-package#0.1.0", |
| ], |
| // The resolved dependency graph for the entire workspace. The enabled |
| // features are based on the enabled features for the "current" package. |
| // Inactivated optional dependencies are not listed. |
| // |
| // This is null if --no-deps is specified. |
| // |
| // By default, this includes all dependencies for all target platforms. |
| // The `--filter-platform` flag may be used to narrow to a specific |
| // target triple. |
| "resolve": { |
| /* Array of nodes within the dependency graph. |
| Each node is a package. |
| */ |
| "nodes": [ |
| { |
| /* The Package ID of this node. */ |
| "id": "file:///path/to/my-package#0.1.0", |
| /* The dependencies of this package, an array of Package IDs. */ |
| "dependencies": [ |
| "https://github.com/rust-lang/crates.io-index#bitflags@1.0.4" |
| ], |
| /* The dependencies of this package. This is an alternative to |
| "dependencies" which contains additional information. In |
| particular, this handles renamed dependencies. |
| */ |
| "deps": [ |
| { |
| /* The name of the dependency's library target. |
| If this is a renamed dependency, this is the new |
| name. |
| */ |
| "name": "bitflags", |
| /* The Package ID of the dependency. */ |
| "pkg": "https://github.com/rust-lang/crates.io-index#bitflags@1.0.4" |
| /* Array of dependency kinds. Added in Cargo 1.40. */ |
| "dep_kinds": [ |
| { |
| /* The dependency kind. |
| "dev", "build", or null for a normal dependency. |
| */ |
| "kind": null, |
| /* The target platform for the dependency. |
| null if not a target dependency. |
| */ |
| "target": "cfg(windows)" |
| } |
| ] |
| } |
| ], |
| /* Array of features enabled on this package. */ |
| "features": [ |
| "default" |
| ] |
| } |
| ], |
| /* The package in the current working directory (if --manifest-path is not given). |
| This is null if there is a virtual workspace. Otherwise it is |
| the Package ID of the package. |
| */ |
| "root": "file:///path/to/my-package#0.1.0", |
| }, |
| /* The absolute path to the target directory where Cargo places its output. */ |
| "target_directory": "/path/to/my-package/target", |
| /* The absolute path to the build directory where Cargo places intermediate build artifacts. (unstable) */ |
| "build_directory": "/path/to/my-package/build-dir", |
| /* The version of the schema for this metadata structure. |
| This will be changed if incompatible changes are ever made. |
| */ |
| "version": 1, |
| /* The absolute path to the root of the workspace. */ |
| "workspace_root": "/path/to/my-package" |
| /* Workspace metadata. |
| This is null if no metadata is specified. */ |
| "metadata": { |
| "docs": { |
| "rs": { |
| "all-features": true |
| } |
| } |
| } |
| } |
| ```` |
| |
| Notes: |
| - For `"id"` field syntax, see [Package ID Specifications] in the reference. |
| |
| ## OPTIONS |
| |
| ### Output Options |
| |
| {{#options}} |
| |
| {{#option "`--no-deps`" }} |
| Output information only about the workspace members and don't fetch |
| dependencies. |
| {{/option}} |
| |
| {{#option "`--format-version` _version_" }} |
| Specify the version of the output format to use. Currently `1` is the only |
| possible value. |
| {{/option}} |
| |
| {{#option "`--filter-platform` _triple_" }} |
| This filters the `resolve` output to only include dependencies for the |
| given [target triple](../appendix/glossary.html#target). |
| A literal `"host-tuple"` can be used, which will internally be substituted by the host's target. |
| Without this flag, the resolve includes all targets. |
| |
| Note that the dependencies listed in the "packages" array still includes all |
| dependencies. Each package definition is intended to be an unaltered |
| reproduction of the information within `Cargo.toml`. |
| {{/option}} |
| |
| {{/options}} |
| |
| {{> section-features }} |
| |
| ### Display Options |
| |
| {{#options}} |
| {{> options-display }} |
| {{/options}} |
| |
| ### Manifest Options |
| |
| {{#options}} |
| {{> options-manifest-path }} |
| |
| {{> options-locked }} |
| |
| {{> options-lockfile-path }} |
| {{/options}} |
| |
| {{> section-options-common }} |
| |
| {{> section-environment }} |
| |
| {{> section-exit-status }} |
| |
| ## EXAMPLES |
| |
| 1. Output JSON about the current package: |
| |
| cargo metadata --format-version=1 |
| |
| ## SEE ALSO |
| |
| {{man "cargo" 1}}, {{man "cargo-pkgid" 1}}, [Package ID Specifications], [JSON messages] |
| |
| [Package ID Specifications]: ../reference/pkgid-spec.html |
| [JSON messages]: ../reference/external-tools.html#json-messages |
