@@ -4,7 +4,7 @@ One of the goals of Cargo is simple integration with third-party tools, like
44IDEs and other build systems. To make integration easier, Cargo has several
55facilities:
66
7- * a ` cargo metadata ` command, which outputs package structure and dependencies
7+ * a [ ` cargo metadata ` ] command, which outputs package structure and dependencies
88 information in JSON,
99
1010* a ` --message-format ` flag, which outputs information about a particular build,
@@ -15,60 +15,21 @@ facilities:
1515
1616### Information about package structure
1717
18- You can use ` cargo metadata ` command to get information about package structure
19- and dependencies. The output of the command looks like this:
20-
21- ``` text
22- {
23- // Integer version number of the format.
24- "version": integer,
25-
26- // List of packages for this workspace, including dependencies.
27- "packages": [
28- {
29- // Opaque package identifier.
30- "id": PackageId,
31-
32- "name": string,
33-
34- "version": string,
35-
36- "source": SourceId,
37-
38- // A list of declared dependencies, see `resolve` field for actual dependencies.
39- "dependencies": [ Dependency ],
40-
41- "targets: [ Target ],
42-
43- // Path to Cargo.toml
44- "manifest_path": string,
45- }
46- ],
47-
48- "workspace_members": [ PackageId ],
49-
50- // Dependencies graph.
51- "resolve": {
52- "nodes": [
53- {
54- "id": PackageId,
55- "dependencies": [ PackageId ]
56- }
57- ]
58- }
59- }
60- ```
18+ You can use [ ` cargo metadata ` ] command to get information about package
19+ structure and dependencies. See the [ ` cargo metadata ` ] documentation
20+ for details on the format of the output.
6121
6222The format is stable and versioned. When calling ` cargo metadata ` , you should
6323pass ` --format-version ` flag explicitly to avoid forward incompatibility
6424hazard.
6525
66- If you are using Rust, there is [ cargo_metadata] crate.
26+ If you are using Rust, the [ cargo_metadata] crate can be used to parse the
27+ output.
6728
6829[ cargo_metadata ] : https://crates.io/crates/cargo_metadata
30+ [ `cargo metadata` ] : ../commands/cargo-metadata.md
6931
70-
71- ### Information about build
32+ ### JSON messages
7233
7334When passing ` --message-format=json ` , Cargo will output the following
7435information during the build:
@@ -82,9 +43,175 @@ information during the build:
8243The output goes to stdout in the JSON object per line format. The ` reason ` field
8344distinguishes different kinds of messages.
8445
85- Information about dependencies in the Makefile-compatible format is stored in
86- the ` .d ` files alongside the artifacts.
46+ The ` --message-format ` option can also take additional formatting values which
47+ alter the way the JSON messages are computed and rendered. See the description
48+ of the ` --message-format ` option in the [ build command documentation] for more
49+ details.
8750
51+ [ build command documentation ] : ../commands/cargo-build.md
52+
53+ #### Compiler messages
54+
55+ The "compiler-message" message includes output from the compiler, such as
56+ warnings and errors. See the [ rustc JSON chapter] ( ../../rustc/json.md ) for
57+ details on ` rustc ` 's message format, which is embedded in the following
58+ structure:
59+
60+ ``` javascript
61+ {
62+ /* The "reason" indicates the kind of message. */
63+ " reason" : " compiler-message"
64+ /* The Package ID, a unique identifier for referring to the package. */
65+ " package_id" : " my-package 0.1.0 (path+file:///path/to/my-package)"
66+ /* The Cargo target (lib, bin, example, etc.) that generated the message. */
67+ " target" : {
68+ /* Array of target kinds.
69+ - lib targets list the `crate-type` values from the
70+ manifest such as "lib", "rlib", "dylib",
71+ "proc-macro", etc. (default ["lib"])
72+ - binary is ["bin"]
73+ - example is ["example"]
74+ - integration test is ["test"]
75+ - benchmark is ["bench"]
76+ - build script is ["custom-build"]
77+ */
78+ " kind" : [
79+ " lib"
80+ ],
81+ /* Array of crate types.
82+ - lib and example libraries list the `crate-type` values
83+ from the manifest such as "lib", "rlib", "dylib",
84+ "proc-macro", etc. (default ["lib"])
85+ - all other target kinds are ["bin"]
86+ */
87+ " crate_types" : [
88+ " lib"
89+ ],
90+ /* The name of the target. */
91+ " name" : " my-package"
92+ /* Absolute path to the root source file of the target. */
93+ " src_path" : " /path/to/my-package/src/lib.rs"
94+ /* The Rust edition of the target.
95+ Defaults to the package edition.
96+ */
97+ " edition" : " 2018"
98+ /* Array of required features.
99+ This property is not included if no required features are set.
100+ */
101+ " required-features" : [" feat1"
102+ /* Whether or not this target has doc tests enabled, and
103+ the target is compatible with doc testing.
104+ */
105+ " doctest" : true
106+ },
107+ /* The message emitted by the compiler.
108+
109+ See https://doc.rust-lang.org/rustc/json.html for details.
110+ */
111+ " message" : {
112+ /* ... */
113+ }
114+ }
115+ ```
116+
117+ #### Artifact messages
118+
119+ For every compilation step, a "compiler-artifact" message is emitted with the
120+ following structure:
121+
122+ ``` javascript
123+ {
124+ /* The "reason" indicates the kind of message. */
125+ " reason" : " compiler-artifact"
126+ /* The Package ID, a unique identifier for referring to the package. */
127+ " package_id" : " my-package 0.1.0 (path+file:///path/to/my-package)"
128+ /* The Cargo target (lib, bin, example, etc.) that generated the artifacts.
129+ See the definition above for `compiler-message` for details.
130+ */
131+ " target" : {
132+ " kind" : [
133+ " lib"
134+ ],
135+ " crate_types" : [
136+ " lib"
137+ ],
138+ " name" : " my-package"
139+ " src_path" : " /path/to/my-package/src/lib.rs"
140+ " edition" : " 2018"
141+ " doctest" : true
142+ },
143+ /* The profile indicates which compiler settings were used. */
144+ " profile" : {
145+ /* The optimization level. */
146+ " opt_level" : " 0"
147+ /* The debug level, an integer of 0, 1, or 2. If `null`, it implies
148+ rustc's default of 0.
149+ */
150+ " debuginfo" : 2 ,
151+ /* Whether or not debug assertions are enabled. */
152+ " debug_assertions" : true ,
153+ /* Whether or not overflow checks are enabled. */
154+ " overflow_checks" : true ,
155+ /* Whether or not the `--test` flag is used. */
156+ " test" : false
157+ },
158+ /* Array of features enabled. */
159+ " features" : [" feat1" " feat2"
160+ /* Array of files generated by this step. */
161+ " filenames" : [
162+ " /path/to/my-package/target/debug/libmy_package.rlib"
163+ " /path/to/my-package/target/debug/deps/libmy_package-be9f3faac0a26ef0.rmeta"
164+ ],
165+ /* A string of the path to the executable that was created, or null if
166+ this step did not generate an executable.
167+ */
168+ " executable" : null ,
169+ /* Whether or not this step was actually executed.
170+ When `true`, this means that the pre-existing artifacts were
171+ up-to-date, and `rustc` was not executed. When `false`, this means that
172+ `rustc` was run to generate the artifacts.
173+ */
174+ " fresh" : true
175+ }
176+
177+ ```
178+
179+ #### Build script output
180+
181+ The "build-script-executed" message includes the parsed output of a build
182+ script. Note that this is emitted even if the build script is not run; it will
183+ display the previously cached value. More details about build script output
184+ may be found in [ the chapter on build scripts] ( build-scripts.md ) .
185+
186+ ``` javascript
187+ {
188+ /* The "reason" indicates the kind of message. */
189+ " reason" : " build-script-executed"
190+ /* The Package ID, a unique identifier for referring to the package. */
191+ " package_id" : " my-package 0.1.0 (path+file:///path/to/my-package)"
192+ /* Array of libraries to link, as indicated by the `cargo:rustc-link-lib`
193+ instruction. Note that this may include a "KIND=" prefix in the string
194+ where KIND is the library kind.
195+ */
196+ " linked_libs" : [" foo" " static=bar"
197+ /* Array of paths to include in the library search path, as indicated by
198+ the `cargo:rustc-link-search` instruction. Note that this may include a
199+ "KIND=" prefix in the string where KIND is the library kind.
200+ */
201+ " linked_paths" : [" /some/path" " native=/another/path"
202+ /* Array of cfg values to enable, as indicated by the `cargo:rustc-cfg`
203+ instruction.
204+ */
205+ " cfgs" : [" cfg1" " cfg2=\" string\" "
206+ /* Array of [KEY, VALUE] arrays of environment variables to set, as
207+ indicated by the `cargo:rustc-env` instruction.
208+ */
209+ " env" : [
210+ [" SOME_KEY" " some value"
211+ [" ANOTHER_KEY" " another value"
212+ ]
213+ }
214+ ```
88215
89216### Custom subcommands
90217
0 commit comments