/
doc.go
379 lines (302 loc) · 15 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
// Copyright 2018 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// This file was auto-generated via go generate.
// DO NOT UPDATE MANUALLY
/*
Command vdl manages Vanadium Definition Language source code. It's similar to
the go tool used for managing Go source code.
Usage:
vdl [flags] <command>
The vdl commands are:
generate Compile packages and dependencies, and generate code
compile Compile packages and dependencies, but don't generate code
audit Check if any packages are stale and need generation
list List package and dependency info in transitive order
help Display help for commands or topics
The vdl additional help topics are:
packages Description of package lists
vdlpath Description of VDLPATH environment variable
vdlroot Description of VDLROOT environment variable
vdl.config Description of vdl.config files
The vdl flags are:
-ignore_unknown=false
Ignore unknown packages provided on the command line.
-max-errors=-1
Stop processing after this many errors, or -1 for unlimited.
-v=false
Turn on verbose logging.
-vdl.config=vdl.config
Basename of the optional per-package config file.
The global flags are:
-metadata=<just specify -metadata to activate>
Displays metadata for the program and exits.
-skip-go-methods=false
Skip go generation of VDL{Read,Write,Zero} methods.
-time=false
Dump timing information to stderr before exiting the program.
# Vdl generate - Compile packages and dependencies, and generate code
Generate compiles packages and their transitive dependencies, and generates code
in the specified languages.
Usage:
vdl generate [flags] <packages>
<packages> are a list of packages to process, similar to the standard go tool.
For more information, run "vdl help packages".
The vdl generate flags are:
-go-out-dir=
Go output directory. There are three modes:
"" : Generate output in-place in the source tree
"dir" : Generate output rooted at dir
"src->dst[,s2->d2...]" : Generate output using translation rules
Assume your source tree is organized as follows:
VDLPATH=/home/vdl
/home/vdl/test_base/base1.vdl
/home/vdl/test_base/base2.vdl
Here's example output under the different modes:
--go-out-dir=""
/home/vdl/test_base/base1.vdl.go
/home/vdl/test_base/base2.vdl.go
--go-out-dir="/tmp/foo"
/tmp/foo/test_base/base1.vdl.go
/tmp/foo/test_base/base2.vdl.go
--go-out-dir="vdl->foo/bar"
/home/foo/bar/test_base/base1.vdl.go
/home/foo/bar/test_base/base2.vdl.go
When the src->dst form is used, src must match the suffix of the path just
before the package path, and dst is the replacement for src. Use commas to
separate multiple rules; the first rule matching src is used. The special
dst SKIP indicates matching packages are skipped.
-java-out-dir=release/go/src->release/java/lib/generated-src/vdl,roadmap/go/src->release/java/lib/generated-src/vdl
Same semantics as --go-out-dir but applies to java code generation.
-java-out-pkg=v.io->io/v
Java output package translation rules. Must be of the form:
"src->dst[,s2->d2...]"
If a VDL package has a prefix src, the prefix will be replaced with dst. Use
commas to separate multiple rules; the first rule matching src is used, and
if there are no matching rules, the package remains unchanged. The special
dst SKIP indicates those packages containing the string are skipped. Note
this skip behavior is slightly different than the -out-dir semantics which is
prefix-based.
-js-out-dir=release/go/src->release/javascript/core/src,roadmap/go/src->release/javascript/core/src,third_party/go/src->SKIP,tools/go/src->SKIP,release/go/src/v.io/v23/vdlroot->SKIP
Same semantics as --go-out-dir but applies to js code generation.
-js-relative-path-to-core=
If set, this is the relative path from js-out-dir to the root of the JS core
-lang=Go
Comma-separated list of languages to generate, currently supporting
Go,Java,Javascript,Swift
-show-warnings=true
show warning messages
-status=true
Show package names as they are updated
-swift-out-dir=release/go/src->release/swift/lib/generated-src/vdl,roadmap/go/src->release/swift/lib/generated-src/vdl
Same semantics as --go-out-dir but applies to Swift code generation.
-swift-out-pkg=v.io/x->SKIP,/internal->SKIP,/testdata->SKIP,v.io/v23->
Swift output package translation rules. Must be of the form:
"src->dst[,s2->d2...]"
If a VDL package has a prefix src, the prefix will be replaced with dst. Use
commas to separate multiple rules; the first rule matching src is used, and
if there are no matching rules, the package remains unchanged. The special
dst SKIP indicates those packages containing the string are skipped. Note
this skip behavior is slightly different than the -out-dir semantics which is
prefix-based.
-ignore_unknown=false
Ignore unknown packages provided on the command line.
-max-errors=-1
Stop processing after this many errors, or -1 for unlimited.
-v=false
Turn on verbose logging.
-vdl.config=vdl.config
Basename of the optional per-package config file.
# Vdl compile
Compile compiles packages and their transitive dependencies, but does not
generate code. This is useful to sanity-check that your VDL files are valid.
Usage:
vdl compile [flags] <packages>
<packages> are a list of packages to process, similar to the standard go tool.
For more information, run "vdl help packages".
The vdl compile flags are:
-show-warnings=true
show warning messages
-status=true
Show package names while we compile
-ignore_unknown=false
Ignore unknown packages provided on the command line.
-max-errors=-1
Stop processing after this many errors, or -1 for unlimited.
-v=false
Turn on verbose logging.
-vdl.config=vdl.config
Basename of the optional per-package config file.
# Vdl audit - Check if any packages are stale and need generation
Audit runs the same logic as generate, but doesn't write out generated files.
Returns a 0 exit code if all packages are up-to-date, otherwise returns a non-0
exit code indicating some packages need generation.
Usage:
vdl audit [flags] <packages>
<packages> are a list of packages to process, similar to the standard go tool.
For more information, run "vdl help packages".
The vdl audit flags are:
-go-out-dir=
Go output directory. There are three modes:
"" : Generate output in-place in the source tree
"dir" : Generate output rooted at dir
"src->dst[,s2->d2...]" : Generate output using translation rules
Assume your source tree is organized as follows:
VDLPATH=/home/vdl
/home/vdl/test_base/base1.vdl
/home/vdl/test_base/base2.vdl
Here's example output under the different modes:
--go-out-dir=""
/home/vdl/test_base/base1.vdl.go
/home/vdl/test_base/base2.vdl.go
--go-out-dir="/tmp/foo"
/tmp/foo/test_base/base1.vdl.go
/tmp/foo/test_base/base2.vdl.go
--go-out-dir="vdl->foo/bar"
/home/foo/bar/test_base/base1.vdl.go
/home/foo/bar/test_base/base2.vdl.go
When the src->dst form is used, src must match the suffix of the path just
before the package path, and dst is the replacement for src. Use commas to
separate multiple rules; the first rule matching src is used. The special
dst SKIP indicates matching packages are skipped.
-java-out-dir=release/go/src->release/java/lib/generated-src/vdl,roadmap/go/src->release/java/lib/generated-src/vdl
Same semantics as --go-out-dir but applies to java code generation.
-java-out-pkg=v.io->io/v
Java output package translation rules. Must be of the form:
"src->dst[,s2->d2...]"
If a VDL package has a prefix src, the prefix will be replaced with dst. Use
commas to separate multiple rules; the first rule matching src is used, and
if there are no matching rules, the package remains unchanged. The special
dst SKIP indicates those packages containing the string are skipped. Note
this skip behavior is slightly different than the -out-dir semantics which is
prefix-based.
-js-out-dir=release/go/src->release/javascript/core/src,roadmap/go/src->release/javascript/core/src,third_party/go/src->SKIP,tools/go/src->SKIP,release/go/src/v.io/v23/vdlroot->SKIP
Same semantics as --go-out-dir but applies to js code generation.
-js-relative-path-to-core=
If set, this is the relative path from js-out-dir to the root of the JS core
-lang=Go
Comma-separated list of languages to generate, currently supporting
Go,Java,Javascript,Swift
-show-warnings=true
show warning messages
-status=true
Show package names as they are updated
-swift-out-dir=release/go/src->release/swift/lib/generated-src/vdl,roadmap/go/src->release/swift/lib/generated-src/vdl
Same semantics as --go-out-dir but applies to Swift code generation.
-swift-out-pkg=v.io/x->SKIP,/internal->SKIP,/testdata->SKIP,v.io/v23->
Swift output package translation rules. Must be of the form:
"src->dst[,s2->d2...]"
If a VDL package has a prefix src, the prefix will be replaced with dst. Use
commas to separate multiple rules; the first rule matching src is used, and
if there are no matching rules, the package remains unchanged. The special
dst SKIP indicates those packages containing the string are skipped. Note
this skip behavior is slightly different than the -out-dir semantics which is
prefix-based.
-ignore_unknown=false
Ignore unknown packages provided on the command line.
-max-errors=-1
Stop processing after this many errors, or -1 for unlimited.
-v=false
Turn on verbose logging.
-vdl.config=vdl.config
Basename of the optional per-package config file.
# Vdl list - List package and dependency info in transitive order
List returns information about packages and their transitive dependencies, in
transitive order. This is the same order the generate and compile commands use
for processing. If "vdl list A" is run and A depends on B, which depends on C,
the returned order will be C, B, A. If multiple packages are specified the
ordering is over all combined dependencies.
Reminder: cyclic dependencies between packages are not allowed. Cyclic
dependencies between VDL files within the same package are also not allowed.
This is more strict than regular Go; it makes it easier to generate code for
other languages like C++.
Usage:
vdl list [flags] <packages>
<packages> are a list of packages to process, similar to the standard go tool.
For more information, run "vdl help packages".
The vdl list flags are:
-ignore_unknown=false
Ignore unknown packages provided on the command line.
-max-errors=-1
Stop processing after this many errors, or -1 for unlimited.
-v=false
Turn on verbose logging.
-vdl.config=vdl.config
Basename of the optional per-package config file.
# Vdl help - Display help for commands or topics
Help with no args displays the usage of the parent command.
Help with args displays the usage of the specified sub-command or help topic.
"help ..." recursively displays help for all commands and topics.
Usage:
vdl help [flags] [command/topic ...]
[command/topic ...] optionally identifies a specific sub-command or help topic.
The vdl help flags are:
-style=compact
The formatting style for help output:
compact - Good for compact cmdline output.
full - Good for cmdline output, shows all global flags.
godoc - Good for godoc processing.
shortonly - Only output short description.
Override the default by setting the CMDLINE_STYLE environment variable.
-width=<terminal width>
Format output to this target width in runes, or unlimited if width < 0.
Defaults to the terminal width if available. Override the default by setting
the CMDLINE_WIDTH environment variable.
# Vdl packages - Description of package lists
Most vdl commands apply to a list of packages:
vdl command <packages>
<packages> are a list of packages to process, similar to the standard go tool.
In its simplest form each package is an import path; e.g.
"v.io/x/ref/lib/vdl"
A package that is an absolute path or that begins with a . or .. element is
interpreted as a file system path, and denotes the package in that directory.
A package is a pattern if it includes one or more "..." wildcards, each of which
can match any string, including the empty string and strings containing slashes.
Such a pattern expands to all packages found in VDLPATH with names matching the
pattern. As a special-case, x/... matches x as well as x's subdirectories.
The special-case "all" is a synonym for "...", and denotes all packages found in
VDLPATH.
Import path elements and file names are not allowed to begin with "." or "_";
such paths are ignored in wildcard matches, and return errors if specified
explicitly.
VDLPATH requires *.vdl source files and packages to appear directly under the
VDLPATH directories. Note that when go modules are used VDLPATH should point to
the location of the go.mod file. Also note that whereas GOPATH requires *.go
source files and packages to appear under a "src" directory, VDLPATH requires
*.vdl source files and packages to appear directly under the VDLPATH
directories.
Run "vdl help vdlpath" to see docs on VDLPATH.
Run "go help packages" to see the standard go package docs.
# Vdl vdlpath - Description of VDLPATH environment variable
The VDLPATH environment variable is used to resolve import statements. It must
be set to compile and generate vdl packages.
The format is a colon-separated list of directories containing vdl source code.
These directories are searched recursively for VDL source files. The path below
the directory determines the import path. If VDLPATH specifies multiple
directories, imports are resolved by picking the first directory with a matching
import name.
An example:
VDPATH=/home/user/vdlA:/home/user/vdlB
/home/user/vdlA
foo/ (import "foo" refers here)
foo1.vdl
/home/user/vdlB
foo/ (this package is ignored)
foo2.vdl
bar/
baz/ (import "bar/baz" refers here)
baz.vdl
# Vdl vdlroot - Description of VDLROOT environment variable
The VDLROOT environment variable is similar to VDLPATH, but instead of pointing
to multiple user source directories, it points at a single source directory
containing the standard vdl packages.
If VDLROOT is empty, we use the standard packages built-in to the vdl binary.
VDLROOT is typically left empty, except by vdl tool developers.
# Vdl vdl.config - Description of vdl.config files
Each vdl source package P may contain an optional file "vdl.config" within the P
directory. This file specifies additional configuration for the vdl tool.
The format of this file is described by the vdltool.Config type in the "vdltool"
standard package, located at VDLROOT/vdltool/config.vdl.
If the file does not exist, we use the zero value of vdl.Config.
*/
package main