Skip to content

Commit 1c89fe2

Browse files
weihangloweihanglo
committed
docs(package): man page and docs for cargo package --list=json 
1 parent 2110a27 commit 1c89fe2

File tree

4 files changed

+156
-5
lines changed

4 files changed

+156
-5
lines changed

‎src/doc/man/cargo-package.md‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,45 @@ There is no guarantee that the source code in the tarball matches the VCS inform
8181

8282
{{#options}}
8383

84-
{{#option "`-l`" "`--list`" }}
84+
{{#option "`-l`" "`--list`_[fmt]_" }}
8585
Print files included in a package without making one.
86+
87+
Specifying an output format (rather than the default) is unstable and requires
88+
`-Zunstable-options`. Valid output formats:
89+
90+
- `json` (unstable, requires `-Zunstable-options`): Emit machine-readable JSON
91+
information about each file.
92+
```javascript
93+
{
94+
/* The Package ID Spec of the package. */
95+
"path+file:///home/foo#0.0.0": {
96+
/* Relative path in the archive file. */
97+
"Cargo.toml.orig": {
98+
/* An absolute path to the actual file content. */
99+
"original_path": "/home/foo/Cargo.toml",
100+
/* The source of the file.
101+
- "existing" for file that exists on disk as-is.
102+
- "generate" for file being generated during packaging
103+
- "copied" for file copied from another location.
104+
The associated path points to a resolved symlink target
105+
or a normalized path outside the package root.
106+
*/
107+
"source": "copied"
108+
},
109+
"Cargo.toml": {
110+
"source": "generated"
111+
},
112+
"LICENSE": {
113+
"original_path": "/home/LICENSE",
114+
"source": "copied"
115+
},
116+
"main.rs": {
117+
"original_path": "/home/foo/main.rs",
118+
"source": "existing"
119+
},
120+
}
121+
}
122+
```
86123
{{/option}}
87124

88125
{{#option "`--no-verify`" }}

‎src/doc/man/generated_txt/cargo-package.txt‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,44 @@ DESCRIPTION
8282

8383
OPTIONS
8484
Package Options
85-
-l, --list
85+
-l, --list[fmt]
8686
Print files included in a package without making one.
8787

88+
Specifying an output format (rather than the default) is unstable
89+
and requires -Zunstable-options. Valid output formats:
90+
91+
o json (unstable, requires -Zunstable-options): Emit
92+
machine-readable JSON information about each file.
93+
{
94+
/* The Package ID Spec of the package. */
95+
"path+file:///home/foo#0.0.0": {
96+
/* Relative path in the archive file. */
97+
"Cargo.toml.orig": {
98+
/* An absolute path to the actual file content. */
99+
"original_path": "/home/foo/Cargo.toml",
100+
/* The source of the file.
101+
- "existing" for file that exists on disk as-is.
102+
- "generate" for file being generated during packaging
103+
- "copied" for file copied from another location.
104+
The associated path points to a resolved symlink target
105+
or a normalized path outside the package root.
106+
*/
107+
"source": "copied"
108+
},
109+
"Cargo.toml": {
110+
"source": "generated"
111+
},
112+
"LICENSE": {
113+
"original_path": "/home/LICENSE",
114+
"source": "copied"
115+
},
116+
"main.rs": {
117+
"original_path": "/home/foo/main.rs",
118+
"source": "existing"
119+
},
120+
}
121+
}
122+
88123
--no-verify
89124
Don’t verify the contents by building them.
90125

‎src/doc/src/commands/cargo-package.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,45 @@ There is no guarantee that the source code in the tarball matches the VCS inform
7777
<dl>
7878

7979
<dt class="option-term" id="option-cargo-package--l"><a class="option-anchor" href="#option-cargo-package--l"></a><code>-l</code></dt>
80-
<dt class="option-term" id="option-cargo-package---list"><a class="option-anchor" href="#option-cargo-package---list"></a><code>--list</code></dt>
81-
<dd class="option-desc">Print files included in a package without making one.</dd>
80+
<dt class="option-term" id="option-cargo-package---list[fmt]"><a class="option-anchor" href="#option-cargo-package---list[fmt]"></a><code>--list</code><em>[fmt]</em></dt>
81+
<dd class="option-desc">Print files included in a package without making one.</p>
82+
<p>Specifying an output format (rather than the default) is unstable and requires
83+
<code>-Zunstable-options</code>. Valid output formats:</p>
84+
<ul>
85+
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
86+
information about each file.
87+
<pre><code class="language-javascript">{
88+
/* The Package ID Spec of the package. */
89+
"path+file:///home/foo#0.0.0": {
90+
/* Relative path in the archive file. */
91+
"Cargo.toml.orig": {
92+
/* An absolute path to the actual file content. */
93+
"original_path": "/home/foo/Cargo.toml",
94+
/* The source of the file.
95+
- "existing" for file that exists on disk as-is.
96+
- "generate" for file being generated during packaging
97+
- "copied" for file copied from another location.
98+
The associated path points to a resolved symlink target
99+
or a normalized path outside the package root.
100+
*/
101+
"source": "copied"
102+
},
103+
"Cargo.toml": {
104+
"source": "generated"
105+
},
106+
"LICENSE": {
107+
"original_path": "/home/LICENSE",
108+
"source": "copied"
109+
},
110+
"main.rs": {
111+
"original_path": "/home/foo/main.rs",
112+
"source": "existing"
113+
},
114+
}
115+
}
116+
</code></pre>
117+
</li>
118+
</ul></dd>
82119

83120

84121
<dt class="option-term" id="option-cargo-package---no-verify"><a class="option-anchor" href="#option-cargo-package---no-verify"></a><code>--no-verify</code></dt>

‎src/etc/man/cargo-package.1‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,9 +106,51 @@ There is no guarantee that the source code in the tarball matches the VCS inform
106106
.SS "Package Options"
107107
.sp
108108
\fB\-l\fR,
109-
\fB\-\-list\fR
109+
\fB\-\-list\fR\fI[fmt]\fR
110110
.RS 4
111111
Print files included in a package without making one.
112+
.sp
113+
Specifying an output format (rather than the default) is unstable and requires
114+
\fB\-Zunstable\-options\fR\&. Valid output formats:
115+
.sp
116+
.RS 4
117+
\h'-04'\(bu\h'+03'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
118+
information about each file.
119+
.sp
120+
.RS 4
121+
.nf
122+
{
123+
/* The Package ID Spec of the package. */
124+
"path+file:///home/foo#0.0.0": {
125+
/* Relative path in the archive file. */
126+
"Cargo.toml.orig": {
127+
/* An absolute path to the actual file content. */
128+
"original_path": "/home/foo/Cargo.toml",
129+
/* The source of the file.
130+
\- "existing" for file that exists on disk as\-is.
131+
\- "generate" for file being generated during packaging
132+
\- "copied" for file copied from another location.
133+
The associated path points to a resolved symlink target
134+
or a normalized path outside the package root.
135+
*/
136+
"source": "copied"
137+
},
138+
"Cargo.toml": {
139+
"source": "generated"
140+
},
141+
"LICENSE": {
142+
"original_path": "/home/LICENSE",
143+
"source": "copied"
144+
},
145+
"main.rs": {
146+
"original_path": "/home/foo/main.rs",
147+
"source": "existing"
148+
},
149+
}
150+
}
151+
.fi
152+
.RE
153+
.RE
112154
.RE
113155
.sp
114156
\fB\-\-no\-verify\fR

0 commit comments

Comments
 (0)