mirror/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
Code Issues Projects Releases Wiki Activity

v.help: reorganise the folder layout of the v help topic text files (#17155)

Browse Source
This commit is contained in:
Christopher Fore 2023-01-31 05:04:01 -05:00 committed by GitHub
parent d563739264
commit b3d742d13a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
77 changed files with 1104 additions and 830 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
cmd/tools/modules/vhelp/vhelp.v
View File

@ -5,8 +5,35 @@ import os
pub fn show_topic(topic string) {
vexe := os.real_path(os.getenv('VEXE'))
vroot := os.dir(vexe)
target_topic := os.join_path(vroot, 'vlib', 'v', 'help', '${topic}.txt')
content := os.read_file(target_topic) or {
topicdir := os.join_path(vroot, 'vlib', 'v', 'help')
mut path_to := topic
mut topics := os.walk_ext(topicdir, '.txt')
mut items := [][]string{}
// Getting the directory, splitting at `/`, reversing,
// trimming to only indexes 0 and 1, and reversing that into the items array
for mut item in topics {
mut item_rev := item.split('/').reverse()
item_rev.trim(2)
items << item_rev.reverse()
}
// Getting the path to the help topic text file
for cmds in items {
if '${topic}.txt' in cmds {
path_to = '${cmds[0]}/${cmds[1].replace('.txt', '')}'
break
}
}
topic_dir := if topic == 'default' {
os.join_path(topicdir, 'default.txt')
} else {
os.join_path(topicdir, '${path_to}.txt')
}
content := os.read_file(topic_dir) or {
eprintln('Unknown topic: ${topic}')
exit(1)
}

1
cmd/v/v.v
View File

@ -67,6 +67,7 @@ fn main() {
timers.show('v start')
timers.start('parse_CLI_args')
args := os.args[1..]
if args.len == 0 || args[0] in ['-', 'repl'] {
if args.len == 0 {
// Running `./v` without args launches repl

32
vlib/v/help/FORMATTING.md Normal file
View File

@ -0,0 +1,32 @@
# Formatting a Help File
## Requirements
- 2 space initial indentation (titles exempt)
- Description indentation of two spaces from the longest word
- All descriptions should be indented to the same column within a block, with a
hard limit at column 80.
- Multi-line descriptions should indent to match the description part of the previous line
## Example
Adding a help file was made to be easy. All you have to do is create the text file in the
appropriate category, and V should recognize it.
```text
Short description of what it does
Usage:
v COMMAND (args and such here)
Longer description of what your command aims to do (optional)
Examples: (optional)
v COMMAND -arg1 -arg2
Options:
-h, --help Help menu
-s, --short Description of short
-l, --long Description of long
```

20
vlib/v/help/ast.txt
View File

@ -1,20 +0,0 @@
Usage: v ast demo.v generate demo.json file.
or: v ast -w demo.v generate demo.json file, and watch for changes.
or: v ast -c demo.v generate demo.json *and* a demo.c file, and watch for changes.
or: v ast -p demo.v print the json output to stdout.
Description: Dump a JSON representation of the V AST for a given .v or .vsh file.
By default, `v ast` will save the JSON to a .json file, named after the .v file.
Pass -p to see it instead.
The arguments should be at least 1 in number.
Options:
-w, --watch watch a .v file for changes, rewrite the .json file, when a change is detected
-p, --print print the AST to stdout
-c, --compile watch the .v file for changes, rewrite the .json file, *AND* generate a .c file too on any change
-t, --terse terse output, only with tree node names (AST structure), no details
--hide <multiple strings>
hide the specified fields. You can give several, by separating them with `,`
-h, --help display this help and exit
--version output version information and exit

14
vlib/v/help/bin2v.txt
View File

@ -1,14 +0,0 @@
Usage:
v bin2v [options] FILE[...]
Converts a list of arbitrary files into a single v module file.
You can use this tool to embed binary files, like pictures or fonts inside
the executable of a v program, such that it would not need access to external
resources during runtime, and it would be as self-contained as possible.
Options:
-h, --help Show this help screen.
-m, --module <string> Name of the generated module.
-p, --prefix <string> A prefix put before each resource name.
-w, --write <string> Write directly to a file with the given name.

8
vlib/v/help/bug.txt
View File

@ -1,8 +0,0 @@
Usage:
v bug [options] FILE
Open a prefilled bug report on GitHub.
Options:
-v Enable verbosity while gathering various information
-y Force the submission of the issue, even if an error occured

30
vlib/v/help/build-js.txt
View File

@ -1,30 +0,0 @@
Usage: v -b js [-options] ['run'] <target.v|target_directory> [run options]
This command compiles the given target, along with their dependencies, into an Javascript source file.
Note that `js` defaults to the `node` codegen backend but it's also possible to pick another:
* `js_browser` - V outputs JS source code ready for the browser.
* `js_node` - V outputs JS source code to run with nodejs.
* `js_freestanding` - V outputs JS source code with no hard runtime dependency.
For more general build help, see also `v help build`.
# Interfacing the Javascript Backend code generation, passing options to it:
-es5
Compile V to ES5 compatible code possibly shrinking output. Note that this flag might limit some types capabilities.
-prod
Do not create any JS Doc comments
-sourcemap
Create a source map for debugging
-sourcemap-inline
Embed the source map directly into the JavaScript source file
(currently default, external source map files not implemented)
-sourcemap-src-include
Include the orginal V source files into the generated source map
(default false, all files in the source map are currently referenced by their absolute system file path)
The supported targets for the JS backend are: ES6 strict

17
vlib/v/help/build-native.txt
View File

@ -1,17 +0,0 @@
Usage: v -native [-options] ['run'] <target.v|target_directory> [run options]
This command compiles the given target, along with their dependencies, into an executable using the Native code generation backend.
For more general build help, see also `v help build`.
# Interfacing the Native code generation, passing options to it:
-v
Display the assembly code generated (that may change to `-showasm` in the future)
-arch <arch>
Select target architecture, right now only `arm64` and `amd64` are supported
-os <os>, -target-os <os>
Change the target OS that V compiles for.
The supported targets for the native backend are: `macos`, `linux` and 'windows'

213
vlib/v/help/build.txt
View File

@ -1,213 +0,0 @@
Usage: v [build flags] ['run'] <target.v|target_directory> [run options]
This command compiles the given target, along with their dependencies, into an executable.
Note that these build flags also work with `run` too, but you need to
pass them *before* `run` . The argument directly after `run` is assumed
to be a .v source file or folder containing .v source files.
Everything after that, is assumed to be flags, that V will ignore itself,
but will pass to the executable after it is compiled.
This enables you to do for example: `v -cc gcc -g myfile.v run -param1 abcde`
... which means for V: "compile using gcc, produce debugging information,
then run `./myfile -param1 abcde` and exit with its exit code".
When compiling packages, V ignores files that end in '_test.v'.
When compiling a single main package, V writes the resulting executable to an output file
named after the build target. ('v abc.v' and 'v abc/' both write either 'abc' or 'abc.exe')
The '.exe' suffix is added automatically, when writing a Windows executable.
By default, the executable is stored in the same directory as the compiled source code.
The -o flag forces V to write the resulting executable or object to the d output file or directory,
instead of the default behavior described in the last two paragraphs.
You can put common options inside an environment variable named VFLAGS, so that
you don't have to repeat them.
You can set it like this: `export VFLAGS="-cc clang -g"` on *nix,
`set VFLAGS=-cc msvc` on Windows.
V respects the TMPDIR environment variable, and will put .tmp.c files in TMPDIR/v/ .
If you have not set it, a suitable platform specific folder (like /tmp) will be used.
NB: the build flags are shared with the run command too:
-b <backend>, -backend <backend>
Specifies the backend that will be used for building the executable.
Current list of supported backends:
* `c` (default) - V outputs C source code, which is then passed to a C compiler.
* `go` - V outputs Go source code, which is then passed to a Go compiler.
* `interpret` - V will interpret the V program directly, instead of compiling it first. Same as `v interpret file.v`.
* `js` - V outputs JS source code which can be passed to NodeJS to be ran.
* `js_browser` - V outputs JS source code ready for the browser.
* `js_node` - V outputs JS source code to run with nodejs.
* `js_freestanding` - V outputs JS source code with no hard runtime dependency.
* `native` - V outputs a native executable directly (see -arch x64|arm64 and -os linux|macos) (EXPERIMENTAL).
-d <flag>[=<value>], -define <flag>[=<value>]
Define the provided flag.
If value is not provided, it is assumed to be set to `true`.
`value` should be `1` or `0` to indicate `true` and `false` respectively otherwise.
-g
Compile the executable in debug mode, allowing code to be debugged more easily.
-o <output>, -output <output>
Force V to output the executable in a specific location
(relative to the current working directory if not absolute).
-obf, -obfuscate
Turn on obfuscation for the code being built. Currently only renames symbols.
-path
Specify the order of path V looks up in while searching for imported dependencies,
separated by pipes (`|`). In addition to absolute paths, you can
also use these special strings too:
@vmodules - replaced with the location of the global ~/.vmodules/ folder
(modules installed with `v install` are there). You can change
its location by setting the environment variable VMODULES.
@vlib - replaced with the location of the v's vlib folder.
Using these, you can arrange for very flexible search orders for you project, for example:
-path "/v/my_project_private_modules|@vlib|@vmodules"
By default, -path is just "@vlib|@vmodules" .
-prod
Compile the executable in production mode, where most optimizations are enabled.
Note that most V warnings turn to errors, if you pass -prod, so you will have
to fix them first.
-no-bounds-checking
Programs compiled with this option, will do no runtime checking of array access operations.
Note that the performance impact of the bounds checking is usually below 3%, so in most
cases, it is preferable to not turn it off, than disable it, and have a program that may
do out of bounds accesses.
-prof, -profile <file.txt>
Compile the executable with all functions profiled.
The profile results will be stored in `file.txt`.
The format is 4 fields, separated by a space, for each v function:
a) how many times it was called
b) how much *nanoseconds in total* it took
c) an average for each function (i.e. (b) / (a) )
d) the function name
NB: you can also combine this command with `run` command.
For example - `v -prof prof.txt run main.v`
NB: the profiler is *NOT* currently thread safe, so look at the profile results of
multithreaded programs very sceptically !
NB: if you want to output the profile info to stdout, use `-profile -`.
NB: you can use `import v.profile`, and then calls to `profile.on(false)`
and `profile.on(true)` to temporarily turn it off and on again.
NB: if you do NOT want the profile to contain information from before your
program's `fn main()` starts, pass `-d no_profile_startup` too.
(V constants, and module init() functions are evaluated before `main()` is called)
NB: You can also select specific functions for profiling. For example:
v -profile-fns println,i64_str -profile - run examples/hanoi.v
In this case, the profile counters will be updated only for them, *and* for the functions that they call.
The profile result (after the program finishes), will look similar to this:
127 0.721ms 5680ns println
127 0.693ms 5456ns _writeln_to_fd
127 0.565ms 4449ns _write_buf_to_fd
127 0.045ms 353ns _v_malloc
127 0.017ms 131ns malloc_noscan
127 0.017ms 133ns _v_free
127 0.014ms 113ns vmemmove
127 0.110ms 866ns i64_str
127 0.016ms 127ns tos
-message-limit <limit>
The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 100).
The checker will abort prematurely once this limit has been reached.
Setting this to 0 or a negative value, will disable the limit.
-no-parallel
Do not run the compiler in parallel (currently only the cgen stage has parallelization).
-profile-no-inline
Skip [inline] functions when profiling.
-skip-unused
Skip generating C/JS code for functions, that are provably not used by your project.
This speeds up compilation, and reduces the generated output size.
It is still experimental, due to historical reasons, but please do try it,
and report issues, if compilation breaks with that option for your program.
-stats
Enable more detailed statistics reporting, while compiling test files.
You can use that with `v test` too, for example:
v -stats test vlib/
... will run test_ functions inside all _test.v files inside vlib/ ,
and will report detailed statistics about how much time each test_ function took, how many
assertions were made, how many tests passed/failed and so on.
-translated
Enable features that are discouraged in regular V code but required for translated V code.
-v
Enable verbosity in the V compiler while compiling
-print-v-files
Just print the list of all parsed .v files, then stop processing further.
This is useful for running external processing tools:
./v -print-v-files cmd/v | etags -L -
... will generate a TAGS file, that emacs can then use to jump
to the definition of functions used by v itself. For vim:
./v -print-v-files cmd/v | ctags -L -
... will generate a simillar tags file, that vi compatible editors can use.
NB: an useful, although not entirely accurate regexp based Universal Ctags options file
for V is located in `.ctags.d/v.ctags` . If you use https://ctags.io/ , it will be used
up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags .
-color, -nocolor
Force the use of ANSI colors for the V error/warning messages, or disable them completely.
By default, the V compiler tries to show its errors/warnings in ANSI color. The heuristic
that it uses to detect whether or not to use ANSI colors may not work in all cases.
These options allow you to override the default detection.
-check
Scans, parses, and checks the files without compiling the program.
-check-syntax
Only scan and parse the files, but then stop. Useful for very quick syntax checks.
-show-timings
Print a summary about how long each compiler stage took, for example:
PARSE: 152ms
CHECK: 62ms
C GEN: 103ms
C tcc: 95ms
Related to -show-timings, is the ability to compile a special instrumented
v compiler with this command:
`v -d time_parsing -d time_checking -d time_cgening -d time_v self`
The instrumented version will print detailed timing stats while processing
each .v file.
-w
Hide all warnings.
-W
Treat *all V warnings* as errors, even in development builds.
-Wfatal-errors
Unconditionally exit with exit(1) after the first error.
Useful for scripts/tooling that calls V.
-Wimpure-v
Warn about using C. or JS. symbols in plain .v files.
These should be moved in .c.v and .js.v .
NB: in the future, this will be turned ON by default,
and will become an error, after vlib modules are cleaned up.
For C-specific build flags, use `v help build-c`.
For JS-specific build flags, use `v help build-js`.
For Native-specific build flags, use `v help build-native`.
See also:
`v help run` for documentation regarding `v run`.

5
vlib/v/help/build-c.txt → vlib/v/help/build/build-c.txt
View File

@ -1,7 +1,8 @@
Usage: v [C build flags] ['run'] <target.v|target_directory> [run options]
This command compiles the given target, along with their dependencies, into an executable.
Usage:
v [build flags] ['run'] <target.v|target_directory> [run options]
This help topic explores the C-backend specific build flags. For more general build help,
see also `v help build`.

35
vlib/v/help/build/build-js.txt Normal file
View File

@ -0,0 +1,35 @@
This command compiles the given target, along with their dependencies,
into a Javascript source file.
Usage:
v -b js [-options] ['run'] <target.v|target_directory> [run options]
Note that `js` defaults to the `node` codegen backend but it's also possible to
pick another:
* `js_browser` - V outputs JS source code ready for the browser.
* `js_node` - V outputs JS source code to run with nodejs.
* `js_freestanding` - V outputs JS source code with no hard runtime dependency.
For more general build help, see also `v help build`.
# Interfacing the Javascript Backend code generation, passing options to it:
-es5 Compile V to ES5 compatible code possibly shrinking output. Note that this flag might limit some types capabilities.
-prod
Do not create any JS Doc comments
-sourcemap
Create a source map for debugging
-sourcemap-inline Embed the source map directly into the
JavaScript source file
(currently default,
external source map files not implemented)
-sourcemap-src-include Include the orginal V source files into the
generated source map
(default false, all files in the source map are currently referenced by
their absolute system file path)
The supported targets for the JS backend are: ES6 strict

20
vlib/v/help/build/build-native.txt Normal file
View File

@ -0,0 +1,20 @@
This command compiles the given target, along with their dependencies,
into an executable using the Native code generation backend.
Usage:
v -native [-options] ['run'] <target.v|target_directory> [run options]
For more general build help, see also `v help build`.
# Interfacing the Native code generation, passing options to it:
-v Display the assembly code generated
(that may change to `-showasm` in the future)
-arch <arch> Select target architecture
Only `arm64` and `amd64` are supported
-os <os>, -target-os <os> Change the target OS that V compiles for.
The supported targets for the native backend are: `macos`, `linux` and 'windows'

214
vlib/v/help/build/build.txt Normal file
View File

@ -0,0 +1,214 @@
The build system for V
Usage:
v [build flags] ['run'] <target.v|target_directory> [run options]
Note that these build flags also work with `run` too, but you need to
pass them *before* `run` . The argument directly after `run` is assumed
to be a .v source file or folder containing .v source files.
Everything after that, is assumed to be flags, that V will ignore itself,
but will pass to the executable after it is compiled.
This enables you to do for example: `v -cc gcc -g myfile.v run -param1 abcde`
... which means for V: "compile using gcc, produce debugging information,
then run `./myfile -param1 abcde` and exit with its exit code".
When compiling packages, V ignores files that end in '_test.v'.
When compiling a single main package, V writes the resulting executable to an output file
named after the build target. ('v abc.v' and 'v abc/' both write either 'abc' or 'abc.exe')
The '.exe' suffix is added automatically, when writing a Windows executable.
By default, the executable is stored in the same directory as the compiled source code.
The -o flag forces V to write the resulting executable or object to the d output file or directory,
instead of the default behavior described in the last two paragraphs.
You can put common options inside an environment variable named VFLAGS, so that
you don't have to repeat them.
You can set it like this: `export VFLAGS="-cc clang -g"` on *nix,
`set VFLAGS=-cc msvc` on Windows.
V respects the TMPDIR environment variable, and will put .tmp.c files in TMPDIR/v/ .
If you have not set it, a suitable platform specific folder (like /tmp) will be used.
NB: the build flags are shared with the run command too:
-b <backend>, -backend <backend>
Specifies the backend that will be used for building the executable.
Current list of supported backends:
* `c` (default) - V outputs C source code, which is then passed to a C compiler.
* `go` - V outputs Go source code, which is then passed to a Go compiler.
* `interpret` - V will interpret the V program directly, instead of compiling it first. Same as `v interpret file.v`.
* `js` - V outputs JS source code which can be passed to NodeJS to be ran.
* `js_browser` - V outputs JS source code ready for the browser.
* `js_node` - V outputs JS source code to run with nodejs.
* `js_freestanding` - V outputs JS source code with no hard runtime dependency.
* `native` - V outputs a native executable directly (see -arch x64|arm64 and -os linux|macos) (EXPERIMENTAL).
-d <flag>[=<value>], -define <flag>[=<value>]
Define the provided flag.
If value is not provided, it is assumed to be set to `true`.
`value` should be `1` or `0` to indicate `true` and `false` respectively otherwise.
-g
Compile the executable in debug mode, allowing code to be debugged more easily.
-o <output>, -output <output>
Force V to output the executable in a specific location
(relative to the current working directory if not absolute).
-obf, -obfuscate
Turn on obfuscation for the code being built. Currently only renames symbols.
-path
Specify the order of path V looks up in while searching for imported dependencies,
separated by pipes (`|`). In addition to absolute paths, you can
also use these special strings too:
@vmodules - replaced with the location of the global ~/.vmodules/ folder
(modules installed with `v install` are there). You can change
its location by setting the environment variable VMODULES.
@vlib - replaced with the location of the v's vlib folder.
Using these, you can arrange for very flexible search orders for you project, for example:
-path "/v/my_project_private_modules|@vlib|@vmodules"
By default, -path is just "@vlib|@vmodules" .
-prod
Compile the executable in production mode, where most optimizations are enabled.
Note that most V warnings turn to errors, if you pass -prod, so you will have
to fix them first.
-no-bounds-checking
Programs compiled with this option, will do no runtime checking of array access operations.
Note that the performance impact of the bounds checking is usually below 3%, so in most
cases, it is preferable to not turn it off, than disable it, and have a program that may
do out of bounds accesses.
-prof, -profile <file.txt>
Compile the executable with all functions profiled.
The profile results will be stored in `file.txt`.
The format is 4 fields, separated by a space, for each v function:
a) how many times it was called
b) how much *nanoseconds in total* it took
c) an average for each function (i.e. (b) / (a) )
d) the function name
NB: you can also combine this command with `run` command.
For example - `v -prof prof.txt run main.v`
NB: the profiler is *NOT* currently thread safe, so look at the profile results of
multithreaded programs very sceptically !
NB: if you want to output the profile info to stdout, use `-profile -`.
NB: you can use `import v.profile`, and then calls to `profile.on(false)`
and `profile.on(true)` to temporarily turn it off and on again.
NB: if you do NOT want the profile to contain information from before your
program's `fn main()` starts, pass `-d no_profile_startup` too.
(V constants, and module init() functions are evaluated before `main()` is called)
NB: You can also select specific functions for profiling. For example:
v -profile-fns println,i64_str -profile - run examples/hanoi.v
In this case, the profile counters will be updated only for them, *and* for the functions that they call.
The profile result (after the program finishes), will look similar to this:
127 0.721ms 5680ns println
127 0.693ms 5456ns _writeln_to_fd
127 0.565ms 4449ns _write_buf_to_fd
127 0.045ms 353ns _v_malloc
127 0.017ms 131ns malloc_noscan
127 0.017ms 133ns _v_free
127 0.014ms 113ns vmemmove
127 0.110ms 866ns i64_str
127 0.016ms 127ns tos
-message-limit <limit>
The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 100).
The checker will abort prematurely once this limit has been reached.
Setting this to 0 or a negative value, will disable the limit.
-no-parallel
Do not run the compiler in parallel (currently only the cgen stage has parallelization).
-profile-no-inline
Skip [inline] functions when profiling.
-skip-unused
Skip generating C/JS code for functions, that are provably not used by your project.
This speeds up compilation, and reduces the generated output size.
It is still experimental, due to historical reasons, but please do try it,
and report issues, if compilation breaks with that option for your program.
-stats
Enable more detailed statistics reporting, while compiling test files.
You can use that with `v test` too, for example:
v -stats test vlib/
... will run test_ functions inside all _test.v files inside vlib/ ,
and will report detailed statistics about how much time each test_ function took, how many
assertions were made, how many tests passed/failed and so on.
-translated
Enable features that are discouraged in regular V code but required for translated V code.
-v
Enable verbosity in the V compiler while compiling
-print-v-files
Just print the list of all parsed .v files, then stop processing further.
This is useful for running external processing tools:
./v -print-v-files cmd/v | etags -L -
... will generate a TAGS file, that emacs can then use to jump
to the definition of functions used by v itself. For vim:
./v -print-v-files cmd/v | ctags -L -
... will generate a simillar tags file, that vi compatible editors can use.
NB: an useful, although not entirely accurate regexp based Universal Ctags options file
for V is located in `.ctags.d/v.ctags` . If you use https://ctags.io/ , it will be used
up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags .
-color, -nocolor
Force the use of ANSI colors for the V error/warning messages, or disable them completely.
By default, the V compiler tries to show its errors/warnings in ANSI color. The heuristic
that it uses to detect whether or not to use ANSI colors may not work in all cases.
These options allow you to override the default detection.
-check
Scans, parses, and checks the files without compiling the program.
-check-syntax
Only scan and parse the files, but then stop. Useful for very quick syntax checks.
-show-timings
Print a summary about how long each compiler stage took, for example:
PARSE: 152ms
CHECK: 62ms
C GEN: 103ms
C tcc: 95ms
Related to -show-timings, is the ability to compile a special instrumented
v compiler with this command:
`v -d time_parsing -d time_checking -d time_cgening -d time_v self`
The instrumented version will print detailed timing stats while processing
each .v file.
-w
Hide all warnings.
-W
Treat *all V warnings* as errors, even in development builds.
-Wfatal-errors
Unconditionally exit with exit(1) after the first error.
Useful for scripts/tooling that calls V.
-Wimpure-v
Warn about using C. or JS. symbols in plain .v files.
These should be moved in .c.v and .js.v .
NB: in the future, this will be turned ON by default,
and will become an error, after vlib modules are cleaned up.
For C-specific build flags, use `v help build-c`.
For JS-specific build flags, use `v help build-js`.
For Native-specific build flags, use `v help build-native`.
See also:
`v help run` for documentation regarding `v run`.

28
vlib/v/help/bump.txt
View File

@ -1,28 +0,0 @@
Usage: v bump [options] [file1 file2 ...]
Description:
Bump the semantic version of the v.mod and/or specified files.
The first instance of a version number is replaced with the new version.
Additionally, the line affected must contain the word "version" in any
form of capitalization. For instance, the following lines will be
recognized by the heuristic:
tool_version = '1.2.1'
version: '0.2.42'
VERSION = "1.23.8"
Examples:
Bump the patch version in v.mod if it exists
v bump --patch
Bump the major version in v.mod and vls.v
v bump --major v.mod vls.v
Upgrade the minor version in sample.v only
v bump --minor sample.v
Options:
-h, --help Show this help text.
-m, --major Bump the major version.
-n, --minor Bump the minor version.
-p, --patch Bump the patch version.

24
vlib/v/help/check-md.txt
View File

@ -1,24 +0,0 @@
check-md is a tool to check the passed markdown files for correct ```v ``` code blocks
and other style violations like too long lines/links etc...
Usage:
a) `v check-md [flags] <...files>` - Check the given .md files.
b) `v check-md [flags] <...dirs>` - Check *all* files in the given directories.
Note: You can also combine files and directories.
Flags:
-silent Do not show a progress bar.
-w, -hide-warnings Do not print warnings, only errors.
NB: There are several special keywords, which you can put after the code fences for v.
These are:
compile - Default, can be omitted. The example will be compiled and formatting is verified.
cgen - The example produces C code, which may not be compilable (when external libs are not installed). Formatting is verified.
live - Compile hot reload examples with the ´-live´ flag set and verify formatting.
ignore - Ignore the example, useful for examples that just use the syntax highlighting
failcompile - Known failing compilation. Useful for examples demonstrating compiler errors.
okfmt - Should only be formatted, but it can refer to invalid modules, missing functions etc. Useful for partial examples.
oksyntax - Should parse, and be formatted, but may not compile. Useful for partial examples.
badsyntax - Known bad syntax, it should NOT even parse.
wip - Like ignore; a planned feature; easy to search.
nofmt - Disable fmt verification for individual code blocks.

24
vlib/v/help/common/common.txt Normal file
View File

@ -0,0 +1,24 @@
Commonly Used Commands:
doc Generates the documentation of a given MODULE, DIRECTORY, or FILE
and prints or saves them to its desired format. It can generate HTML, JSON,
or Markdown format.
fmt Formats the given V source files or recursively formats all files in the directory,
then prints their formatted source to stdout.
missdoc Prints all V functions in .v files under PATH/, that do not yet have documentation comments.
repl Run the V REPL
run Equivalent to running `v build` and running the compiled executable
test Runs tests in the given FILEs and DIRECTORYs
vet Reports suspicious code constructs
watch Collects all .v files needed for complication,
then when any of the .v source files change,
it re-runs the complication
where Prints the location of the searched symbols in the scope of the current project

15
vlib/v/help/doc.txt → vlib/v/help/common/doc.txt
View File

@ -1,3 +1,5 @@
Generates the documentation of a given MODULE, DIRECTORY, or FILE
Usage:
v doc [options] [MODULE / DIRECTORY / FILE] [symbol name]
@ -14,13 +16,15 @@ Examples:
Options:
-all Includes private and public functions/methods/structs/consts/enums.
-f Specifies the output format to be used. Available formats are:
-f Specifies the output format to be used.
Available formats are:
md/markdown, json, text, stdout and html/htm
-h, -help Prints this help text.
-m Generate docs for modules listed in that folder.
-o Specifies the output file/folder path where to store the generated docs.
Set it to "stdout" to print the output instead of saving the contents
to a file.
-o Specifies the output file/folder path where to store the
generated docs.
Set it to "stdout" to print the output instead of saving
the contents to a file.
-color Forces stdout colorize output.
-no-color Forces plain text output, without ANSI colors.
-readme Include README.md to docs if present.
@ -28,7 +32,8 @@ Options:
-no-timestamp Omits the timestamp in the output file.
For HTML mode:
-inline-assets Embeds the contents of the CSS and JS assets into the webpage directly.
-inline-assets Embeds the contents of the CSS and JS assets into the
webpage directly.
-theme-dir The directory for doc theme template
For plain text mode:

43
vlib/v/help/common/fmt.txt Normal file
View File

@ -0,0 +1,43 @@
Read source code from stdin, output formatted file to stdout.
Usage:
v fmt [options] path_to_source.v [path_to_other_source.v]
v fmt [options] path/to/dir [path/to/other_dir]
cat source.v | v fmt
Formats the given V source files or recursively formats all files in the
directory, then prints their formatted source to stdout.
Options:
-c Check if a file is already formatted. If not, print the
filepath and exit with code 2. Compared to -verify it is
quicker but has a small trade-off in precision.
-diff Display the differences between the formatted source(s)
and the original source(s). This will attempt to find a
working `diff` command automatically unless you specify one
with the VDIFF_TOOL environment variable.
-l List files whose formatting differs from vfmt.
-w Write result to (source) file(s) instead of to stdout.
-backup In combination with `-w`, copy the original `file.v` to a
`file.v.bak` backup, before overwriting the original source
file.
-debug Print the kinds of encountered AST statements/expressions
on stderr.
-verify Make sure the provided file is already formatted. Useful for
checking code contributions in CI for example.
Environment Variables:
VDIFF_TOOL A command-line tool that will be executed with the original
file path and a temporary formatted file path as arguments.
e.g. `VDIFF_TOOL=opendiff v fmt -diff path/to/file.v` will
become: opendiff path/to/file.v /tmp/v/vfmt_file.v
VDIFF_OPTIONS A set of command-line options to be sent immediately after
the `diff` command. e.g. VDIFF_OPTIONS="-W 80 -y"
v fmt -diff path/to/file.v /tmp/v/vfmt_file.v

36
vlib/v/help/common/missdoc.txt Normal file
View File

@ -0,0 +1,36 @@
Prints all V functions in .v files under PATH/, that do not yet have
documentation comments.
Usage: v missdoc [options] PATH [PATH]...
Options:
-h, --help Show this help text.
-t, --tags Also print function tags if any is found.
-d, --deprecated Include deprecated functions in output.
-p, --private Include private functions in output.
--js Include JavaScript functions in output.
-n, --no-line-numbers Exclude line numbers in output.
-e, --exclude <multiple strings>
-r, --relative-paths Use relative paths in output.
--verify exit(1) if documentation is missing, 0 otherwise.
--diff exit(1) and show difference between two PATH inputs,
return 0 otherwise.
--version output version information and exit
PATH can be both files and directories.
The `--verify` flag is useful for use in CI setups for checking if a V project
has all it's functions and methods documented:
```
v missdoc --verify path/to/code
```
The `--diff` flag is useful if your project is not yet fully documented
but you want to ensure that no new functions or methods are introduced
between commits or branches:
```
v missdoc --diff current/code new/code
```

5
vlib/v/help/repl.txt → vlib/v/help/common/repl.txt
View File

@ -1,3 +1,4 @@
Usage: v repl
This command runs the V REPL.
Usage:
v repl

11
vlib/v/help/run.txt → vlib/v/help/common/run.txt
View File

@ -1,10 +1,15 @@
Usage: v [build flags] run <file.v|directory|-> [arguments...]
Equivalent to running `v build` and running the compiled executable.
This command is equivalent to running `v build` and running the compiled executable.
Usage:
v [build flags] run <file.v|directory|-> [arguments...]
This command is equivalent to running `v build` and running the compiled
executable.
The executable is passed the arguments as provided in [arguments...].
If the target is '-', it means that the V source code to build comes from stdin.
If the '-o' option is not specified, and the target is '-', a temporary base name for the executable will be used.
If the '-o' option is not specified, and the target is '-', a temporary base
name for the executable will be used.
The exit status of run will be:
* `1` if the compilation failed.

32
vlib/v/help/test.txt → vlib/v/help/common/test.txt
View File

@ -1,20 +1,21 @@
Runs test functions in the given FILEs and DIRECTORYs.
Usage:
v [-stats] test FILE|DIRECTORY[...] [-run-only GPATTERN1[,...]]
Runs test functions in the given FILEs and DIRECTORYs.
If '-stats' is given, more statistics about the tests are printed along
with a report of passes/failures
If '-stats' is given, more statistics about the tests are printed along
with a report of passes/failures
If you give `-run-only GPATTERN`, then *only* test functions, that do
match by name the given glob pattern `GPATTERN` will run. You can separate
multiple glob patterns with `,`.
If a _test.v file lacks matching functions for all of the glob patterns, it
will be ignored completely, so you can do in effect:
`v test . -run-only test_your_fn_name`
... and V will run only that test function, no matter how many _test.v
files you have, and how many other test_ functions exist in them.
NB: glob patterns support `*` which matches anything, and `?`, that
matches any single character. They are *NOT* regular expressions however.
If you give `-run-only GPATTERN`, then *only* test functions, that do
match by name the given glob pattern `GPATTERN` will run. You can separate
multiple glob patterns with `,`.
If a _test.v file lacks matching functions for all of the glob patterns, it
will be ignored completely, so you can do in effect:
`v test . -run-only test_your_fn_name`
... and V will run only that test function, no matter how many _test.v
files you have, and how many other test_ functions exist in them.
NB: glob patterns support `*` which matches anything, and `?`, that
matches any single character. They are *NOT* regular expressions however.
NB 1: very frequently, when you work on a module you can cd into its folder,
and then you can perform:
@ -58,6 +59,7 @@ should see something like this:
```
OK [1/2] 164.671 ms vlib/math/stats/stats_test.v
OK [2/2] 184.842 ms vlib/math/complex/complex_test.v
------------------------------------------------------------------------------------------
Summary for all V _test.v files: 2 passed, 2 total. Runtime: 185 ms, on 2 parallel jobs.
--------------------------------------------------------------------------------
Summary for all V _test.v files: 2 passed, 2 total. Runtime: 185 ms, on 2
parallel jobs.
```

19
vlib/v/help/common/vet.txt Normal file
View File

@ -0,0 +1,19 @@
Reports suspicious code constructs.
Usage:
v vet [options] path_to_source.v [path_to_other_source.v]
v vet [options] path/to/dir [path/to/other_dir]
Options:
-W Exit with code 1, even if vet only reported warnings.
Useful for checks in CI.
-w, -hide-warnings Do not print warnings to stderr.
-v, -verbose Enable verbose logging.
-p Report private functions with missing documentation too
(by default, only the `pub fn` functions will be reported).
-force (NB: vet development only!)
Do not skip the vet regression tests.

34
vlib/v/help/common/watch.txt Normal file
View File

@ -0,0 +1,34 @@
`v watch` collects all .v files needed for a compilation
Usage:
v watch [--clear] [--ignore .db] [--add /path/to/a/file.v] [other V options] [run] program.v
`v watch` collects all .v files needed for a compilation, then when
any of the .v source files change, it re-runs the compilation.
Options:
-s, --silent Be more silent; do not print the watch timestamp
before each re-run.
-c, --clear Clears the terminal before each re-run.
-a, --add <string> Add more files to be watched.
Useful with `v watch -add=feature.v run cmd/v feature.v`,
when you want to change *both* the V compiler,
and the `feature.v` file.
-i, --ignore <string> Ignore files having these extensions.
Useful with `v watch -ignore=.db run vwebserver.v`,
if your `vwebserver` writes to an sqlite.db file in
the same folder.
--before <string> A command to execute *before* each re-run.
Example: --before 'v wipe-cache'
--after <string> A command to execute *after* each re-run.
Example: --after 'rm -rf /tmp/v/'
You can also customise the timeout, after `v watch` will re-start a monitored
program automatically, even if it was not changed by setting the enviroment
variable VWATCH_TIMEOUT (in seconds). By default, it is 5 min. (300 seconds).

41
vlib/v/help/common/where.txt Normal file
View File

@ -0,0 +1,41 @@
Prints the location of the searched symbols in the scope of the current project.
Usage:
v where symbol_type symbol_name [params]
Examples:
v where fn main
v where struct User
v where method Square.area
v where fn pow -mod math
v where interface callable -dir some -dir other
symbol_name can be:
fn by default if omit symbol_type (don't omit preferably)
method require Struct.method notation
struct
interface
enum
const
var
regexp
Options:
-mod [mod_name] Restrict to search recursively only within of the given
module, if not provided search in entire v scope
(use -mod main to search inside all your project).
-dir [dir_path] Restrict to search non recursively within the given
folder/s, if not provided, search in entire v scope.
-vis [visibility] Can be: all, pub, pri (all by default if not provided).
Restrict to search symbols with the given visibility.
-mut [mutability] Can be: any, yes, not (any by default if not provided).
Restrict to search symbols with the given mutability.
flags:
-h include Header
-f Format output (each match uses 3 lines)
-v for both above (more Verbose)
Note:
This tool is inspired by the vdoc tool and its design. However, this is
for a more specific use, and can be improved.

28
vlib/v/help/complete.txt
View File

@ -1,28 +0,0 @@
Usage:
v complete [options] [SUBCMD] QUERY...
Description:
Tool for bridging auto completion between various shells and v
Supported shells:
bash, fish, zsh, powershell
Examples:
Echo auto-detected shell install script to STDOUT
v complete
Echo specific shell install script to STDOUT
v complete setup bash
Auto complete input `v tes`*USER PUSHES TAB* (in Bash compatible format).
This is not meant for manual invocation - it's called by the relevant
shell via the script installed with `v complete` or `v complete setup SHELL`.
v complete bash v tes
Options:
-h, --help Show this help text.
SUBCMD:
setup : setup [SHELL] - returns the code for completion setup for SHELL
bash : [QUERY] - returns Bash compatible completion code with completions computed from QUERY
fish : [QUERY] - returns Fish compatible completion code with completions computed from QUERY
zsh : [QUERY] - returns ZSH compatible completion code with completions computed from QUERY
powershell: [QUERY] - returns PowerShell compatible completion code with completions computed from QUERY

113
vlib/v/help/default.txt
View File

@ -1,65 +1,80 @@
V is a tool for managing V source code.
Usage:
v [options] [command] [arguments]
v [options] [command] [arguments]
Examples:
v hello.v Compile the file `hello.v` and output it as `hello` or `hello.exe`.
v run hello.v Same as above but also run the produced executable immediately after compilation.
v -cg run hello.v Same as above, but make debugging easier (in case your program crashes).
v crun hello.v Same as above, but do not recompile, if the executable already exists, and is newer than the sources.
v -o h.c hello.v Translate `hello.v` to `h.c`. Do not compile further.
v -o - hello.v Translate `hello.v` and output the C source code to stdout. Do not compile further.
v watch hello.v Re-does the same compilation, when a source code change is detected.
The program is only compiled, not run.
v watch run hello.v Re-runs the same `hello.v` file, when a source code change is detected.
v hello.v Compile the file `hello.v` and output it as
`hello` or `hello.exe`.
v run hello.v Same as above but also run the produced
executable immediately after compilation.
v -cg run hello.v Same as above, but make debugging easier
(in case your program crashes).
v crun hello.v Same as above, but do not recompile, if the
executable already exists, and is newer than the
sources.
v -o h.c hello.v Translate `hello.v` to `h.c`. Do not compile
further.
v -o - hello.v Translate `hello.v` and output the C source code
to stdout. Do not compile further.
v watch hello.v Re-does the same compilation, when a source code
change is detected.
The program is only compiled, not run.
v watch run hello.v Re-runs the same `hello.v` file, when a source
code change is detected.
V supports the following commands:
* New project scaffolding:
new Setup the file structure for a V project (in a sub folder).
init Setup the file structure for an already existing V project.
* Ordinary development:
run Compile and run a V program. Delete the executable after the run.
crun Compile and run a V program without deleting the executable.
If you run the same program a second time, without changing the source files,
V will just run the executable, without recompilation. Suitable for scripting.
test Run all test files in the provided directory.
fmt Format the V code provided.
vet Report suspicious code constructs.
doc Generate the documentation for a V module.
vlib-docs Generate and open the documentation of all the vlib modules.
repl Run the REPL.
watch Re-compile/re-run a source file, each time it is changed.
where Find and print the location of current project declarations.
* Project Scaffolding Utilities:
new Setup the file structure for a V project
(in a sub folder).
init Setup the file structure for an already existing
V project.
* Installation/self updating:
symlink Create a symbolic link for V.
up Run the V self-updater.
self [-prod] Run the V self-compiler, use -prod to optimize compilation.
version Print the version text and exits.
* Commonly Used Utilities:
run Compile and run a V program. Delete the
executable after the run.
crun Compile and run a V program without deleting the
executable.
If you run the same program a second time,
without changing the source files,
V will just run the executable, without
recompilation. Suitable for scripting.
test Run all test files in the provided directory.
fmt Format the V code provided.
vet Report suspicious code constructs.
doc Generate the documentation for a V module.
vlib-docs Generate and open the documentation of all the
vlib modules.
repl Run the REPL.
watch Re-compile/re-run a source file, each time it is
changed.
where Find and print the location of current project
declarations.
* Module/package management:
install Install a module from VPM.
remove Remove a module that was installed from VPM.
search Search for a module from VPM.
update Update an installed module from VPM.
upgrade Upgrade all the outdated modules.
list List all installed modules.
outdated List installed modules that need updates.
show Display information about a module on vpm
* Installation Management Utilities:
symlink Create a symbolic link for V.
up Run the V self-updater.
self [-prod] Run the V self-compiler, use -prod to optimize
compilation.
version Print the version text and exits.
* Others:
doctor Display some useful info about your system to help reporting bugs.
translate Translate C code to V.
tracev Produce a tracing version of the v compiler.
Use `tracev yourfile.v` when the compiler panics.
NB: `tracev` is much slower and more verbose than ordinary `v`
* Package Management Utilities:
install Install a module from VPM.
remove Remove a module that was installed from VPM.
search Search for a module from VPM.
update Update an installed module from VPM.
upgrade Upgrade all the outdated modules.
list List all installed modules.
outdated List installed modules that need updates.
show Display information about a module on vpm
Use "v help <command>" for more information about a command, example:
`v help build`, `v help build-c`, `v help build-native`
Use "v help <command>" for more information about a command, example: `v help build`, `v help build-c`, `v help build-native`
Use "v help other" to see less frequently used commands.
Use "v help topics" to see a list of all known help topics.
Note: Help is required to write more help topics.
Only build, new, init, doc, fmt, vet, run, test, watch, search, install, remove, update, bin2v, check-md are properly documented currently.
Only build, new, init, doc, fmt, vet, run, test, watch, search, install, remove,
update, bin2v, check-md are properly documented currently.

38
vlib/v/help/fmt.txt
View File

@ -1,38 +0,0 @@
Usage:
v fmt [options] path_to_source.v [path_to_other_source.v]
v fmt [options] path/to/dir [path/to/other_dir]
cat source.v | v fmt
Read source code from stdin, output formatted file to stdout.
Formats the given V source files or recursively formats all files in the directory,
then prints their formatted source to stdout.
Options:
-c Check if a file is already formatted. If not, print the filepath and exit with code 2.
Compared to -verify it is quicker but has a small trade-off in precision.
-diff Display the differences between the formatted source(s) and the original source(s).
This will attempt to find a working `diff` command automatically unless you
specify one with the VDIFF_TOOL environment variable.
-l List files whose formatting differs from vfmt.
-w Write result to (source) file(s) instead of to stdout.
-backup In combination with `-w`, copy the original `file.v` to a `file.v.bak` backup,
before overwriting the original source file.
-debug Print the kinds of encountered AST statements/expressions on stderr.
-verify Make sure the provided file is already formatted. Useful for checking code contributions
in CI for example.
Environment Variables:
VDIFF_TOOL A command-line tool that will be executed with the original file path
and a temporary formatted file path as arguments. e.g.
`VDIFF_TOOL=opendiff v fmt -diff path/to/file.v` will become:
opendiff path/to/file.v /tmp/v/vfmt_file.v
VDIFF_OPTIONS A set of command-line options to be sent immediately after the
`diff` command. e.g.
VDIFF_OPTIONS="-W 80 -y" v fmt -diff path/to/file.v /tmp/v/vfmt_file.v

23
vlib/v/help/gret.txt
View File

@ -1,23 +0,0 @@
Usage:
v gret [options] PATH [PATH]
Description:
Dump and/or compare rendered frames of graphical apps
both external and `gg` based apps is supported.
Examples:
Generate screenshots to `/tmp/test`
v gret /tmp/test
Generate and compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst`
v gret /tmp/src /tmp/dst
Compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst`
v gret --compare-only /tmp/src /tmp/dst
Options:
-h, --help Show this help text.
-v, --verbose Be verbose about the tool's progress.
-c, --compare-only Don't generate screenshots - only compare input directories
-r, --root-path Root path of the comparison
-t, --toml-config Path or string with TOML configuration
--version output version information and exit

49
vlib/v/help/help.v
View File

@ -8,6 +8,7 @@ const (
unknown_topic = '`v help`: unknown help topic provided. Use `v help` for usage information.'
)
// print_and_exit Prints the help topic and exits
pub fn print_and_exit(topic string) {
vexe := pref.vexe_path()
vroot := os.dir(vexe)
@ -20,14 +21,47 @@ pub fn print_and_exit(topic string) {
eprintln(help.unknown_topic)
exit(1)
}
// `init` has the same help topic as `new`
name := if topic == 'init' { 'new' } else { topic }
mut path_to := topic
mut topics := os.walk_ext(topicdir, '.txt')
mut items := [][]string{}
mut item_rev := []string{}
mut delim := ''
// Getting the directory, splitting at `/`, trimming to only indexes 0 and 1,
// and reversing that into the items array
for mut item in topics {
$if windows {
delim = '\\'
} $else {
delim = '/'
}
item_rev = item.split(delim).reverse()
item_rev.trim(2)
items << item_rev.reverse()
}
// Getting the path to the help topic text file
for cmds in items {
if '${topic}.txt' in cmds {
path_to = '${cmds[0]}/${cmds[1].replace('.txt', '')}'
break
}
}
topic_dir := if topic == 'default' {
os.join_path(topicdir, 'default.txt')
} else {
os.join_path(topicdir, '${path_to}.txt')
}
if topic == 'topics' {
println(known_topics(topicdir))
exit(0)
}
target_topic := os.join_path(topicdir, '${name}.txt')
content := os.read_file(target_topic) or {
content := os.read_file(topic_dir) or {
eprintln(help.unknown_topic)
eprintln(known_topics(topicdir))
exit(1)
@ -36,13 +70,14 @@ pub fn print_and_exit(topic string) {
exit(0)
}
// known_topics Getting topics known to V
fn known_topics(topicdir string) string {
mut res := []string{}
res << 'Known help topics: '
topic_files := os.glob(os.join_path(topicdir, '*.txt')) or { [] }
mut topics := topic_files.map(os.file_name(it).replace('.txt', ''))
mut topics := os.walk_ext(topicdir, '.txt').map(os.file_name(it).replace('.txt', ''))
topics.sort()
res << topics.join(', ')
res << '.'
return res.join('')
return res.join('').replace('default, ', '')
}

31
vlib/v/help/help_test.v
View File

@ -19,3 +19,34 @@ fn test_help_as_long_option() {
assert res.exit_code == 0
assert res.output.starts_with('V is a tool for managing V source code.')
}
fn test_all_help() {
vroot := os.dir(vexe)
topicdir := os.join_path(vroot, 'vlib', 'v', 'help')
mut topics := os.walk_ext(topicdir, '.txt')
mut items := []string{}
mut delim := ''
for mut item in topics {
$if windows {
delim = '\\'
} $else {
delim = '/'
}
mut item_rev := item.replace('.txt', '').split(delim).reverse()
item_rev.trim(2)
items << item_rev.reverse()
}
for topic in items {
res := os.execute('${os.quoted_path(vexe)} help ${topic}')
if topic == 'help' {
continue
}
assert res.exit_code == 0
assert res.output != ''
}
}

4
vlib/v/help/init.txt
View File

@ -1,4 +0,0 @@
Usage:
v init
Setup the file structure for an already existing V project.

14
vlib/v/help/install.txt
View File

@ -1,14 +0,0 @@
Usage:
v install [PACKAGE...]
Installs each PACKAGE.
If no PACKAGEs, the packages listed in the `v.mod` file are installed instead.
Options:
--vpm - [Default] Install from vpm
--git - Install from git repository url
--hg - Install from mercurial repository url
--once - Only install the package if it was not previously installed
-help - Show usage info.
-v - Print more details about the performed operation.
-server-url - When doing network operations, use this vpm server. Can be given multiple times.

9
vlib/v/help/installation/installation.txt Normal file
View File

@ -0,0 +1,9 @@
Installation Management Utilities:
self Rebuild V with the passed options.
symlink Add a symlink for the V compiler executable.
up Update the V compiler to the latest version from https://github.com/vlang/v.
version Print the version of V installed

7
vlib/v/help/installation/self.txt Normal file
View File

@ -0,0 +1,7 @@
Rebuild V with the passed options.
Usage:
v self
Options:
All other options are passed to the build command. (e.g. -prod)

8
vlib/v/help/symlink.txt → vlib/v/help/installation/symlink.txt
View File

@ -1,7 +1,9 @@
Usage: v symlink [OPTIONS]
This command adds a symlink for the V compiler executable.
Note that on Unix systems this command requires write permissions to /usr/local/bin to work.
Usage:
v symlink [OPTIONS]
Note that on Unix systems this command requires write permissions to
/usr/local/bin to work.
For GitHub Actions, the option -githubci needs to be specified.

8
vlib/v/help/installation/up.txt Normal file
View File

@ -0,0 +1,8 @@
Update the V compiler to the latest version from https://github.com/vlang/v.
Usage:
v up
Options:
-v Print more details about the update.
-prod Compile the updated V with the -prod flag.

5
vlib/v/help/version.txt → vlib/v/help/installation/version.txt
View File

@ -1,3 +1,4 @@
Usage: v version
Print the version of V installed.
Usage:
v version

18
vlib/v/help/ls.txt
View File

@ -1,18 +0,0 @@
Usage:
v ls [options] [ARGS]
Description:
Installs, updates, and executes the V language server program
Options:
--json Print the output as JSON.
--silent Disables output printing.
--install Installs the language server. You may also use this flag to re-download or force update your existing installation.
--update Updates the installed language server.
--check Checks if the language server is installed.
--force Force install or update the language server.
--source Clone and build the language server from source.
--ls Pass the arguments to the language server.
-p, --path <string> Path to the language server executable.
-h, --help Show this updater's help text. To show the help text for the language server's, pass the `--ls` flag before it.
--version output version information and exit

36
vlib/v/help/missdoc.txt
View File

@ -1,36 +0,0 @@
v missdoc 0.1.0
-----------------------------------------------
Usage: v missdoc [options] PATH [PATH]...
Description: Prints all V functions in .v files under PATH/, that do not yet have documentation comments.
Options:
-h, --help Show this help text.
-t, --tags Also print function tags if any is found.
-d, --deprecated Include deprecated functions in output.
-p, --private Include private functions in output.
--js Include JavaScript functions in output.
-n, --no-line-numbers Exclude line numbers in output.
-e, --exclude <multiple strings>
-r, --relative-paths Use relative paths in output.
--verify exit(1) if documentation is missing, 0 otherwise.
--diff exit(1) and show difference between two PATH inputs, return 0 otherwise.
--version output version information and exit
-----------------------------------------------
PATH can be both files and directories.
The `--verify` flag is useful for use in CI setups for checking if a V project
has all it's functions and methods documented:
```
v missdoc --verify path/to/code
```
The `--diff` flag is useful if your project is not yet fully documented
but you want to ensure that no new functions or methods are introduced
between commits or branches:
```
v missdoc --diff current/code new/code
```

18
vlib/v/help/new.txt
View File

@ -1,18 +0,0 @@
Usage:
v new [NAME] [DESCRIPTION]
Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World"
file, and performs 'git init' (if git is installed on the system).
If NAME is given, the project will be setup in a new directory with that
name, and that name will be added to the 'v.mod' file. If no name is given,
the user will be prompted for a name.
If DESCRIPTION is given, the 'v.mod' file is updated with said description.
v init
Sets up a V project within the current directory.
If no '.v' file exists, then will create a 'main.v' file.
If no 'v.mod' file exists, one will be created.
If the current directory is not already controlled with 'git', will perform
'git init' (if git is installed on the system).

33
vlib/v/help/other.txt
View File

@ -1,33 +0,0 @@
These are utility commands that you can also launch through v,
but which are used less frequently by users:
ast Generate a json representation of the AST for a given .v file.
bug Post an issue on the V's issue tracker, including the failing program, and some diagnostic information.
bin2v Convert a binary file to a v source file,
that can be later embedded in a module or program.
build-examples Test if all examples can be built.
build-tools Test if all tools can be built.
build-vbinaries Test if V can be built with different configuration.
check-md Check that V examples in markdown files are formatted and can compile.
setup-freetype Setup thirdparty freetype on Windows.
test-all Run most checks, that the CI does locally.
It may take over 2 minutes, and it needs internet connectivity too,
because it tries to also verify that `v install` works.
test-fmt Test if all files in the current directory are formatted properly.
test-parser Test that the V parser works with the given files, as if
they were typed by a human programmer, one character at a time.
NB: *very slow* for longer files (tens of seconds for 1KB .v file).
Mainly useful as a parser bug finder for the V Language Server project.
test-self Test if V is working properly by running all tests, including the compiler ones.
NB: this can 1-2 minutes to run.
wipe-cache Remove the V cache folder. Useful for cleaning the cache, and guaranteeing a clean build.

27
vlib/v/help/other/ast.txt Normal file
View File

@ -0,0 +1,27 @@
Dump a JSON representation of the V AST for a given .v or .vsh file.
Usage:
v ast demo.v generate demo.json file.
v ast -w demo.v generate demo.json file, and watch for changes.
v ast -c demo.v generate demo.json *and* a demo.c file, and watch for
changes.
v ast -p demo.v print the json output to stdout.
Dump a JSON representation of the V AST for a given .v or .vsh file.
By default, `v ast` will save the JSON to a .json file, named after the .v file.
Pass -p to see it instead.
The arguments should be at least 1 in number.
Options:
-w, --watch Watch a .v file for changes, rewrite the .json file,
when a change is detected
-p, --print Print the AST to stdout
-c, --compile Watch the .v file for changes, rewrite the .json
File, *AND* generate a .c file too on any change
-t, --terse terse output, only with tree node names
(AST structure), no details
--hide <multiple strings> Hide the specified fields. You can give several, by
separating them with `,`
-h, --help Display this help and exit
--version Output version information and exit

14
vlib/v/help/other/bin2v.txt Normal file
View File

@ -0,0 +1,14 @@
Converts a list of arbitrary files into a single v module file.
Usage:
v bin2v [options] FILE[...]
You can use this tool to embed binary files, like pictures or fonts inside
the executable of a v program, such that it would not need access to external
resources during runtime, and it would be as self-contained as possible.
Options:
-h, --help Show this help screen.
-m, --module <string> Name of the generated module.
-p, --prefix <string> A prefix put before each resource name.
-w, --write <string> Write directly to a file with the given name.

8
vlib/v/help/other/bug.txt Normal file
View File

@ -0,0 +1,8 @@
Open a prefilled bug report on GitHub.
Usage:
v bug [options] FILE
Options:
-v Enable verbosity while gathering various information
-y Force the submission of the issue, even if an error occured

28
vlib/v/help/other/bump.txt Normal file
View File

@ -0,0 +1,28 @@
Bump the semantic version of the v.mod and/or specified files.
Usage:
v bump [options] [file1 file2 ...]
The first instance of a version number is replaced with the new version.
Additionally, the line affected must contain the word "version" in any
form of capitalization. For instance, the following lines will be
recognized by the heuristic:
tool_version = '1.2.1'
version: '0.2.42'
VERSION = "1.23.8"
Examples:
Bump the patch version in v.mod if it exists
v bump --patch
Bump the major version in v.mod and vls.v
v bump --major v.mod vls.v
Upgrade the minor version in sample.v only
v bump --minor sample.v
Options:
-h, --help Show this help text.
-m, --major Bump the major version.
-n, --minor Bump the minor version.
-p, --patch Bump the patch version.

34
vlib/v/help/other/check-md.txt Normal file
View File

@ -0,0 +1,34 @@
check-md is a tool to check the passed markdown files for correct ```v ```
code blocks and other style violations like too long lines/links etc...
Usage:
v check-md [flags] <...files> - Check the given .md files.
v check-md [flags] <...dirs> - Check *all* files in the given directories.
Note: You can also combine files and directories.
Options:
-silent Do not show a progress bar.
-w, -hide-warnings Do not print warnings, only errors.
NB: There are several special keywords, which you can put after the code fences
for v.
These are:
compile Default, can be omitted. The example will be compiled
and formatting is verified.
cgen The example produces C code, which may not be
compilable (when external libs are not installed).
Formatting is verified.
live Compile hot reload examples with the ´-live´ flag set
and verify formatting.
ignore Ignore the example, useful for examples that just use
the syntax highlighting
failcompile Known failing compilation. Useful for examples
demonstrating compiler errors.
okfmt Should only be formatted, but it can refer to invalid
modules, missing functions etc. Useful for partial
examples.
oksyntax Should parse, and be formatted, but may not compile.
Useful for partial examples.
badsyntax Known bad syntax, it should NOT even parse.
wip Like ignore; a planned feature; easy to search.
nofmt Disable fmt verification for individual code blocks.

31
vlib/v/help/other/complete.txt Normal file
View File

@ -0,0 +1,31 @@
Tool for bridging autocompletion between various shells and v
Usage:
v complete [options] [SUBCMD] QUERY...
Supported shells:
bash, fish, zsh, powershell
Examples:
Echo auto-detected shell install script to STDOUT
v complete
Echo specific shell install script to STDOUT
v complete setup bash
Auto complete input `v tes`*USER PUSHES TAB* (in Bash compatible format).
This is not meant for manual invocation - it's called by the relevant
shell via the script installed with `v complete` or `v complete setup SHELL`.
v complete bash v tes
Options:
-h, --help Show this help text.
SUBCMD:
setup : setup [SHELL] Returns the code for completion setup for SHELL
bash : [QUERY] Returns Bash compatible completion code with
completions computed from QUERY
fish : [QUERY] Returns Fish compatible completion code with
completions computed from QUERY
zsh : [QUERY] Returns ZSH compatible completion code with
completions computed from QUERY
powershell: [QUERY] Returns PowerShell compatible completion code with
completions computed from QUERY

5
vlib/v/help/doctor.txt → vlib/v/help/other/doctor.txt
View File

@ -1,3 +1,4 @@
Usage: v doctor
Display some useful info about your system necessary for bug reports.
Usage:
v doctor

24
vlib/v/help/other/gret.txt Normal file
View File

@ -0,0 +1,24 @@
Dump and/or compare rendered frames of graphical apps;
both, external and `gg` based apps are supported.
Usage:
v gret [options] PATH [PATH]
Examples:
Generate screenshots to `/tmp/test`
v gret /tmp/test
Generate and compare screenshots in `/tmp/src` to existing screenshots in
`/tmp/dst`
v gret /tmp/src /tmp/dst
Compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst`
v gret --compare-only /tmp/src /tmp/dst
Options:
-h, --help Show this help text.
-v, --verbose Be verbose about the tool's progress.
-c, --compare-only Don't generate screenshots - only compare input
directories
-r, --root-path Root path of the comparison
-t, --toml-config Path or string with TOML configuration
--version Output version information and exit

20
vlib/v/help/other/ls.txt Normal file
View File

@ -0,0 +1,20 @@
Installs, updates, and executes the V language server program
Usage:
v ls [options] [ARGS]
Options:
--json Print the output as JSON.
--silent Disables output printing.
--install Installs the language server. You may also use this flag
to re-download or force update your existing
installation.
--update Updates the installed language server.
--check Checks if the language server is installed.
--force Force install or update the language server.
--source Clone and build the language server from source.
--ls Pass the arguments to the language server.
-p, --path <string> Path to the language server executable.
-h, --help Show this updater's help text. To show the help text for
the language server's, pass the `--ls` flag before it.
--version output version information and exit

43
vlib/v/help/other/other.txt Normal file
View File

@ -0,0 +1,43 @@
Other less frequently used commands supported by V include:
ast Generate a json representation of the AST for a given .v file.
bug Post an issue on the V's issue tracker, including the failing program, and some diagnostic information.
bin2v Convert a binary file to a v source file,
that can be later embedded in a module or program.
build-examples Test if all examples can be built.
build-tools Test if all tools can be built.
build-vbinaries Test if V can be built with different configuration.
check-md Check that V examples in markdown files are formatted and can compile.
doctor Display some useful info about your system to help reporting bugs.
setup-freetype Setup thirdparty freetype on Windows.
translate Translate C code to V.
tracev Produce a tracing version of the v compiler.
Use `tracev yourfile.v` when the compiler panics.
NB: `tracev` is much slower and more verbose than ordinary `v`
test-all Run most checks, that the CI does locally.
It may take over 2 minutes, and it needs internet connectivity too,
because it tries to also verify that `v install` works.
test-fmt Test if all files in the current directory are formatted properly.
test-parser Test that the V parser works with the given files, as if
they were typed by a human programmer, one character at a time.
NB: *very slow* for longer files (tens of seconds for 1KB .v file).
Mainly useful as a parser bug finder for the V Language Server project.
test-self Test if V is working properly by running all tests, including the compiler ones.
NB: this can 1-2 minutes to run.
wipe-cache Remove the V cache folder. Useful for cleaning the cache, and guaranteeing a clean build.

23
vlib/v/help/other/shader.txt Normal file
View File

@ -0,0 +1,23 @@
Compile shaders in sokol's annotated GLSL format
Usage:
v shader [options] [DIRECTORY / FILE]
Compile shaders in sokol's annotated GLSL format to C headers for use with
sokol based apps. Sokol based apps include all apps using V's gg module.
Examples:
v shader .
v shader examples/sokol/02_cubes_glsl/cube_glsl.glsl
Options:
-h, --help Show this help text.
-v, --verbose Be verbose about the tools progress.
-u, --force-update Force update of the sokol-shdc tool.
-l, --slang <multiple strings> Shader dialects to generate code for.
Default is all.
Available: 'glsl330', 'glsl100',
'glsl300es', 'hlsl4', 'hlsl5',
'metal_macos', 'metal_ios', 'metal_sim',
'wgpu'

5
vlib/v/help/tracev.txt → vlib/v/help/other/tracev.txt
View File

@ -1,3 +1,4 @@
Usage: v tracev
Produce a tracing version of the V compiler.
Usage:
v tracev

9
vlib/v/help/remove.txt
View File

@ -1,9 +0,0 @@
Usage:
v remove [PACKAGE...]
Removes all listed PACKAGEs.
If no PACKAGE is provided, removes ALL installed packages.
Options:
-help - Show usage info.
-v - Print more details about the performed operation.
-server-url - When doing network operations, use this vpm server. Can be given multiple times.

9
vlib/v/help/scaffolding/init.txt Normal file
View File

@ -0,0 +1,9 @@
Sets up a V project within the current directory.
Usage:
v init
If no '.v' file exists, then will create a 'main.v' file.
If no 'v.mod' file exists, one will be created.
If the current directory is not already controlled with 'git', will perform
'git init' (if git is installed on the system).

13
vlib/v/help/scaffolding/new.txt Normal file
View File

@ -0,0 +1,13 @@
Sets up a new V project
Usage:
v new [NAME] [DESCRIPTION]
Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World"
file, and performs 'git init' (if git is installed on the system).
If NAME is given, the project will be setup in a new directory with that
name, and that name will be added to the 'v.mod' file. If no name is given,
the user will be prompted for a name.
If DESCRIPTION is given, the 'v.mod' file is updated with said description.

6
vlib/v/help/scaffolding/scaffolding.txt Normal file
View File

@ -0,0 +1,6 @@
Project Scaffolding Utilities:
init Sets up the file structure for an already existing V project.
new Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World"
file, and performs 'git init' (if git is installed on the system).

10
vlib/v/help/search.txt
View File

@ -1,10 +0,0 @@
Usage:
v search KEYWORD[...]
Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the
details
Options:
-help - Show usage info.
-v - Print more details about the performed operation.
-server-url - When doing network operations, use this vpm server. Can be
given multiple times.

5
vlib/v/help/self.txt
View File

@ -1,5 +0,0 @@
Usage: v self
Rebuild V with the passed options.
Options: All other options are passed to the build command. (e.g. -prod)

17
vlib/v/help/shader.txt
View File

@ -1,17 +0,0 @@
Usage:
v shader [options] [DIRECTORY / FILE]
Examples:
v shader .
v shader examples/sokol/02_cubes_glsl/cube_glsl.glsl
Compile shaders in sokol's annotated GLSL format to C headers for use with sokol based apps.
Sokol based apps include all apps using V's gg module.
Options:
-h, --help Show this help text.
-v, --verbose Be verbose about the tools progress.
-u, --force-update Force update of the sokol-shdc tool.
-l, --slang <multiple strings> Shader dialects to generate code for. Default is all.
Available: 'glsl330', 'glsl100', 'glsl300es', 'hlsl4', 'hlsl5', 'metal_macos', 'metal_ios', 'metal_sim', 'wgpu'

7
vlib/v/help/up.txt
View File

@ -1,7 +0,0 @@
Usage: v up
Update the V compiler to the latest version from https://github.com/vlang/v.
Options:
-v - Print more details about the update.
-prod - Compile the updated V with the -prod flag.

10
vlib/v/help/update.txt
View File

@ -1,10 +0,0 @@
Usage:
v update [PACKAGE]...
Updates each PACKAGE.
With no PACKAGE, ALL installed packages are updated to their latest versions.
Options:
-help - Show usage info.
-v - Print more details about the update.
-server-url - When doing network operations, use this vpm server. Can be given multiple times.

7
vlib/v/help/upgrade.txt
View File

@ -1,7 +0,0 @@
Usage: v upgrade
Upgrade all outdated modules.
Options:
-help - Show usage info.
-v - Print more details about the upgrade.

21
vlib/v/help/vet.txt
View File

@ -1,21 +0,0 @@
Usage:
v vet [options] path_to_source.v [path_to_other_source.v]
v vet [options] path/to/dir [path/to/other_dir]
Reports suspicious code constructs.
Options:
-W
Exit with code 1, even if vet only reported warnings. Useful for checks in CI.
-w, -hide-warnings
Do not print warnings to stderr.
-v, -verbose
Enable verbose logging.
-p
Report private functions with missing documentation too (by default, only the `pub fn` functions will be reported).
-force
(NB: vet development only!) Do not skip the vet regression tests.

8
vlib/v/help/vpm.txt
View File

@ -1,8 +0,0 @@
Usage:
a) v install [PACKAGE...]
b) v update [PACKAGE...]
c) v remove [PACKAGE...]
d) v search KEYWORD[...]
e) v show [PACKAGE...]
You can also pass -h or --help after each vpm command from the above, to see more details about it.

16
vlib/v/help/vpm/install.txt Normal file
View File

@ -0,0 +1,16 @@
Installs each PACKAGE.
Usage:
v install [PACKAGE...]
If no PACKAGEs, the packages listed in the `v.mod` file are installed instead.
Options:
--vpm [Default] Install from vpm
--git Install from git repository url
--hg Install from mercurial repository url
--help, -h Prints the help menu
--once Only install the package if it was not previously installed
-v Print more details about the performed operation.
-server-url When doing network operations, use this vpm server.
Can be given multiple times.

5
vlib/v/help/list.txt → vlib/v/help/vpm/list.txt
View File

@ -1,3 +1,4 @@
Usage: v list
List all installed packages.
Usage:
v list

5
vlib/v/help/outdated.txt → vlib/v/help/vpm/outdated.txt
View File

@ -1,3 +1,4 @@
Usage: v outdated
List all installed modules that need updates.
Usage:
v outdated

11
vlib/v/help/vpm/remove.txt Normal file
View File

@ -0,0 +1,11 @@
Removes all listed PACKAGEs.
Usage:
v remove [PACKAGE...]
If no PACKAGE is provided, removes ALL installed packages.
Options:
-v Print more details about the performed operation.
-server-url When doing network operations, use this vpm server.
Can be given multiple times.

9
vlib/v/help/vpm/search.txt Normal file
View File

@ -0,0 +1,9 @@
Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the details
Usage:
v search KEYWORD[...]
Options:
-v Print more details about the performed operation.
-server-url When doing network operations, use this vpm server. Can be
given multiple times.

5
vlib/v/help/show.txt → vlib/v/help/vpm/show.txt
View File

@ -1,3 +1,4 @@
Usage: v show
Display information about a module on vpm.
Usage:
v show

11
vlib/v/help/vpm/update.txt Normal file
View File

@ -0,0 +1,11 @@
Updates each PACKAGE.
Usage:
v update [PACKAGE]...
With no PACKAGE, ALL installed packages are updated to their latest versions.
Options:
-v Print more details about the update.
-server-url When doing network operations, use this vpm server.
Can be given multiple times.

7
vlib/v/help/vpm/upgrade.txt Normal file
View File

@ -0,0 +1,7 @@
Upgrade all outdated modules.
Usage:
v upgrade
Options:
-v Print more details about the upgrade.

17
vlib/v/help/vpm/vpm.txt Normal file
View File

@ -0,0 +1,17 @@
Package Management Utilities:
install Installs each PACKAGE.
list List all installed packages.
outdated List all installed modules that need updates.
remove Removes all listed PACKAGEs.
search Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the details
show Display information about a module on vpm.
update Updates each PACKAGE.
upgrade Upgrade all outdated modules.

28
vlib/v/help/watch.txt
View File

@ -1,28 +0,0 @@
v watch [--clear] [--ignore .db] [--add /path/to/a/file.v] [other V options] [run] program.v
Description:
`v watch` collects all .v files needed for a compilation, then when
any of the .v source files changes, it re-runs the compilation.
Options:
-s, --silent Be more silent; do not print the watch timestamp before each re-run.
-c, --clear Clears the terminal before each re-run.
-a, --add <string> Add more files to be watched.
Useful with `v watch -add=feature.v run cmd/v feature.v`,
when you want to change *both* the V compiler,
and the `feature.v` file.
-i, --ignore <string> Ignore files having these extensions.
Useful with `v watch -ignore=.db run vwebserver.v`,
if your `vwebserver` writes to an sqlite.db file in the
same folder.
--before <string> A command to execute *before* each re-run. Example: --before 'v wipe-cache'
--after <string> A command to execute *after* each re-run. Example: --after 'rm -rf /tmp/v/'
You can also customise the timeout, after `v watch` will re-start a monitored
program automatically, even if it was not changed by setting the enviroment
variable VWATCH_TIMEOUT (in seconds). By default, it is 5 min. (300 seconds).

42
vlib/v/help/where.txt
View File

@ -1,42 +0,0 @@
Usage:
v where symbol_type symbol_name [params]
Examples:
v where fn main
v where struct User
v where method Square.area
v where fn pow -mod math
v where interface callable -dir some -dir other
--------------------------------------------------------------------------------
Prints the location of the searched symbols in the scope of the current project.
--------------------------------------------------------------------------------
symbol_name can be:
fn by default if omit symbol_type (don't omit preferably)
method require Struct.method notation
struct
interface
enum
const
var
regexp
params:
-mod [mod_name] Restrict to search recursively only within of the given
module, if not provided search in entire v scope
(use -mod main to search inside all your project).
-dir [dir_path] Restrict to search non recursively within the given
folder/s, if not provided, search in entire v scope.
-vis [visibility] Can be: all, pub, pri (all by default if not provided).
Restrict to search symbols with the given visibility.
-mut [mutability] Can be: any, yes, not (any by default if not provided).
Restrict to search symbols with the given mutability.
flags:
-h include Header
-f Format output (each match uses 3 lines)
-v for both above (more Verbose)
Note:
This tool is inspired by the vdoc tool and its design. However, this is
for a more specific use, and can be improved.