1 | pub fn show_topic(topic string) { |
2 | vexe := os.real_path(os.getenv('VEXE')) |
3 | vroot := os.dir(vexe) |
4 | - target_topic := os.join_path(vroot, 'vlib', 'v', 'help', '${topic}.txt') |
5 | - content := os.read_file(target_topic) or { |
6 | + topicdir := os.join_path(vroot, 'vlib', 'v', 'help') |
7 | + |
8 | + mut path_to := topic |
9 | + mut topics := os.walk_ext(topicdir, '.txt') |
10 | + mut items := [][]string{} |
11 | + |
12 | + // Getting the directory, splitting at `/`, reversing, |
13 | + // trimming to only indexes 0 and 1, and reversing that into the items array |
14 | + for mut item in topics { |
15 | + mut item_rev := item.split('/').reverse() |
16 | + item_rev.trim(2) |
17 | + items << item_rev.reverse() |
18 | + } |
19 | + |
20 | + // Getting the path to the help topic text file |
21 | + for cmds in items { |
22 | + if '${topic}.txt' in cmds { |
23 | + path_to = '${cmds[0]}/${cmds[1].replace('.txt', '')}' |
24 | + break |
25 | + } |
26 | + } |
27 | + |
28 | + topic_dir := if topic == 'default' { |
29 | + os.join_path(topicdir, 'default.txt') |
30 | + } else { |
31 | + os.join_path(topicdir, '${path_to}.txt') |
32 | + } |
33 | + |
34 | + content := os.read_file(topic_dir) or { |
35 | eprintln('Unknown topic: ${topic}') |
36 | exit(1) |
37 | } |
38 |
1 | timers.show('v start') |
2 | timers.start('parse_CLI_args') |
3 | args := os.args[1..] |
4 | + |
5 | if args.len == 0 || args[0] in ['-', 'repl'] { |
6 | if args.len == 0 { |
7 | // Running `./v` without args launches repl |
8 |
1 | new file mode 100644 |
2 | +# Formatting a Help File |
3 | + |
4 | +## Requirements |
5 | + |
6 | +- 2 space initial indentation (titles exempt) |
7 | +- Description indentation of two spaces from the longest word |
8 | +- All descriptions should be indented to the same column within a block, with a |
9 | +hard limit at column 80. |
10 | + - Multi-line descriptions should indent to match the description part of the previous line |
11 | + |
12 | + |
13 | +## Example |
14 | + |
15 | +Adding a help file was made to be easy. All you have to do is create the text file in the |
16 | +appropriate category, and V should recognize it. |
17 | + |
18 | +```text |
19 | +Short description of what it does |
20 | + |
21 | +Usage: |
22 | + v COMMAND (args and such here) |
23 | + |
24 | +Longer description of what your command aims to do (optional) |
25 | + |
26 | +Examples: (optional) |
27 | + v COMMAND -arg1 -arg2 |
28 | + |
29 | +Options: |
30 | + -h, --help Help menu |
31 | + -s, --short Description of short |
32 | + -l, --long Description of long |
33 | +``` |
34 |
1 | deleted file mode 100644 |
2 | -Usage: v ast demo.v generate demo.json file. |
3 | - or: v ast -w demo.v generate demo.json file, and watch for changes. |
4 | - or: v ast -c demo.v generate demo.json *and* a demo.c file, and watch for changes. |
5 | - or: v ast -p demo.v print the json output to stdout. |
6 | - |
7 | -Description: Dump a JSON representation of the V AST for a given .v or .vsh file. |
8 | -By default, `v ast` will save the JSON to a .json file, named after the .v file. |
9 | -Pass -p to see it instead. |
10 | - |
11 | -The arguments should be at least 1 in number. |
12 | - |
13 | -Options: |
14 | - -w, --watch watch a .v file for changes, rewrite the .json file, when a change is detected |
15 | - -p, --print print the AST to stdout |
16 | - -c, --compile watch the .v file for changes, rewrite the .json file, *AND* generate a .c file too on any change |
17 | - -t, --terse terse output, only with tree node names (AST structure), no details |
18 | - --hide <multiple strings> |
19 | - hide the specified fields. You can give several, by separating them with `,` |
20 | - -h, --help display this help and exit |
21 | - --version output version information and exit |
22 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v bin2v [options] FILE[...] |
4 | - |
5 | - Converts a list of arbitrary files into a single v module file. |
6 | - |
7 | - You can use this tool to embed binary files, like pictures or fonts inside |
8 | - the executable of a v program, such that it would not need access to external |
9 | - resources during runtime, and it would be as self-contained as possible. |
10 | - |
11 | -Options: |
12 | - -h, --help Show this help screen. |
13 | - -m, --module <string> Name of the generated module. |
14 | - -p, --prefix <string> A prefix put before each resource name. |
15 | - -w, --write <string> Write directly to a file with the given name. |
16 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v bug [options] FILE |
4 | - |
5 | - Open a prefilled bug report on GitHub. |
6 | - |
7 | -Options: |
8 | - -v Enable verbosity while gathering various information |
9 | - -y Force the submission of the issue, even if an error occured |
10 |
1 | deleted file mode 100644 |
2 | -Usage: v -b js [-options] ['run'] <target.v|target_directory> [run options] |
3 | - |
4 | -This command compiles the given target, along with their dependencies, into an Javascript source file. |
5 | - |
6 | -Note that `js` defaults to the `node` codegen backend but it's also possible to pick another: |
7 | - |
8 | -* `js_browser` - V outputs JS source code ready for the browser. |
9 | -* `js_node` - V outputs JS source code to run with nodejs. |
10 | -* `js_freestanding` - V outputs JS source code with no hard runtime dependency. |
11 | - |
12 | -For more general build help, see also `v help build`. |
13 | - |
14 | -# Interfacing the Javascript Backend code generation, passing options to it: |
15 | - -es5 |
16 | - Compile V to ES5 compatible code possibly shrinking output. Note that this flag might limit some types capabilities. |
17 | - -prod |
18 | - Do not create any JS Doc comments |
19 | - |
20 | - -sourcemap |
21 | - Create a source map for debugging |
22 | - |
23 | - -sourcemap-inline |
24 | - Embed the source map directly into the JavaScript source file |
25 | - (currently default, external source map files not implemented) |
26 | - |
27 | - -sourcemap-src-include |
28 | - Include the orginal V source files into the generated source map |
29 | - (default false, all files in the source map are currently referenced by their absolute system file path) |
30 | - |
31 | - The supported targets for the JS backend are: ES6 strict |
32 |
1 | deleted file mode 100644 |
2 | -Usage: v -native [-options] ['run'] <target.v|target_directory> [run options] |
3 | - |
4 | -This command compiles the given target, along with their dependencies, into an executable using the Native code generation backend. |
5 | - |
6 | -For more general build help, see also `v help build`. |
7 | - |
8 | -# Interfacing the Native code generation, passing options to it: |
9 | - -v |
10 | - Display the assembly code generated (that may change to `-showasm` in the future) |
11 | - |
12 | - -arch <arch> |
13 | - Select target architecture, right now only `arm64` and `amd64` are supported |
14 | - |
15 | - -os <os>, -target-os <os> |
16 | - Change the target OS that V compiles for. |
17 | - |
18 | - The supported targets for the native backend are: `macos`, `linux` and 'windows' |
19 |
1 | deleted file mode 100644 |
2 | -Usage: v [build flags] ['run'] <target.v|target_directory> [run options] |
3 | - |
4 | -This command compiles the given target, along with their dependencies, into an executable. |
5 | - |
6 | -Note that these build flags also work with `run` too, but you need to |
7 | -pass them *before* `run` . The argument directly after `run` is assumed |
8 | -to be a .v source file or folder containing .v source files. |
9 | -Everything after that, is assumed to be flags, that V will ignore itself, |
10 | -but will pass to the executable after it is compiled. |
11 | - |
12 | -This enables you to do for example: `v -cc gcc -g myfile.v run -param1 abcde` |
13 | -... which means for V: "compile using gcc, produce debugging information, |
14 | -then run `./myfile -param1 abcde` and exit with its exit code". |
15 | - |
16 | -When compiling packages, V ignores files that end in '_test.v'. |
17 | - |
18 | -When compiling a single main package, V writes the resulting executable to an output file |
19 | -named after the build target. ('v abc.v' and 'v abc/' both write either 'abc' or 'abc.exe') |
20 | -The '.exe' suffix is added automatically, when writing a Windows executable. |
21 | -By default, the executable is stored in the same directory as the compiled source code. |
22 | - |
23 | -The -o flag forces V to write the resulting executable or object to the d output file or directory, |
24 | -instead of the default behavior described in the last two paragraphs. |
25 | - |
26 | -You can put common options inside an environment variable named VFLAGS, so that |
27 | -you don't have to repeat them. |
28 | - |
29 | -You can set it like this: `export VFLAGS="-cc clang -g"` on *nix, |
30 | -`set VFLAGS=-cc msvc` on Windows. |
31 | - |
32 | -V respects the TMPDIR environment variable, and will put .tmp.c files in TMPDIR/v/ . |
33 | -If you have not set it, a suitable platform specific folder (like /tmp) will be used. |
34 | - |
35 | -NB: the build flags are shared with the run command too: |
36 | - |
37 | - -b <backend>, -backend <backend> |
38 | - Specifies the backend that will be used for building the executable. |
39 | - Current list of supported backends: |
40 | - * `c` (default) - V outputs C source code, which is then passed to a C compiler. |
41 | - * `go` - V outputs Go source code, which is then passed to a Go compiler. |
42 | - * `interpret` - V will interpret the V program directly, instead of compiling it first. Same as `v interpret file.v`. |
43 | - * `js` - V outputs JS source code which can be passed to NodeJS to be ran. |
44 | - * `js_browser` - V outputs JS source code ready for the browser. |
45 | - * `js_node` - V outputs JS source code to run with nodejs. |
46 | - * `js_freestanding` - V outputs JS source code with no hard runtime dependency. |
47 | - * `native` - V outputs a native executable directly (see -arch x64|arm64 and -os linux|macos) (EXPERIMENTAL). |
48 | - |
49 | - -d <flag>[=<value>], -define <flag>[=<value>] |
50 | - Define the provided flag. |
51 | - If value is not provided, it is assumed to be set to `true`. |
52 | - `value` should be `1` or `0` to indicate `true` and `false` respectively otherwise. |
53 | - |
54 | - -g |
55 | - Compile the executable in debug mode, allowing code to be debugged more easily. |
56 | - |
57 | - -o <output>, -output <output> |
58 | - Force V to output the executable in a specific location |
59 | - (relative to the current working directory if not absolute). |
60 | - |
61 | - -obf, -obfuscate |
62 | - Turn on obfuscation for the code being built. Currently only renames symbols. |
63 | - |
64 | - -path |
65 | - Specify the order of path V looks up in while searching for imported dependencies, |
66 | - separated by pipes (`|`). In addition to absolute paths, you can |
67 | - also use these special strings too: |
68 | - @vmodules - replaced with the location of the global ~/.vmodules/ folder |
69 | - (modules installed with `v install` are there). You can change |
70 | - its location by setting the environment variable VMODULES. |
71 | - @vlib - replaced with the location of the v's vlib folder. |
72 | - Using these, you can arrange for very flexible search orders for you project, for example: |
73 | - -path "/v/my_project_private_modules|@vlib|@vmodules" |
74 | - By default, -path is just "@vlib|@vmodules" . |
75 | - |
76 | - -prod |
77 | - Compile the executable in production mode, where most optimizations are enabled. |
78 | - Note that most V warnings turn to errors, if you pass -prod, so you will have |
79 | - to fix them first. |
80 | - |
81 | - -no-bounds-checking |
82 | - Programs compiled with this option, will do no runtime checking of array access operations. |
83 | - Note that the performance impact of the bounds checking is usually below 3%, so in most |
84 | - cases, it is preferable to not turn it off, than disable it, and have a program that may |
85 | - do out of bounds accesses. |
86 | - |
87 | - -prof, -profile <file.txt> |
88 | - Compile the executable with all functions profiled. |
89 | - The profile results will be stored in `file.txt`. |
90 | - The format is 4 fields, separated by a space, for each v function: |
91 | - a) how many times it was called |
92 | - b) how much *nanoseconds in total* it took |
93 | - c) an average for each function (i.e. (b) / (a) ) |
94 | - d) the function name |
95 | - |
96 | - NB: you can also combine this command with `run` command. |
97 | - For example - `v -prof prof.txt run main.v` |
98 | - |
99 | - NB: the profiler is *NOT* currently thread safe, so look at the profile results of |
100 | - multithreaded programs very sceptically ! |
101 | - |
102 | - NB: if you want to output the profile info to stdout, use `-profile -`. |
103 | - |
104 | - NB: you can use `import v.profile`, and then calls to `profile.on(false)` |
105 | - and `profile.on(true)` to temporarily turn it off and on again. |
106 | - |
107 | - NB: if you do NOT want the profile to contain information from before your |
108 | - program's `fn main()` starts, pass `-d no_profile_startup` too. |
109 | - (V constants, and module init() functions are evaluated before `main()` is called) |
110 | - |
111 | - NB: You can also select specific functions for profiling. For example: |
112 | - v -profile-fns println,i64_str -profile - run examples/hanoi.v |
113 | - In this case, the profile counters will be updated only for them, *and* for the functions that they call. |
114 | - The profile result (after the program finishes), will look similar to this: |
115 | - 127 0.721ms 5680ns println |
116 | - 127 0.693ms 5456ns _writeln_to_fd |
117 | - 127 0.565ms 4449ns _write_buf_to_fd |
118 | - 127 0.045ms 353ns _v_malloc |
119 | - 127 0.017ms 131ns malloc_noscan |
120 | - 127 0.017ms 133ns _v_free |
121 | - 127 0.014ms 113ns vmemmove |
122 | - 127 0.110ms 866ns i64_str |
123 | - 127 0.016ms 127ns tos |
124 | - |
125 | - -message-limit <limit> |
126 | - The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 100). |
127 | - The checker will abort prematurely once this limit has been reached. |
128 | - Setting this to 0 or a negative value, will disable the limit. |
129 | - |
130 | - -no-parallel |
131 | - Do not run the compiler in parallel (currently only the cgen stage has parallelization). |
132 | - |
133 | - -profile-no-inline |
134 | - Skip [inline] functions when profiling. |
135 | - |
136 | - -skip-unused |
137 | - Skip generating C/JS code for functions, that are provably not used by your project. |
138 | - This speeds up compilation, and reduces the generated output size. |
139 | - It is still experimental, due to historical reasons, but please do try it, |
140 | - and report issues, if compilation breaks with that option for your program. |
141 | - |
142 | - -stats |
143 | - Enable more detailed statistics reporting, while compiling test files. |
144 | - You can use that with `v test` too, for example: |
145 | - v -stats test vlib/ |
146 | - ... will run test_ functions inside all _test.v files inside vlib/ , |
147 | - and will report detailed statistics about how much time each test_ function took, how many |
148 | - assertions were made, how many tests passed/failed and so on. |
149 | - |
150 | - -translated |
151 | - Enable features that are discouraged in regular V code but required for translated V code. |
152 | - |
153 | - -v |
154 | - Enable verbosity in the V compiler while compiling |
155 | - |
156 | - -print-v-files |
157 | - Just print the list of all parsed .v files, then stop processing further. |
158 | - This is useful for running external processing tools: |
159 | - ./v -print-v-files cmd/v | etags -L - |
160 | - ... will generate a TAGS file, that emacs can then use to jump |
161 | - to the definition of functions used by v itself. For vim: |
162 | - ./v -print-v-files cmd/v | ctags -L - |
163 | - ... will generate a simillar tags file, that vi compatible editors can use. |
164 | - NB: an useful, although not entirely accurate regexp based Universal Ctags options file |
165 | - for V is located in `.ctags.d/v.ctags` . If you use https://ctags.io/ , it will be used |
166 | - up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags . |
167 | - |
168 | - -color, -nocolor |
169 | - Force the use of ANSI colors for the V error/warning messages, or disable them completely. |
170 | - By default, the V compiler tries to show its errors/warnings in ANSI color. The heuristic |
171 | - that it uses to detect whether or not to use ANSI colors may not work in all cases. |
172 | - These options allow you to override the default detection. |
173 | - |
174 | - -check |
175 | - Scans, parses, and checks the files without compiling the program. |
176 | - |
177 | - -check-syntax |
178 | - Only scan and parse the files, but then stop. Useful for very quick syntax checks. |
179 | - |
180 | - -show-timings |
181 | - Print a summary about how long each compiler stage took, for example: |
182 | - PARSE: 152ms |
183 | - CHECK: 62ms |
184 | - C GEN: 103ms |
185 | - C tcc: 95ms |
186 | - |
187 | - Related to -show-timings, is the ability to compile a special instrumented |
188 | - v compiler with this command: |
189 | - `v -d time_parsing -d time_checking -d time_cgening -d time_v self` |
190 | - The instrumented version will print detailed timing stats while processing |
191 | - each .v file. |
192 | - |
193 | - -w |
194 | - Hide all warnings. |
195 | - |
196 | - -W |
197 | - Treat *all V warnings* as errors, even in development builds. |
198 | - |
199 | - -Wfatal-errors |
200 | - Unconditionally exit with exit(1) after the first error. |
201 | - Useful for scripts/tooling that calls V. |
202 | - |
203 | - -Wimpure-v |
204 | - Warn about using C. or JS. symbols in plain .v files. |
205 | - These should be moved in .c.v and .js.v . |
206 | - NB: in the future, this will be turned ON by default, |
207 | - and will become an error, after vlib modules are cleaned up. |
208 | - |
209 | -For C-specific build flags, use `v help build-c`. |
210 | -For JS-specific build flags, use `v help build-js`. |
211 | -For Native-specific build flags, use `v help build-native`. |
212 | - |
213 | -See also: |
214 | - `v help run` for documentation regarding `v run`. |
215 |
1 | similarity index 99% |
2 | rename from vlib/v/help/build-c.txt |
3 | rename to vlib/v/help/build/build-c.txt |
4 | -Usage: v [C build flags] ['run'] <target.v|target_directory> [run options] |
5 | - |
6 | This command compiles the given target, along with their dependencies, into an executable. |
7 | |
8 | +Usage: |
9 | + v [build flags] ['run'] <target.v|target_directory> [run options] |
10 | + |
11 | This help topic explores the C-backend specific build flags. For more general build help, |
12 | see also `v help build`. |
13 | |
14 |
1 | new file mode 100644 |
2 | +This command compiles the given target, along with their dependencies, |
3 | +into a Javascript source file. |
4 | + |
5 | +Usage: |
6 | + v -b js [-options] ['run'] <target.v|target_directory> [run options] |
7 | + |
8 | + |
9 | +Note that `js` defaults to the `node` codegen backend but it's also possible to |
10 | +pick another: |
11 | + |
12 | +* `js_browser` - V outputs JS source code ready for the browser. |
13 | +* `js_node` - V outputs JS source code to run with nodejs. |
14 | +* `js_freestanding` - V outputs JS source code with no hard runtime dependency. |
15 | + |
16 | +For more general build help, see also `v help build`. |
17 | + |
18 | +# Interfacing the Javascript Backend code generation, passing options to it: |
19 | + -es5 Compile V to ES5 compatible code possibly shrinking output. Note that this flag might limit some types capabilities. |
20 | + -prod |
21 | + Do not create any JS Doc comments |
22 | + |
23 | + -sourcemap |
24 | + Create a source map for debugging |
25 | + |
26 | + -sourcemap-inline Embed the source map directly into the |
27 | + JavaScript source file |
28 | + (currently default, |
29 | + external source map files not implemented) |
30 | + |
31 | + -sourcemap-src-include Include the orginal V source files into the |
32 | + generated source map |
33 | + (default false, all files in the source map are currently referenced by |
34 | + their absolute system file path) |
35 | + |
36 | +The supported targets for the JS backend are: ES6 strict |
37 |
1 | new file mode 100644 |
2 | +This command compiles the given target, along with their dependencies, |
3 | +into an executable using the Native code generation backend. |
4 | + |
5 | +Usage: |
6 | + v -native [-options] ['run'] <target.v|target_directory> [run options] |
7 | + |
8 | + |
9 | +For more general build help, see also `v help build`. |
10 | + |
11 | +# Interfacing the Native code generation, passing options to it: |
12 | + -v Display the assembly code generated |
13 | + (that may change to `-showasm` in the future) |
14 | + |
15 | + -arch <arch> Select target architecture |
16 | + Only `arm64` and `amd64` are supported |
17 | + |
18 | + -os <os>, -target-os <os> Change the target OS that V compiles for. |
19 | + |
20 | + |
21 | +The supported targets for the native backend are: `macos`, `linux` and 'windows' |
22 |
1 | new file mode 100644 |
2 | +The build system for V |
3 | + |
4 | +Usage: |
5 | + v [build flags] ['run'] <target.v|target_directory> [run options] |
6 | + |
7 | +Note that these build flags also work with `run` too, but you need to |
8 | +pass them *before* `run` . The argument directly after `run` is assumed |
9 | +to be a .v source file or folder containing .v source files. |
10 | +Everything after that, is assumed to be flags, that V will ignore itself, |
11 | +but will pass to the executable after it is compiled. |
12 | + |
13 | +This enables you to do for example: `v -cc gcc -g myfile.v run -param1 abcde` |
14 | +... which means for V: "compile using gcc, produce debugging information, |
15 | +then run `./myfile -param1 abcde` and exit with its exit code". |
16 | + |
17 | +When compiling packages, V ignores files that end in '_test.v'. |
18 | + |
19 | +When compiling a single main package, V writes the resulting executable to an output file |
20 | +named after the build target. ('v abc.v' and 'v abc/' both write either 'abc' or 'abc.exe') |
21 | +The '.exe' suffix is added automatically, when writing a Windows executable. |
22 | +By default, the executable is stored in the same directory as the compiled source code. |
23 | + |
24 | +The -o flag forces V to write the resulting executable or object to the d output file or directory, |
25 | +instead of the default behavior described in the last two paragraphs. |
26 | + |
27 | +You can put common options inside an environment variable named VFLAGS, so that |
28 | +you don't have to repeat them. |
29 | + |
30 | +You can set it like this: `export VFLAGS="-cc clang -g"` on *nix, |
31 | +`set VFLAGS=-cc msvc` on Windows. |
32 | + |
33 | +V respects the TMPDIR environment variable, and will put .tmp.c files in TMPDIR/v/ . |
34 | +If you have not set it, a suitable platform specific folder (like /tmp) will be used. |
35 | + |
36 | +NB: the build flags are shared with the run command too: |
37 | + |
38 | + -b <backend>, -backend <backend> |
39 | + Specifies the backend that will be used for building the executable. |
40 | + Current list of supported backends: |
41 | + * `c` (default) - V outputs C source code, which is then passed to a C compiler. |
42 | + * `go` - V outputs Go source code, which is then passed to a Go compiler. |
43 | + * `interpret` - V will interpret the V program directly, instead of compiling it first. Same as `v interpret file.v`. |
44 | + * `js` - V outputs JS source code which can be passed to NodeJS to be ran. |
45 | + * `js_browser` - V outputs JS source code ready for the browser. |
46 | + * `js_node` - V outputs JS source code to run with nodejs. |
47 | + * `js_freestanding` - V outputs JS source code with no hard runtime dependency. |
48 | + * `native` - V outputs a native executable directly (see -arch x64|arm64 and -os linux|macos) (EXPERIMENTAL). |
49 | + |
50 | + -d <flag>[=<value>], -define <flag>[=<value>] |
51 | + Define the provided flag. |
52 | + If value is not provided, it is assumed to be set to `true`. |
53 | + `value` should be `1` or `0` to indicate `true` and `false` respectively otherwise. |
54 | + |
55 | + -g |
56 | + Compile the executable in debug mode, allowing code to be debugged more easily. |
57 | + |
58 | + -o <output>, -output <output> |
59 | + Force V to output the executable in a specific location |
60 | + (relative to the current working directory if not absolute). |
61 | + |
62 | + -obf, -obfuscate |
63 | + Turn on obfuscation for the code being built. Currently only renames symbols. |
64 | + |
65 | + -path |
66 | + Specify the order of path V looks up in while searching for imported dependencies, |
67 | + separated by pipes (`|`). In addition to absolute paths, you can |
68 | + also use these special strings too: |
69 | + @vmodules - replaced with the location of the global ~/.vmodules/ folder |
70 | + (modules installed with `v install` are there). You can change |
71 | + its location by setting the environment variable VMODULES. |
72 | + @vlib - replaced with the location of the v's vlib folder. |
73 | + Using these, you can arrange for very flexible search orders for you project, for example: |
74 | + -path "/v/my_project_private_modules|@vlib|@vmodules" |
75 | + By default, -path is just "@vlib|@vmodules" . |
76 | + |
77 | + -prod |
78 | + Compile the executable in production mode, where most optimizations are enabled. |
79 | + Note that most V warnings turn to errors, if you pass -prod, so you will have |
80 | + to fix them first. |
81 | + |
82 | + -no-bounds-checking |
83 | + Programs compiled with this option, will do no runtime checking of array access operations. |
84 | + Note that the performance impact of the bounds checking is usually below 3%, so in most |
85 | + cases, it is preferable to not turn it off, than disable it, and have a program that may |
86 | + do out of bounds accesses. |
87 | + |
88 | + -prof, -profile <file.txt> |
89 | + Compile the executable with all functions profiled. |
90 | + The profile results will be stored in `file.txt`. |
91 | + The format is 4 fields, separated by a space, for each v function: |
92 | + a) how many times it was called |
93 | + b) how much *nanoseconds in total* it took |
94 | + c) an average for each function (i.e. (b) / (a) ) |
95 | + d) the function name |
96 | + |
97 | + NB: you can also combine this command with `run` command. |
98 | + For example - `v -prof prof.txt run main.v` |
99 | + |
100 | + NB: the profiler is *NOT* currently thread safe, so look at the profile results of |
101 | + multithreaded programs very sceptically ! |
102 | + |
103 | + NB: if you want to output the profile info to stdout, use `-profile -`. |
104 | + |
105 | + NB: you can use `import v.profile`, and then calls to `profile.on(false)` |
106 | + and `profile.on(true)` to temporarily turn it off and on again. |
107 | + |
108 | + NB: if you do NOT want the profile to contain information from before your |
109 | + program's `fn main()` starts, pass `-d no_profile_startup` too. |
110 | + (V constants, and module init() functions are evaluated before `main()` is called) |
111 | + |
112 | + NB: You can also select specific functions for profiling. For example: |
113 | + v -profile-fns println,i64_str -profile - run examples/hanoi.v |
114 | + In this case, the profile counters will be updated only for them, *and* for the functions that they call. |
115 | + The profile result (after the program finishes), will look similar to this: |
116 | + 127 0.721ms 5680ns println |
117 | + 127 0.693ms 5456ns _writeln_to_fd |
118 | + 127 0.565ms 4449ns _write_buf_to_fd |
119 | + 127 0.045ms 353ns _v_malloc |
120 | + 127 0.017ms 131ns malloc_noscan |
121 | + 127 0.017ms 133ns _v_free |
122 | + 127 0.014ms 113ns vmemmove |
123 | + 127 0.110ms 866ns i64_str |
124 | + 127 0.016ms 127ns tos |
125 | + |
126 | + -message-limit <limit> |
127 | + The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 100). |
128 | + The checker will abort prematurely once this limit has been reached. |
129 | + Setting this to 0 or a negative value, will disable the limit. |
130 | + |
131 | + -no-parallel |
132 | + Do not run the compiler in parallel (currently only the cgen stage has parallelization). |
133 | + |
134 | + -profile-no-inline |
135 | + Skip [inline] functions when profiling. |
136 | + |
137 | + -skip-unused |
138 | + Skip generating C/JS code for functions, that are provably not used by your project. |
139 | + This speeds up compilation, and reduces the generated output size. |
140 | + It is still experimental, due to historical reasons, but please do try it, |
141 | + and report issues, if compilation breaks with that option for your program. |
142 | + |
143 | + -stats |
144 | + Enable more detailed statistics reporting, while compiling test files. |
145 | + You can use that with `v test` too, for example: |
146 | + v -stats test vlib/ |
147 | + ... will run test_ functions inside all _test.v files inside vlib/ , |
148 | + and will report detailed statistics about how much time each test_ function took, how many |
149 | + assertions were made, how many tests passed/failed and so on. |
150 | + |
151 | + -translated |
152 | + Enable features that are discouraged in regular V code but required for translated V code. |
153 | + |
154 | + -v |
155 | + Enable verbosity in the V compiler while compiling |
156 | + |
157 | + -print-v-files |
158 | + Just print the list of all parsed .v files, then stop processing further. |
159 | + This is useful for running external processing tools: |
160 | + ./v -print-v-files cmd/v | etags -L - |
161 | + ... will generate a TAGS file, that emacs can then use to jump |
162 | + to the definition of functions used by v itself. For vim: |
163 | + ./v -print-v-files cmd/v | ctags -L - |
164 | + ... will generate a simillar tags file, that vi compatible editors can use. |
165 | + NB: an useful, although not entirely accurate regexp based Universal Ctags options file |
166 | + for V is located in `.ctags.d/v.ctags` . If you use https://ctags.io/ , it will be used |
167 | + up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags . |
168 | + |
169 | + -color, -nocolor |
170 | + Force the use of ANSI colors for the V error/warning messages, or disable them completely. |
171 | + By default, the V compiler tries to show its errors/warnings in ANSI color. The heuristic |
172 | + that it uses to detect whether or not to use ANSI colors may not work in all cases. |
173 | + These options allow you to override the default detection. |
174 | + |
175 | + -check |
176 | + Scans, parses, and checks the files without compiling the program. |
177 | + |
178 | + -check-syntax |
179 | + Only scan and parse the files, but then stop. Useful for very quick syntax checks. |
180 | + |
181 | + -show-timings |
182 | + Print a summary about how long each compiler stage took, for example: |
183 | + PARSE: 152ms |
184 | + CHECK: 62ms |
185 | + C GEN: 103ms |
186 | + C tcc: 95ms |
187 | + |
188 | + Related to -show-timings, is the ability to compile a special instrumented |
189 | + v compiler with this command: |
190 | + `v -d time_parsing -d time_checking -d time_cgening -d time_v self` |
191 | + The instrumented version will print detailed timing stats while processing |
192 | + each .v file. |
193 | + |
194 | + -w |
195 | + Hide all warnings. |
196 | + |
197 | + -W |
198 | + Treat *all V warnings* as errors, even in development builds. |
199 | + |
200 | + -Wfatal-errors |
201 | + Unconditionally exit with exit(1) after the first error. |
202 | + Useful for scripts/tooling that calls V. |
203 | + |
204 | + -Wimpure-v |
205 | + Warn about using C. or JS. symbols in plain .v files. |
206 | + These should be moved in .c.v and .js.v . |
207 | + NB: in the future, this will be turned ON by default, |
208 | + and will become an error, after vlib modules are cleaned up. |
209 | + |
210 | +For C-specific build flags, use `v help build-c`. |
211 | +For JS-specific build flags, use `v help build-js`. |
212 | +For Native-specific build flags, use `v help build-native`. |
213 | + |
214 | +See also: |
215 | + `v help run` for documentation regarding `v run`. |
216 |
1 | deleted file mode 100644 |
2 | -Usage: v bump [options] [file1 file2 ...] |
3 | - |
4 | -Description: |
5 | - Bump the semantic version of the v.mod and/or specified files. |
6 | - |
7 | - The first instance of a version number is replaced with the new version. |
8 | - Additionally, the line affected must contain the word "version" in any |
9 | - form of capitalization. For instance, the following lines will be |
10 | - recognized by the heuristic: |
11 | - |
12 | - tool_version = '1.2.1' |
13 | - version: '0.2.42' |
14 | - VERSION = "1.23.8" |
15 | - |
16 | -Examples: |
17 | - Bump the patch version in v.mod if it exists |
18 | - v bump --patch |
19 | - Bump the major version in v.mod and vls.v |
20 | - v bump --major v.mod vls.v |
21 | - Upgrade the minor version in sample.v only |
22 | - v bump --minor sample.v |
23 | - |
24 | - |
25 | -Options: |
26 | - -h, --help Show this help text. |
27 | - -m, --major Bump the major version. |
28 | - -n, --minor Bump the minor version. |
29 | - -p, --patch Bump the patch version. |
30 |
1 | deleted file mode 100644 |
2 | -check-md is a tool to check the passed markdown files for correct ```v ``` code blocks |
3 | -and other style violations like too long lines/links etc... |
4 | - |
5 | -Usage: |
6 | - a) `v check-md [flags] <...files>` - Check the given .md files. |
7 | - b) `v check-md [flags] <...dirs>` - Check *all* files in the given directories. |
8 | - Note: You can also combine files and directories. |
9 | - |
10 | -Flags: |
11 | - -silent Do not show a progress bar. |
12 | - -w, -hide-warnings Do not print warnings, only errors. |
13 | - |
14 | -NB: There are several special keywords, which you can put after the code fences for v. |
15 | -These are: |
16 | - compile - Default, can be omitted. The example will be compiled and formatting is verified. |
17 | - cgen - The example produces C code, which may not be compilable (when external libs are not installed). Formatting is verified. |
18 | - live - Compile hot reload examples with the ´-live´ flag set and verify formatting. |
19 | - ignore - Ignore the example, useful for examples that just use the syntax highlighting |
20 | - failcompile - Known failing compilation. Useful for examples demonstrating compiler errors. |
21 | - okfmt - Should only be formatted, but it can refer to invalid modules, missing functions etc. Useful for partial examples. |
22 | - oksyntax - Should parse, and be formatted, but may not compile. Useful for partial examples. |
23 | - badsyntax - Known bad syntax, it should NOT even parse. |
24 | - wip - Like ignore; a planned feature; easy to search. |
25 | - nofmt - Disable fmt verification for individual code blocks. |
26 |
1 | new file mode 100644 |
2 | +Commonly Used Commands: |
3 | + |
4 | + doc Generates the documentation of a given MODULE, DIRECTORY, or FILE |
5 | + and prints or saves them to its desired format. It can generate HTML, JSON, |
6 | + or Markdown format. |
7 | + |
8 | + fmt Formats the given V source files or recursively formats all files in the directory, |
9 | + then prints their formatted source to stdout. |
10 | + |
11 | + missdoc Prints all V functions in .v files under PATH/, that do not yet have documentation comments. |
12 | + |
13 | + repl Run the V REPL |
14 | + |
15 | + run Equivalent to running `v build` and running the compiled executable |
16 | + |
17 | + test Runs tests in the given FILEs and DIRECTORYs |
18 | + |
19 | + vet Reports suspicious code constructs |
20 | + |
21 | + watch Collects all .v files needed for complication, |
22 | + then when any of the .v source files change, |
23 | + it re-runs the complication |
24 | + |
25 | + where Prints the location of the searched symbols in the scope of the current project |
26 | \ No newline at end of file |
27 |
1 | similarity index 80% |
2 | rename from vlib/v/help/doc.txt |
3 | rename to vlib/v/help/common/doc.txt |
4 | +Generates the documentation of a given MODULE, DIRECTORY, or FILE |
5 | + |
6 | Usage: |
7 | v doc [options] [MODULE / DIRECTORY / FILE] [symbol name] |
8 | |
9 | |
10 | Options: |
11 | -all Includes private and public functions/methods/structs/consts/enums. |
12 | - -f Specifies the output format to be used. Available formats are: |
13 | + -f Specifies the output format to be used. |
14 | + Available formats are: |
15 | md/markdown, json, text, stdout and html/htm |
16 | -h, -help Prints this help text. |
17 | -m Generate docs for modules listed in that folder. |
18 | - -o Specifies the output file/folder path where to store the generated docs. |
19 | - Set it to "stdout" to print the output instead of saving the contents |
20 | - to a file. |
21 | + -o Specifies the output file/folder path where to store the |
22 | + generated docs. |
23 | + Set it to "stdout" to print the output instead of saving |
24 | + the contents to a file. |
25 | -color Forces stdout colorize output. |
26 | -no-color Forces plain text output, without ANSI colors. |
27 | -readme Include README.md to docs if present. |
28 | -no-timestamp Omits the timestamp in the output file. |
29 | |
30 | For HTML mode: |
31 | - -inline-assets Embeds the contents of the CSS and JS assets into the webpage directly. |
32 | + -inline-assets Embeds the contents of the CSS and JS assets into the |
33 | + webpage directly. |
34 | -theme-dir The directory for doc theme template |
35 | |
36 | For plain text mode: |
37 |
1 | new file mode 100644 |
2 | +Read source code from stdin, output formatted file to stdout. |
3 | + |
4 | +Usage: |
5 | + v fmt [options] path_to_source.v [path_to_other_source.v] |
6 | + v fmt [options] path/to/dir [path/to/other_dir] |
7 | + cat source.v | v fmt |
8 | + |
9 | +Formats the given V source files or recursively formats all files in the |
10 | +directory, then prints their formatted source to stdout. |
11 | + |
12 | +Options: |
13 | + -c Check if a file is already formatted. If not, print the |
14 | + filepath and exit with code 2. Compared to -verify it is |
15 | + quicker but has a small trade-off in precision. |
16 | + |
17 | + -diff Display the differences between the formatted source(s) |
18 | + and the original source(s). This will attempt to find a |
19 | + working `diff` command automatically unless you specify one |
20 | + with the VDIFF_TOOL environment variable. |
21 | + |
22 | + -l List files whose formatting differs from vfmt. |
23 | + |
24 | + -w Write result to (source) file(s) instead of to stdout. |
25 | + |
26 | + -backup In combination with `-w`, copy the original `file.v` to a |
27 | + `file.v.bak` backup, before overwriting the original source |
28 | + file. |
29 | + |
30 | + -debug Print the kinds of encountered AST statements/expressions |
31 | + on stderr. |
32 | + |
33 | + -verify Make sure the provided file is already formatted. Useful for |
34 | + checking code contributions in CI for example. |
35 | + |
36 | +Environment Variables: |
37 | + VDIFF_TOOL A command-line tool that will be executed with the original |
38 | + file path and a temporary formatted file path as arguments. |
39 | + e.g. `VDIFF_TOOL=opendiff v fmt -diff path/to/file.v` will |
40 | + become: opendiff path/to/file.v /tmp/v/vfmt_file.v |
41 | + |
42 | + VDIFF_OPTIONS A set of command-line options to be sent immediately after |
43 | + the `diff` command. e.g. VDIFF_OPTIONS="-W 80 -y" |
44 | + v fmt -diff path/to/file.v /tmp/v/vfmt_file.v |
45 |
1 | new file mode 100644 |
2 | +Prints all V functions in .v files under PATH/, that do not yet have |
3 | +documentation comments. |
4 | + |
5 | +Usage: v missdoc [options] PATH [PATH]... |
6 | + |
7 | +Options: |
8 | + -h, --help Show this help text. |
9 | + -t, --tags Also print function tags if any is found. |
10 | + -d, --deprecated Include deprecated functions in output. |
11 | + -p, --private Include private functions in output. |
12 | + --js Include JavaScript functions in output. |
13 | + -n, --no-line-numbers Exclude line numbers in output. |
14 | + -e, --exclude <multiple strings> |
15 | + |
16 | + -r, --relative-paths Use relative paths in output. |
17 | + --verify exit(1) if documentation is missing, 0 otherwise. |
18 | + --diff exit(1) and show difference between two PATH inputs, |
19 | + return 0 otherwise. |
20 | + --version output version information and exit |
21 | + |
22 | + |
23 | + |
24 | +PATH can be both files and directories. |
25 | + |
26 | +The `--verify` flag is useful for use in CI setups for checking if a V project |
27 | +has all it's functions and methods documented: |
28 | +``` |
29 | +v missdoc --verify path/to/code |
30 | +``` |
31 | + |
32 | +The `--diff` flag is useful if your project is not yet fully documented |
33 | +but you want to ensure that no new functions or methods are introduced |
34 | +between commits or branches: |
35 | +``` |
36 | +v missdoc --diff current/code new/code |
37 | +``` |
38 |
1 | similarity index 65% |
2 | rename from vlib/v/help/repl.txt |
3 | rename to vlib/v/help/common/repl.txt |
4 | -Usage: v repl |
5 | - |
6 | This command runs the V REPL. |
7 | + |
8 | +Usage: |
9 | + v repl |
10 |
1 | similarity index 68% |
2 | rename from vlib/v/help/run.txt |
3 | rename to vlib/v/help/common/run.txt |
4 | -Usage: v [build flags] run <file.v|directory|-> [arguments...] |
5 | +Equivalent to running `v build` and running the compiled executable. |
6 | |
7 | -This command is equivalent to running `v build` and running the compiled executable. |
8 | +Usage: |
9 | + v [build flags] run <file.v|directory|-> [arguments...] |
10 | + |
11 | +This command is equivalent to running `v build` and running the compiled |
12 | +executable. |
13 | The executable is passed the arguments as provided in [arguments...]. |
14 | |
15 | If the target is '-', it means that the V source code to build comes from stdin. |
16 | -If the '-o' option is not specified, and the target is '-', a temporary base name for the executable will be used. |
17 | +If the '-o' option is not specified, and the target is '-', a temporary base |
18 | +name for the executable will be used. |
19 | |
20 | The exit status of run will be: |
21 | * `1` if the compilation failed. |
22 |
1 | similarity index 71% |
2 | rename from vlib/v/help/test.txt |
3 | rename to vlib/v/help/common/test.txt |
4 | +Runs test functions in the given FILEs and DIRECTORYs. |
5 | + |
6 | Usage: |
7 | v [-stats] test FILE|DIRECTORY[...] [-run-only GPATTERN1[,...]] |
8 | - Runs test functions in the given FILEs and DIRECTORYs. |
9 | - |
10 | - If '-stats' is given, more statistics about the tests are printed along |
11 | - with a report of passes/failures |
12 | - |
13 | - If you give `-run-only GPATTERN`, then *only* test functions, that do |
14 | - match by name the given glob pattern `GPATTERN` will run. You can separate |
15 | - multiple glob patterns with `,`. |
16 | - If a _test.v file lacks matching functions for all of the glob patterns, it |
17 | - will be ignored completely, so you can do in effect: |
18 | - `v test . -run-only test_your_fn_name` |
19 | - ... and V will run only that test function, no matter how many _test.v |
20 | - files you have, and how many other test_ functions exist in them. |
21 | - NB: glob patterns support `*` which matches anything, and `?`, that |
22 | - matches any single character. They are *NOT* regular expressions however. |
23 | + |
24 | +If '-stats' is given, more statistics about the tests are printed along |
25 | +with a report of passes/failures |
26 | + |
27 | +If you give `-run-only GPATTERN`, then *only* test functions, that do |
28 | +match by name the given glob pattern `GPATTERN` will run. You can separate |
29 | +multiple glob patterns with `,`. |
30 | +If a _test.v file lacks matching functions for all of the glob patterns, it |
31 | +will be ignored completely, so you can do in effect: |
32 | + `v test . -run-only test_your_fn_name` |
33 | +... and V will run only that test function, no matter how many _test.v |
34 | +files you have, and how many other test_ functions exist in them. |
35 | +NB: glob patterns support `*` which matches anything, and `?`, that |
36 | +matches any single character. They are *NOT* regular expressions however. |
37 | |
38 | NB 1: very frequently, when you work on a module you can cd into its folder, |
39 | and then you can perform: |
40 | ``` |
41 | OK [1/2] 164.671 ms vlib/math/stats/stats_test.v |
42 | OK [2/2] 184.842 ms vlib/math/complex/complex_test.v |
43 | ------------------------------------------------------------------------------------------- |
44 | - Summary for all V _test.v files: 2 passed, 2 total. Runtime: 185 ms, on 2 parallel jobs. |
45 | +-------------------------------------------------------------------------------- |
46 | + Summary for all V _test.v files: 2 passed, 2 total. Runtime: 185 ms, on 2 |
47 | + parallel jobs. |
48 | ``` |
49 |
1 | new file mode 100644 |
2 | +Reports suspicious code constructs. |
3 | + |
4 | +Usage: |
5 | + v vet [options] path_to_source.v [path_to_other_source.v] |
6 | + v vet [options] path/to/dir [path/to/other_dir] |
7 | + |
8 | +Options: |
9 | + -W Exit with code 1, even if vet only reported warnings. |
10 | + Useful for checks in CI. |
11 | + |
12 | + -w, -hide-warnings Do not print warnings to stderr. |
13 | + |
14 | + -v, -verbose Enable verbose logging. |
15 | + |
16 | + -p Report private functions with missing documentation too |
17 | + (by default, only the `pub fn` functions will be reported). |
18 | + |
19 | + -force (NB: vet development only!) |
20 | + Do not skip the vet regression tests. |
21 |
1 | new file mode 100644 |
2 | +`v watch` collects all .v files needed for a compilation |
3 | + |
4 | +Usage: |
5 | + v watch [--clear] [--ignore .db] [--add /path/to/a/file.v] [other V options] [run] program.v |
6 | + |
7 | +`v watch` collects all .v files needed for a compilation, then when |
8 | +any of the .v source files change, it re-runs the compilation. |
9 | + |
10 | + |
11 | +Options: |
12 | + -s, --silent Be more silent; do not print the watch timestamp |
13 | + before each re-run. |
14 | + |
15 | + -c, --clear Clears the terminal before each re-run. |
16 | + |
17 | + -a, --add <string> Add more files to be watched. |
18 | + Useful with `v watch -add=feature.v run cmd/v feature.v`, |
19 | + when you want to change *both* the V compiler, |
20 | + and the `feature.v` file. |
21 | + |
22 | + -i, --ignore <string> Ignore files having these extensions. |
23 | + Useful with `v watch -ignore=.db run vwebserver.v`, |
24 | + if your `vwebserver` writes to an sqlite.db file in |
25 | + the same folder. |
26 | + |
27 | + --before <string> A command to execute *before* each re-run. |
28 | + Example: --before 'v wipe-cache' |
29 | + |
30 | + --after <string> A command to execute *after* each re-run. |
31 | + Example: --after 'rm -rf /tmp/v/' |
32 | + |
33 | +You can also customise the timeout, after `v watch` will re-start a monitored |
34 | +program automatically, even if it was not changed by setting the enviroment |
35 | +variable VWATCH_TIMEOUT (in seconds). By default, it is 5 min. (300 seconds). |
36 |
1 | new file mode 100644 |
2 | +Prints the location of the searched symbols in the scope of the current project. |
3 | + |
4 | +Usage: |
5 | + v where symbol_type symbol_name [params] |
6 | + |
7 | +Examples: |
8 | + v where fn main |
9 | + v where struct User |
10 | + v where method Square.area |
11 | + v where fn pow -mod math |
12 | + v where interface callable -dir some -dir other |
13 | + |
14 | + |
15 | +symbol_name can be: |
16 | + fn by default if omit symbol_type (don't omit preferably) |
17 | + method require Struct.method notation |
18 | + struct |
19 | + interface |
20 | + enum |
21 | + const |
22 | + var |
23 | + regexp |
24 | + |
25 | +Options: |
26 | + -mod [mod_name] Restrict to search recursively only within of the given |
27 | + module, if not provided search in entire v scope |
28 | + (use -mod main to search inside all your project). |
29 | + -dir [dir_path] Restrict to search non recursively within the given |
30 | + folder/s, if not provided, search in entire v scope. |
31 | + -vis [visibility] Can be: all, pub, pri (all by default if not provided). |
32 | + Restrict to search symbols with the given visibility. |
33 | + -mut [mutability] Can be: any, yes, not (any by default if not provided). |
34 | + Restrict to search symbols with the given mutability. |
35 | +flags: |
36 | + -h include Header |
37 | + -f Format output (each match uses 3 lines) |
38 | + -v for both above (more Verbose) |
39 | + |
40 | +Note: |
41 | + This tool is inspired by the vdoc tool and its design. However, this is |
42 | + for a more specific use, and can be improved. |
43 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v complete [options] [SUBCMD] QUERY... |
4 | - |
5 | -Description: |
6 | - Tool for bridging auto completion between various shells and v |
7 | - |
8 | -Supported shells: |
9 | - bash, fish, zsh, powershell |
10 | - |
11 | -Examples: |
12 | - Echo auto-detected shell install script to STDOUT |
13 | - v complete |
14 | - Echo specific shell install script to STDOUT |
15 | - v complete setup bash |
16 | - Auto complete input `v tes`*USER PUSHES TAB* (in Bash compatible format). |
17 | - This is not meant for manual invocation - it's called by the relevant |
18 | - shell via the script installed with `v complete` or `v complete setup SHELL`. |
19 | - v complete bash v tes |
20 | - |
21 | -Options: |
22 | - -h, --help Show this help text. |
23 | - |
24 | -SUBCMD: |
25 | - setup : setup [SHELL] - returns the code for completion setup for SHELL |
26 | - bash : [QUERY] - returns Bash compatible completion code with completions computed from QUERY |
27 | - fish : [QUERY] - returns Fish compatible completion code with completions computed from QUERY |
28 | - zsh : [QUERY] - returns ZSH compatible completion code with completions computed from QUERY |
29 | - powershell: [QUERY] - returns PowerShell compatible completion code with completions computed from QUERY |
30 | \ No newline at end of file |
31 |
1 | V is a tool for managing V source code. |
2 | |
3 | Usage: |
4 | - v [options] [command] [arguments] |
5 | + v [options] [command] [arguments] |
6 | |
7 | Examples: |
8 | - v hello.v Compile the file `hello.v` and output it as `hello` or `hello.exe`. |
9 | - v run hello.v Same as above but also run the produced executable immediately after compilation. |
10 | - v -cg run hello.v Same as above, but make debugging easier (in case your program crashes). |
11 | - v crun hello.v Same as above, but do not recompile, if the executable already exists, and is newer than the sources. |
12 | - v -o h.c hello.v Translate `hello.v` to `h.c`. Do not compile further. |
13 | - v -o - hello.v Translate `hello.v` and output the C source code to stdout. Do not compile further. |
14 | - |
15 | - v watch hello.v Re-does the same compilation, when a source code change is detected. |
16 | - The program is only compiled, not run. |
17 | - v watch run hello.v Re-runs the same `hello.v` file, when a source code change is detected. |
18 | + v hello.v Compile the file `hello.v` and output it as |
19 | + `hello` or `hello.exe`. |
20 | + v run hello.v Same as above but also run the produced |
21 | + executable immediately after compilation. |
22 | + v -cg run hello.v Same as above, but make debugging easier |
23 | + (in case your program crashes). |
24 | + v crun hello.v Same as above, but do not recompile, if the |
25 | + executable already exists, and is newer than the |
26 | + sources. |
27 | + v -o h.c hello.v Translate `hello.v` to `h.c`. Do not compile |
28 | + further. |
29 | + v -o - hello.v Translate `hello.v` and output the C source code |
30 | + to stdout. Do not compile further. |
31 | + v watch hello.v Re-does the same compilation, when a source code |
32 | + change is detected. |
33 | + The program is only compiled, not run. |
34 | + v watch run hello.v Re-runs the same `hello.v` file, when a source |
35 | + code change is detected. |
36 | |
37 | V supports the following commands: |
38 | -* New project scaffolding: |
39 | - new Setup the file structure for a V project (in a sub folder). |
40 | - init Setup the file structure for an already existing V project. |
41 | |
42 | -* Ordinary development: |
43 | - run Compile and run a V program. Delete the executable after the run. |
44 | - crun Compile and run a V program without deleting the executable. |
45 | - If you run the same program a second time, without changing the source files, |
46 | - V will just run the executable, without recompilation. Suitable for scripting. |
47 | - test Run all test files in the provided directory. |
48 | - fmt Format the V code provided. |
49 | - vet Report suspicious code constructs. |
50 | - doc Generate the documentation for a V module. |
51 | - vlib-docs Generate and open the documentation of all the vlib modules. |
52 | - repl Run the REPL. |
53 | - watch Re-compile/re-run a source file, each time it is changed. |
54 | - where Find and print the location of current project declarations. |
55 | +* Project Scaffolding Utilities: |
56 | + new Setup the file structure for a V project |
57 | + (in a sub folder). |
58 | + init Setup the file structure for an already existing |
59 | + V project. |
60 | + |
61 | +* Commonly Used Utilities: |
62 | + run Compile and run a V program. Delete the |
63 | + executable after the run. |
64 | + crun Compile and run a V program without deleting the |
65 | + executable. |
66 | + If you run the same program a second time, |
67 | + without changing the source files, |
68 | + V will just run the executable, without |
69 | + recompilation. Suitable for scripting. |
70 | + test Run all test files in the provided directory. |
71 | + fmt Format the V code provided. |
72 | + vet Report suspicious code constructs. |
73 | + doc Generate the documentation for a V module. |
74 | + vlib-docs Generate and open the documentation of all the |
75 | + vlib modules. |
76 | + repl Run the REPL. |
77 | + watch Re-compile/re-run a source file, each time it is |
78 | + changed. |
79 | + where Find and print the location of current project |
80 | + declarations. |
81 | |
82 | -* Installation/self updating: |
83 | - symlink Create a symbolic link for V. |
84 | - up Run the V self-updater. |
85 | - self [-prod] Run the V self-compiler, use -prod to optimize compilation. |
86 | - version Print the version text and exits. |
87 | +* Installation Management Utilities: |
88 | + symlink Create a symbolic link for V. |
89 | + up Run the V self-updater. |
90 | + self [-prod] Run the V self-compiler, use -prod to optimize |
91 | + compilation. |
92 | + version Print the version text and exits. |
93 | |
94 | -* Module/package management: |
95 | - install Install a module from VPM. |
96 | - remove Remove a module that was installed from VPM. |
97 | - search Search for a module from VPM. |
98 | - update Update an installed module from VPM. |
99 | - upgrade Upgrade all the outdated modules. |
100 | - list List all installed modules. |
101 | - outdated List installed modules that need updates. |
102 | - show Display information about a module on vpm |
103 | +* Package Management Utilities: |
104 | + install Install a module from VPM. |
105 | + remove Remove a module that was installed from VPM. |
106 | + search Search for a module from VPM. |
107 | + update Update an installed module from VPM. |
108 | + upgrade Upgrade all the outdated modules. |
109 | + list List all installed modules. |
110 | + outdated List installed modules that need updates. |
111 | + show Display information about a module on vpm |
112 | |
113 | -* Others: |
114 | - doctor Display some useful info about your system to help reporting bugs. |
115 | - translate Translate C code to V. |
116 | - tracev Produce a tracing version of the v compiler. |
117 | - Use `tracev yourfile.v` when the compiler panics. |
118 | - NB: `tracev` is much slower and more verbose than ordinary `v` |
119 | +Use "v help <command>" for more information about a command, example: |
120 | +`v help build`, `v help build-c`, `v help build-native` |
121 | |
122 | -Use "v help <command>" for more information about a command, example: `v help build`, `v help build-c`, `v help build-native` |
123 | Use "v help other" to see less frequently used commands. |
124 | Use "v help topics" to see a list of all known help topics. |
125 | |
126 | Note: Help is required to write more help topics. |
127 | -Only build, new, init, doc, fmt, vet, run, test, watch, search, install, remove, update, bin2v, check-md are properly documented currently. |
128 | +Only build, new, init, doc, fmt, vet, run, test, watch, search, install, remove, |
129 | +update, bin2v, check-md are properly documented currently. |
130 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v fmt [options] path_to_source.v [path_to_other_source.v] |
4 | - v fmt [options] path/to/dir [path/to/other_dir] |
5 | - cat source.v | v fmt |
6 | - Read source code from stdin, output formatted file to stdout. |
7 | - |
8 | -Formats the given V source files or recursively formats all files in the directory, |
9 | -then prints their formatted source to stdout. |
10 | - |
11 | -Options: |
12 | - -c Check if a file is already formatted. If not, print the filepath and exit with code 2. |
13 | - Compared to -verify it is quicker but has a small trade-off in precision. |
14 | - |
15 | - -diff Display the differences between the formatted source(s) and the original source(s). |
16 | - This will attempt to find a working `diff` command automatically unless you |
17 | - specify one with the VDIFF_TOOL environment variable. |
18 | - |
19 | - -l List files whose formatting differs from vfmt. |
20 | - |
21 | - -w Write result to (source) file(s) instead of to stdout. |
22 | - |
23 | - -backup In combination with `-w`, copy the original `file.v` to a `file.v.bak` backup, |
24 | - before overwriting the original source file. |
25 | - |
26 | - -debug Print the kinds of encountered AST statements/expressions on stderr. |
27 | - |
28 | - -verify Make sure the provided file is already formatted. Useful for checking code contributions |
29 | - in CI for example. |
30 | - |
31 | -Environment Variables: |
32 | - VDIFF_TOOL A command-line tool that will be executed with the original file path |
33 | - and a temporary formatted file path as arguments. e.g. |
34 | - `VDIFF_TOOL=opendiff v fmt -diff path/to/file.v` will become: |
35 | - opendiff path/to/file.v /tmp/v/vfmt_file.v |
36 | - |
37 | - VDIFF_OPTIONS A set of command-line options to be sent immediately after the |
38 | - `diff` command. e.g. |
39 | - VDIFF_OPTIONS="-W 80 -y" v fmt -diff path/to/file.v /tmp/v/vfmt_file.v |
40 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v gret [options] PATH [PATH] |
4 | - |
5 | -Description: |
6 | - Dump and/or compare rendered frames of graphical apps |
7 | - both external and `gg` based apps is supported. |
8 | - |
9 | -Examples: |
10 | - Generate screenshots to `/tmp/test` |
11 | - v gret /tmp/test |
12 | - Generate and compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst` |
13 | - v gret /tmp/src /tmp/dst |
14 | - Compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst` |
15 | - v gret --compare-only /tmp/src /tmp/dst |
16 | - |
17 | -Options: |
18 | - -h, --help Show this help text. |
19 | - -v, --verbose Be verbose about the tool's progress. |
20 | - -c, --compare-only Don't generate screenshots - only compare input directories |
21 | - -r, --root-path Root path of the comparison |
22 | - -t, --toml-config Path or string with TOML configuration |
23 | - |
24 | - --version output version information and exit |
25 |
1 | unknown_topic = '`v help`: unknown help topic provided. Use `v help` for usage information.' |
2 | ) |
3 | |
4 | +// print_and_exit Prints the help topic and exits |
5 | pub fn print_and_exit(topic string) { |
6 | vexe := pref.vexe_path() |
7 | vroot := os.dir(vexe) |
8 | eprintln(help.unknown_topic) |
9 | exit(1) |
10 | } |
11 | - // `init` has the same help topic as `new` |
12 | - name := if topic == 'init' { 'new' } else { topic } |
13 | + |
14 | + mut path_to := topic |
15 | + mut topics := os.walk_ext(topicdir, '.txt') |
16 | + mut items := [][]string{} |
17 | + |
18 | + mut item_rev := []string{} |
19 | + mut delim := '' |
20 | + |
21 | + // Getting the directory, splitting at `/`, trimming to only indexes 0 and 1, |
22 | + // and reversing that into the items array |
23 | + for mut item in topics { |
24 | + $if windows { |
25 | + delim = '\\' |
26 | + } $else { |
27 | + delim = '/' |
28 | + } |
29 | + item_rev = item.split(delim).reverse() |
30 | + item_rev.trim(2) |
31 | + items << item_rev.reverse() |
32 | + } |
33 | + |
34 | + // Getting the path to the help topic text file |
35 | + for cmds in items { |
36 | + if '${topic}.txt' in cmds { |
37 | + path_to = '${cmds[0]}/${cmds[1].replace('.txt', '')}' |
38 | + break |
39 | + } |
40 | + } |
41 | + |
42 | + topic_dir := if topic == 'default' { |
43 | + os.join_path(topicdir, 'default.txt') |
44 | + } else { |
45 | + os.join_path(topicdir, '${path_to}.txt') |
46 | + } |
47 | + |
48 | if topic == 'topics' { |
49 | println(known_topics(topicdir)) |
50 | exit(0) |
51 | } |
52 | - target_topic := os.join_path(topicdir, '${name}.txt') |
53 | - content := os.read_file(target_topic) or { |
54 | + |
55 | + content := os.read_file(topic_dir) or { |
56 | eprintln(help.unknown_topic) |
57 | eprintln(known_topics(topicdir)) |
58 | exit(1) |
59 | exit(0) |
60 | } |
61 | |
62 | +// known_topics Getting topics known to V |
63 | fn known_topics(topicdir string) string { |
64 | mut res := []string{} |
65 | res << 'Known help topics: ' |
66 | - topic_files := os.glob(os.join_path(topicdir, '*.txt')) or { [] } |
67 | - mut topics := topic_files.map(os.file_name(it).replace('.txt', '')) |
68 | + |
69 | + mut topics := os.walk_ext(topicdir, '.txt').map(os.file_name(it).replace('.txt', '')) |
70 | topics.sort() |
71 | res << topics.join(', ') |
72 | res << '.' |
73 | - return res.join('') |
74 | + return res.join('').replace('default, ', '') |
75 | } |
76 |
1 | assert res.exit_code == 0 |
2 | assert res.output.starts_with('V is a tool for managing V source code.') |
3 | } |
4 | + |
5 | +fn test_all_help() { |
6 | + vroot := os.dir(vexe) |
7 | + topicdir := os.join_path(vroot, 'vlib', 'v', 'help') |
8 | + mut topics := os.walk_ext(topicdir, '.txt') |
9 | + |
10 | + mut items := []string{} |
11 | + mut delim := '' |
12 | + |
13 | + for mut item in topics { |
14 | + $if windows { |
15 | + delim = '\\' |
16 | + } $else { |
17 | + delim = '/' |
18 | + } |
19 | + mut item_rev := item.replace('.txt', '').split(delim).reverse() |
20 | + item_rev.trim(2) |
21 | + items << item_rev.reverse() |
22 | + } |
23 | + |
24 | + for topic in items { |
25 | + res := os.execute('${os.quoted_path(vexe)} help ${topic}') |
26 | + |
27 | + if topic == 'help' { |
28 | + continue |
29 | + } |
30 | + |
31 | + assert res.exit_code == 0 |
32 | + assert res.output != '' |
33 | + } |
34 | +} |
35 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v init |
4 | - |
5 | -Setup the file structure for an already existing V project. |
6 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v install [PACKAGE...] |
4 | - Installs each PACKAGE. |
5 | - |
6 | - If no PACKAGEs, the packages listed in the `v.mod` file are installed instead. |
7 | - |
8 | -Options: |
9 | - --vpm - [Default] Install from vpm |
10 | - --git - Install from git repository url |
11 | - --hg - Install from mercurial repository url |
12 | - --once - Only install the package if it was not previously installed |
13 | - -help - Show usage info. |
14 | - -v - Print more details about the performed operation. |
15 | - -server-url - When doing network operations, use this vpm server. Can be given multiple times. |
16 |
1 | new file mode 100644 |
2 | +Installation Management Utilities: |
3 | + |
4 | + self Rebuild V with the passed options. |
5 | + |
6 | + symlink Add a symlink for the V compiler executable. |
7 | + |
8 | + up Update the V compiler to the latest version from https://github.com/vlang/v. |
9 | + |
10 | + version Print the version of V installed |
11 | \ No newline at end of file |
12 |
1 | new file mode 100644 |
2 | +Rebuild V with the passed options. |
3 | + |
4 | +Usage: |
5 | + v self |
6 | + |
7 | +Options: |
8 | + All other options are passed to the build command. (e.g. -prod) |
9 |
1 | similarity index 51% |
2 | rename from vlib/v/help/symlink.txt |
3 | rename to vlib/v/help/installation/symlink.txt |
4 | -Usage: v symlink [OPTIONS] |
5 | - |
6 | This command adds a symlink for the V compiler executable. |
7 | |
8 | -Note that on Unix systems this command requires write permissions to /usr/local/bin to work. |
9 | +Usage: |
10 | + v symlink [OPTIONS] |
11 | + |
12 | +Note that on Unix systems this command requires write permissions to |
13 | +/usr/local/bin to work. |
14 | |
15 | For GitHub Actions, the option -githubci needs to be specified. |
16 | \ No newline at end of file |
17 |
1 | new file mode 100644 |
2 | +Update the V compiler to the latest version from https://github.com/vlang/v. |
3 | + |
4 | +Usage: |
5 | + v up |
6 | + |
7 | +Options: |
8 | + -v Print more details about the update. |
9 | + -prod Compile the updated V with the -prod flag. |
10 |
1 | similarity index 64% |
2 | rename from vlib/v/help/version.txt |
3 | rename to vlib/v/help/installation/version.txt |
4 | -Usage: v version |
5 | - |
6 | Print the version of V installed. |
7 | + |
8 | +Usage: |
9 | + v version |
10 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v ls [options] [ARGS] |
4 | - |
5 | -Description: |
6 | - Installs, updates, and executes the V language server program |
7 | - |
8 | -Options: |
9 | - --json Print the output as JSON. |
10 | - --silent Disables output printing. |
11 | - --install Installs the language server. You may also use this flag to re-download or force update your existing installation. |
12 | - --update Updates the installed language server. |
13 | - --check Checks if the language server is installed. |
14 | - --force Force install or update the language server. |
15 | - --source Clone and build the language server from source. |
16 | - --ls Pass the arguments to the language server. |
17 | - -p, --path <string> Path to the language server executable. |
18 | - -h, --help Show this updater's help text. To show the help text for the language server's, pass the `--ls` flag before it. |
19 | - --version output version information and exit |
20 | \ No newline at end of file |
21 |
1 | deleted file mode 100644 |
2 | -v missdoc 0.1.0 |
3 | ------------------------------------------------ |
4 | -Usage: v missdoc [options] PATH [PATH]... |
5 | - |
6 | -Description: Prints all V functions in .v files under PATH/, that do not yet have documentation comments. |
7 | - |
8 | -Options: |
9 | - -h, --help Show this help text. |
10 | - -t, --tags Also print function tags if any is found. |
11 | - -d, --deprecated Include deprecated functions in output. |
12 | - -p, --private Include private functions in output. |
13 | - --js Include JavaScript functions in output. |
14 | - -n, --no-line-numbers Exclude line numbers in output. |
15 | - -e, --exclude <multiple strings> |
16 | - |
17 | - -r, --relative-paths Use relative paths in output. |
18 | - --verify exit(1) if documentation is missing, 0 otherwise. |
19 | - --diff exit(1) and show difference between two PATH inputs, return 0 otherwise. |
20 | - --version output version information and exit |
21 | - |
22 | ------------------------------------------------ |
23 | - |
24 | -PATH can be both files and directories. |
25 | - |
26 | -The `--verify` flag is useful for use in CI setups for checking if a V project |
27 | -has all it's functions and methods documented: |
28 | -``` |
29 | -v missdoc --verify path/to/code |
30 | -``` |
31 | - |
32 | -The `--diff` flag is useful if your project is not yet fully documented |
33 | -but you want to ensure that no new functions or methods are introduced |
34 | -between commits or branches: |
35 | -``` |
36 | -v missdoc --diff current/code new/code |
37 | -``` |
38 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v new [NAME] [DESCRIPTION] |
4 | - Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World" |
5 | - file, and performs 'git init' (if git is installed on the system). |
6 | - |
7 | - If NAME is given, the project will be setup in a new directory with that |
8 | - name, and that name will be added to the 'v.mod' file. If no name is given, |
9 | - the user will be prompted for a name. |
10 | - |
11 | - If DESCRIPTION is given, the 'v.mod' file is updated with said description. |
12 | - |
13 | - v init |
14 | - Sets up a V project within the current directory. |
15 | - |
16 | - If no '.v' file exists, then will create a 'main.v' file. |
17 | - If no 'v.mod' file exists, one will be created. |
18 | - If the current directory is not already controlled with 'git', will perform |
19 | - 'git init' (if git is installed on the system). |
20 |
1 | deleted file mode 100644 |
2 | -These are utility commands that you can also launch through v, |
3 | -but which are used less frequently by users: |
4 | - |
5 | - ast Generate a json representation of the AST for a given .v file. |
6 | - |
7 | - bug Post an issue on the V's issue tracker, including the failing program, and some diagnostic information. |
8 | - |
9 | - bin2v Convert a binary file to a v source file, |
10 | - that can be later embedded in a module or program. |
11 | - |
12 | - build-examples Test if all examples can be built. |
13 | - build-tools Test if all tools can be built. |
14 | - build-vbinaries Test if V can be built with different configuration. |
15 | - |
16 | - check-md Check that V examples in markdown files are formatted and can compile. |
17 | - |
18 | - setup-freetype Setup thirdparty freetype on Windows. |
19 | - |
20 | - test-all Run most checks, that the CI does locally. |
21 | - It may take over 2 minutes, and it needs internet connectivity too, |
22 | - because it tries to also verify that `v install` works. |
23 | - |
24 | - test-fmt Test if all files in the current directory are formatted properly. |
25 | - |
26 | - test-parser Test that the V parser works with the given files, as if |
27 | - they were typed by a human programmer, one character at a time. |
28 | - NB: *very slow* for longer files (tens of seconds for 1KB .v file). |
29 | - Mainly useful as a parser bug finder for the V Language Server project. |
30 | - |
31 | - test-self Test if V is working properly by running all tests, including the compiler ones. |
32 | - NB: this can 1-2 minutes to run. |
33 | - |
34 | - wipe-cache Remove the V cache folder. Useful for cleaning the cache, and guaranteeing a clean build. |
35 |
1 | new file mode 100644 |
2 | +Dump a JSON representation of the V AST for a given .v or .vsh file. |
3 | + |
4 | +Usage: |
5 | + v ast demo.v generate demo.json file. |
6 | + v ast -w demo.v generate demo.json file, and watch for changes. |
7 | + v ast -c demo.v generate demo.json *and* a demo.c file, and watch for |
8 | + changes. |
9 | + v ast -p demo.v print the json output to stdout. |
10 | + |
11 | +Dump a JSON representation of the V AST for a given .v or .vsh file. |
12 | +By default, `v ast` will save the JSON to a .json file, named after the .v file. |
13 | +Pass -p to see it instead. |
14 | + |
15 | +The arguments should be at least 1 in number. |
16 | + |
17 | +Options: |
18 | + -w, --watch Watch a .v file for changes, rewrite the .json file, |
19 | + when a change is detected |
20 | + -p, --print Print the AST to stdout |
21 | + -c, --compile Watch the .v file for changes, rewrite the .json |
22 | + File, *AND* generate a .c file too on any change |
23 | + -t, --terse terse output, only with tree node names |
24 | + (AST structure), no details |
25 | + --hide <multiple strings> Hide the specified fields. You can give several, by |
26 | + separating them with `,` |
27 | + -h, --help Display this help and exit |
28 | + --version Output version information and exit |
29 |
1 | new file mode 100644 |
2 | +Converts a list of arbitrary files into a single v module file. |
3 | + |
4 | +Usage: |
5 | + v bin2v [options] FILE[...] |
6 | + |
7 | +You can use this tool to embed binary files, like pictures or fonts inside |
8 | +the executable of a v program, such that it would not need access to external |
9 | +resources during runtime, and it would be as self-contained as possible. |
10 | + |
11 | +Options: |
12 | + -h, --help Show this help screen. |
13 | + -m, --module <string> Name of the generated module. |
14 | + -p, --prefix <string> A prefix put before each resource name. |
15 | + -w, --write <string> Write directly to a file with the given name. |
16 |
1 | new file mode 100644 |
2 | +Open a prefilled bug report on GitHub. |
3 | + |
4 | +Usage: |
5 | + v bug [options] FILE |
6 | + |
7 | +Options: |
8 | + -v Enable verbosity while gathering various information |
9 | + -y Force the submission of the issue, even if an error occured |
10 |
1 | new file mode 100644 |
2 | +Bump the semantic version of the v.mod and/or specified files. |
3 | + |
4 | +Usage: |
5 | + v bump [options] [file1 file2 ...] |
6 | + |
7 | +The first instance of a version number is replaced with the new version. |
8 | +Additionally, the line affected must contain the word "version" in any |
9 | +form of capitalization. For instance, the following lines will be |
10 | +recognized by the heuristic: |
11 | + |
12 | +tool_version = '1.2.1' |
13 | +version: '0.2.42' |
14 | +VERSION = "1.23.8" |
15 | + |
16 | +Examples: |
17 | + Bump the patch version in v.mod if it exists |
18 | + v bump --patch |
19 | + Bump the major version in v.mod and vls.v |
20 | + v bump --major v.mod vls.v |
21 | + Upgrade the minor version in sample.v only |
22 | + v bump --minor sample.v |
23 | + |
24 | + |
25 | +Options: |
26 | + -h, --help Show this help text. |
27 | + -m, --major Bump the major version. |
28 | + -n, --minor Bump the minor version. |
29 | + -p, --patch Bump the patch version. |
30 |
1 | new file mode 100644 |
2 | +check-md is a tool to check the passed markdown files for correct ```v ``` |
3 | +code blocks and other style violations like too long lines/links etc... |
4 | + |
5 | +Usage: |
6 | + v check-md [flags] <...files> - Check the given .md files. |
7 | + v check-md [flags] <...dirs> - Check *all* files in the given directories. |
8 | + Note: You can also combine files and directories. |
9 | + |
10 | +Options: |
11 | + -silent Do not show a progress bar. |
12 | + -w, -hide-warnings Do not print warnings, only errors. |
13 | + |
14 | +NB: There are several special keywords, which you can put after the code fences |
15 | +for v. |
16 | +These are: |
17 | + compile Default, can be omitted. The example will be compiled |
18 | + and formatting is verified. |
19 | + cgen The example produces C code, which may not be |
20 | + compilable (when external libs are not installed). |
21 | + Formatting is verified. |
22 | + live Compile hot reload examples with the ´-live´ flag set |
23 | + and verify formatting. |
24 | + ignore Ignore the example, useful for examples that just use |
25 | + the syntax highlighting |
26 | + failcompile Known failing compilation. Useful for examples |
27 | + demonstrating compiler errors. |
28 | + okfmt Should only be formatted, but it can refer to invalid |
29 | + modules, missing functions etc. Useful for partial |
30 | + examples. |
31 | + oksyntax Should parse, and be formatted, but may not compile. |
32 | + Useful for partial examples. |
33 | + badsyntax Known bad syntax, it should NOT even parse. |
34 | + wip Like ignore; a planned feature; easy to search. |
35 | + nofmt Disable fmt verification for individual code blocks. |
36 |
1 | new file mode 100644 |
2 | +Tool for bridging autocompletion between various shells and v |
3 | + |
4 | +Usage: |
5 | + v complete [options] [SUBCMD] QUERY... |
6 | + |
7 | +Supported shells: |
8 | + bash, fish, zsh, powershell |
9 | + |
10 | +Examples: |
11 | + Echo auto-detected shell install script to STDOUT |
12 | + v complete |
13 | + Echo specific shell install script to STDOUT |
14 | + v complete setup bash |
15 | + Auto complete input `v tes`*USER PUSHES TAB* (in Bash compatible format). |
16 | + This is not meant for manual invocation - it's called by the relevant |
17 | + shell via the script installed with `v complete` or `v complete setup SHELL`. |
18 | + v complete bash v tes |
19 | + |
20 | +Options: |
21 | + -h, --help Show this help text. |
22 | + |
23 | +SUBCMD: |
24 | + setup : setup [SHELL] Returns the code for completion setup for SHELL |
25 | + bash : [QUERY] Returns Bash compatible completion code with |
26 | + completions computed from QUERY |
27 | + fish : [QUERY] Returns Fish compatible completion code with |
28 | + completions computed from QUERY |
29 | + zsh : [QUERY] Returns ZSH compatible completion code with |
30 | + completions computed from QUERY |
31 | + powershell: [QUERY] Returns PowerShell compatible completion code with |
32 | + completions computed from QUERY |
33 | \ No newline at end of file |
34 |
1 | similarity index 79% |
2 | rename from vlib/v/help/doctor.txt |
3 | rename to vlib/v/help/other/doctor.txt |
4 | -Usage: v doctor |
5 | - |
6 | Display some useful info about your system necessary for bug reports. |
7 | + |
8 | +Usage: |
9 | + v doctor |
10 |
1 | new file mode 100644 |
2 | +Dump and/or compare rendered frames of graphical apps; |
3 | +both, external and `gg` based apps are supported. |
4 | + |
5 | +Usage: |
6 | + v gret [options] PATH [PATH] |
7 | + |
8 | +Examples: |
9 | + Generate screenshots to `/tmp/test` |
10 | + v gret /tmp/test |
11 | + Generate and compare screenshots in `/tmp/src` to existing screenshots in |
12 | + `/tmp/dst` |
13 | + v gret /tmp/src /tmp/dst |
14 | + Compare screenshots in `/tmp/src` to existing screenshots in `/tmp/dst` |
15 | + v gret --compare-only /tmp/src /tmp/dst |
16 | + |
17 | +Options: |
18 | + -h, --help Show this help text. |
19 | + -v, --verbose Be verbose about the tool's progress. |
20 | + -c, --compare-only Don't generate screenshots - only compare input |
21 | + directories |
22 | + -r, --root-path Root path of the comparison |
23 | + -t, --toml-config Path or string with TOML configuration |
24 | + |
25 | + --version Output version information and exit |
26 |
1 | new file mode 100644 |
2 | +Installs, updates, and executes the V language server program |
3 | + |
4 | +Usage: |
5 | + v ls [options] [ARGS] |
6 | + |
7 | +Options: |
8 | + --json Print the output as JSON. |
9 | + --silent Disables output printing. |
10 | + --install Installs the language server. You may also use this flag |
11 | + to re-download or force update your existing |
12 | + installation. |
13 | + --update Updates the installed language server. |
14 | + --check Checks if the language server is installed. |
15 | + --force Force install or update the language server. |
16 | + --source Clone and build the language server from source. |
17 | + --ls Pass the arguments to the language server. |
18 | + -p, --path <string> Path to the language server executable. |
19 | + -h, --help Show this updater's help text. To show the help text for |
20 | + the language server's, pass the `--ls` flag before it. |
21 | + --version output version information and exit |
22 | \ No newline at end of file |
23 |
1 | new file mode 100644 |
2 | +Other less frequently used commands supported by V include: |
3 | + |
4 | + ast Generate a json representation of the AST for a given .v file. |
5 | + |
6 | + bug Post an issue on the V's issue tracker, including the failing program, and some diagnostic information. |
7 | + |
8 | + bin2v Convert a binary file to a v source file, |
9 | + that can be later embedded in a module or program. |
10 | + |
11 | + build-examples Test if all examples can be built. |
12 | + |
13 | + build-tools Test if all tools can be built. |
14 | + |
15 | + build-vbinaries Test if V can be built with different configuration. |
16 | + |
17 | + check-md Check that V examples in markdown files are formatted and can compile. |
18 | + |
19 | + doctor Display some useful info about your system to help reporting bugs. |
20 | + |
21 | + setup-freetype Setup thirdparty freetype on Windows. |
22 | + |
23 | + translate Translate C code to V. |
24 | + |
25 | + tracev Produce a tracing version of the v compiler. |
26 | + Use `tracev yourfile.v` when the compiler panics. |
27 | + NB: `tracev` is much slower and more verbose than ordinary `v` |
28 | + |
29 | + |
30 | + test-all Run most checks, that the CI does locally. |
31 | + It may take over 2 minutes, and it needs internet connectivity too, |
32 | + because it tries to also verify that `v install` works. |
33 | + |
34 | + test-fmt Test if all files in the current directory are formatted properly. |
35 | + |
36 | + test-parser Test that the V parser works with the given files, as if |
37 | + they were typed by a human programmer, one character at a time. |
38 | + NB: *very slow* for longer files (tens of seconds for 1KB .v file). |
39 | + Mainly useful as a parser bug finder for the V Language Server project. |
40 | + |
41 | + test-self Test if V is working properly by running all tests, including the compiler ones. |
42 | + NB: this can 1-2 minutes to run. |
43 | + |
44 | + wipe-cache Remove the V cache folder. Useful for cleaning the cache, and guaranteeing a clean build. |
45 | \ No newline at end of file |
46 |
1 | new file mode 100644 |
2 | +Compile shaders in sokol's annotated GLSL format |
3 | + |
4 | +Usage: |
5 | + v shader [options] [DIRECTORY / FILE] |
6 | + |
7 | +Compile shaders in sokol's annotated GLSL format to C headers for use with |
8 | +sokol based apps. Sokol based apps include all apps using V's gg module. |
9 | + |
10 | +Examples: |
11 | + v shader . |
12 | + v shader examples/sokol/02_cubes_glsl/cube_glsl.glsl |
13 | + |
14 | +Options: |
15 | + -h, --help Show this help text. |
16 | + -v, --verbose Be verbose about the tools progress. |
17 | + -u, --force-update Force update of the sokol-shdc tool. |
18 | + -l, --slang <multiple strings> Shader dialects to generate code for. |
19 | + Default is all. |
20 | + Available: 'glsl330', 'glsl100', |
21 | + 'glsl300es', 'hlsl4', 'hlsl5', |
22 | + 'metal_macos', 'metal_ios', 'metal_sim', |
23 | + 'wgpu' |
24 | + |
25 |
1 | similarity index 71% |
2 | rename from vlib/v/help/tracev.txt |
3 | rename to vlib/v/help/other/tracev.txt |
4 | -Usage: v tracev |
5 | - |
6 | Produce a tracing version of the V compiler. |
7 | + |
8 | +Usage: |
9 | + v tracev |
10 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v remove [PACKAGE...] |
4 | - Removes all listed PACKAGEs. |
5 | - If no PACKAGE is provided, removes ALL installed packages. |
6 | - |
7 | -Options: |
8 | - -help - Show usage info. |
9 | - -v - Print more details about the performed operation. |
10 | - -server-url - When doing network operations, use this vpm server. Can be given multiple times. |
11 |
1 | new file mode 100644 |
2 | +Sets up a V project within the current directory. |
3 | + |
4 | +Usage: |
5 | + v init |
6 | + |
7 | +If no '.v' file exists, then will create a 'main.v' file. |
8 | +If no 'v.mod' file exists, one will be created. |
9 | +If the current directory is not already controlled with 'git', will perform |
10 | +'git init' (if git is installed on the system). |
11 |
1 | new file mode 100644 |
2 | +Sets up a new V project |
3 | + |
4 | +Usage: |
5 | + v new [NAME] [DESCRIPTION] |
6 | + |
7 | +Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World" |
8 | +file, and performs 'git init' (if git is installed on the system). |
9 | + |
10 | +If NAME is given, the project will be setup in a new directory with that |
11 | +name, and that name will be added to the 'v.mod' file. If no name is given, |
12 | +the user will be prompted for a name. |
13 | + |
14 | +If DESCRIPTION is given, the 'v.mod' file is updated with said description. |
15 | \ No newline at end of file |
16 |
1 | new file mode 100644 |
2 | +Project Scaffolding Utilities: |
3 | + |
4 | + init Sets up the file structure for an already existing V project. |
5 | + |
6 | + new Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World" |
7 | + file, and performs 'git init' (if git is installed on the system). |
8 | \ No newline at end of file |
9 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v search KEYWORD[...] |
4 | - Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the |
5 | - details |
6 | - |
7 | -Options: |
8 | - -help - Show usage info. |
9 | - -v - Print more details about the performed operation. |
10 | - -server-url - When doing network operations, use this vpm server. Can be |
11 | - given multiple times. |
12 |
1 | deleted file mode 100644 |
2 | -Usage: v self |
3 | - |
4 | -Rebuild V with the passed options. |
5 | - |
6 | -Options: All other options are passed to the build command. (e.g. -prod) |
7 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v shader [options] [DIRECTORY / FILE] |
4 | - |
5 | -Examples: |
6 | - v shader . |
7 | - v shader examples/sokol/02_cubes_glsl/cube_glsl.glsl |
8 | - |
9 | - Compile shaders in sokol's annotated GLSL format to C headers for use with sokol based apps. |
10 | - Sokol based apps include all apps using V's gg module. |
11 | - |
12 | -Options: |
13 | - -h, --help Show this help text. |
14 | - -v, --verbose Be verbose about the tools progress. |
15 | - -u, --force-update Force update of the sokol-shdc tool. |
16 | - -l, --slang <multiple strings> Shader dialects to generate code for. Default is all. |
17 | - Available: 'glsl330', 'glsl100', 'glsl300es', 'hlsl4', 'hlsl5', 'metal_macos', 'metal_ios', 'metal_sim', 'wgpu' |
18 | - |
19 |
1 | deleted file mode 100644 |
2 | -Usage: v up |
3 | - |
4 | -Update the V compiler to the latest version from https://github.com/vlang/v. |
5 | - |
6 | -Options: |
7 | - -v - Print more details about the update. |
8 | - -prod - Compile the updated V with the -prod flag. |
9 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v update [PACKAGE]... |
4 | - Updates each PACKAGE. |
5 | - |
6 | - With no PACKAGE, ALL installed packages are updated to their latest versions. |
7 | - |
8 | -Options: |
9 | - -help - Show usage info. |
10 | - -v - Print more details about the update. |
11 | - -server-url - When doing network operations, use this vpm server. Can be given multiple times. |
12 |
1 | deleted file mode 100644 |
2 | -Usage: v upgrade |
3 | - |
4 | -Upgrade all outdated modules. |
5 | - |
6 | -Options: |
7 | - -help - Show usage info. |
8 | - -v - Print more details about the upgrade. |
9 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v vet [options] path_to_source.v [path_to_other_source.v] |
4 | - v vet [options] path/to/dir [path/to/other_dir] |
5 | - |
6 | -Reports suspicious code constructs. |
7 | - |
8 | -Options: |
9 | - -W |
10 | - Exit with code 1, even if vet only reported warnings. Useful for checks in CI. |
11 | - |
12 | - -w, -hide-warnings |
13 | - Do not print warnings to stderr. |
14 | - |
15 | - -v, -verbose |
16 | - Enable verbose logging. |
17 | - |
18 | - -p |
19 | - Report private functions with missing documentation too (by default, only the `pub fn` functions will be reported). |
20 | - |
21 | - -force |
22 | - (NB: vet development only!) Do not skip the vet regression tests. |
23 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - a) v install [PACKAGE...] |
4 | - b) v update [PACKAGE...] |
5 | - c) v remove [PACKAGE...] |
6 | - d) v search KEYWORD[...] |
7 | - e) v show [PACKAGE...] |
8 | - |
9 | - You can also pass -h or --help after each vpm command from the above, to see more details about it. |
10 |
1 | new file mode 100644 |
2 | +Installs each PACKAGE. |
3 | + |
4 | +Usage: |
5 | + v install [PACKAGE...] |
6 | + |
7 | +If no PACKAGEs, the packages listed in the `v.mod` file are installed instead. |
8 | + |
9 | +Options: |
10 | + --vpm [Default] Install from vpm |
11 | + --git Install from git repository url |
12 | + --hg Install from mercurial repository url |
13 | + --help, -h Prints the help menu |
14 | + --once Only install the package if it was not previously installed |
15 | + -v Print more details about the performed operation. |
16 | + -server-url When doing network operations, use this vpm server. |
17 | + Can be given multiple times. |
18 |
1 | similarity index 65% |
2 | rename from vlib/v/help/list.txt |
3 | rename to vlib/v/help/vpm/list.txt |
4 | -Usage: v list |
5 | - |
6 | List all installed packages. |
7 | + |
8 | +Usage: |
9 | + v list |
10 |
1 | similarity index 70% |
2 | rename from vlib/v/help/outdated.txt |
3 | rename to vlib/v/help/vpm/outdated.txt |
4 | -Usage: v outdated |
5 | - |
6 | List all installed modules that need updates. |
7 | + |
8 | +Usage: |
9 | + v outdated |
10 |
1 | new file mode 100644 |
2 | +Removes all listed PACKAGEs. |
3 | + |
4 | +Usage: |
5 | + v remove [PACKAGE...] |
6 | + |
7 | +If no PACKAGE is provided, removes ALL installed packages. |
8 | + |
9 | +Options: |
10 | + -v Print more details about the performed operation. |
11 | + -server-url When doing network operations, use this vpm server. |
12 | + Can be given multiple times. |
13 |
1 | new file mode 100644 |
2 | +Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the details |
3 | + |
4 | +Usage: |
5 | + v search KEYWORD[...] |
6 | + |
7 | +Options: |
8 | + -v Print more details about the performed operation. |
9 | + -server-url When doing network operations, use this vpm server. Can be |
10 | + given multiple times. |
11 |
1 | similarity index 73% |
2 | rename from vlib/v/help/show.txt |
3 | rename to vlib/v/help/vpm/show.txt |
4 | -Usage: v show |
5 | - |
6 | Display information about a module on vpm. |
7 | + |
8 | +Usage: |
9 | + v show |
10 |
1 | new file mode 100644 |
2 | +Updates each PACKAGE. |
3 | + |
4 | +Usage: |
5 | + v update [PACKAGE]... |
6 | + |
7 | +With no PACKAGE, ALL installed packages are updated to their latest versions. |
8 | + |
9 | +Options: |
10 | + -v Print more details about the update. |
11 | + -server-url When doing network operations, use this vpm server. |
12 | + Can be given multiple times. |
13 |
1 | new file mode 100644 |
2 | +Upgrade all outdated modules. |
3 | + |
4 | +Usage: |
5 | + v upgrade |
6 | + |
7 | +Options: |
8 | + -v Print more details about the upgrade. |
9 |
1 | new file mode 100644 |
2 | +Package Management Utilities: |
3 | + |
4 | + install Installs each PACKAGE. |
5 | + |
6 | + list List all installed packages. |
7 | + |
8 | + outdated List all installed modules that need updates. |
9 | + |
10 | + remove Removes all listed PACKAGEs. |
11 | + |
12 | + search Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the details |
13 | + |
14 | + show Display information about a module on vpm. |
15 | + |
16 | + update Updates each PACKAGE. |
17 | + |
18 | + upgrade Upgrade all outdated modules. |
19 | \ No newline at end of file |
20 |
1 | deleted file mode 100644 |
2 | -v watch [--clear] [--ignore .db] [--add /path/to/a/file.v] [other V options] [run] program.v |
3 | - |
4 | -Description: |
5 | -`v watch` collects all .v files needed for a compilation, then when |
6 | -any of the .v source files changes, it re-runs the compilation. |
7 | - |
8 | -Options: |
9 | - -s, --silent Be more silent; do not print the watch timestamp before each re-run. |
10 | - |
11 | - -c, --clear Clears the terminal before each re-run. |
12 | - |
13 | - -a, --add <string> Add more files to be watched. |
14 | - Useful with `v watch -add=feature.v run cmd/v feature.v`, |
15 | - when you want to change *both* the V compiler, |
16 | - and the `feature.v` file. |
17 | - |
18 | - -i, --ignore <string> Ignore files having these extensions. |
19 | - Useful with `v watch -ignore=.db run vwebserver.v`, |
20 | - if your `vwebserver` writes to an sqlite.db file in the |
21 | - same folder. |
22 | - |
23 | - --before <string> A command to execute *before* each re-run. Example: --before 'v wipe-cache' |
24 | - |
25 | - --after <string> A command to execute *after* each re-run. Example: --after 'rm -rf /tmp/v/' |
26 | - |
27 | -You can also customise the timeout, after `v watch` will re-start a monitored |
28 | -program automatically, even if it was not changed by setting the enviroment |
29 | -variable VWATCH_TIMEOUT (in seconds). By default, it is 5 min. (300 seconds). |
30 |
1 | deleted file mode 100644 |
2 | -Usage: |
3 | - v where symbol_type symbol_name [params] |
4 | - |
5 | -Examples: |
6 | - v where fn main |
7 | - v where struct User |
8 | - v where method Square.area |
9 | - v where fn pow -mod math |
10 | - v where interface callable -dir some -dir other |
11 | - |
12 | --------------------------------------------------------------------------------- |
13 | -Prints the location of the searched symbols in the scope of the current project. |
14 | --------------------------------------------------------------------------------- |
15 | - |
16 | -symbol_name can be: |
17 | - fn by default if omit symbol_type (don't omit preferably) |
18 | - method require Struct.method notation |
19 | - struct |
20 | - interface |
21 | - enum |
22 | - const |
23 | - var |
24 | - regexp |
25 | - |
26 | -params: |
27 | - -mod [mod_name] Restrict to search recursively only within of the given |
28 | - module, if not provided search in entire v scope |
29 | - (use -mod main to search inside all your project). |
30 | - -dir [dir_path] Restrict to search non recursively within the given |
31 | - folder/s, if not provided, search in entire v scope. |
32 | - -vis [visibility] Can be: all, pub, pri (all by default if not provided). |
33 | - Restrict to search symbols with the given visibility. |
34 | - -mut [mutability] Can be: any, yes, not (any by default if not provided). |
35 | - Restrict to search symbols with the given mutability. |
36 | -flags: |
37 | - -h include Header |
38 | - -f Format output (each match uses 3 lines) |
39 | - -v for both above (more Verbose) |
40 | - |
41 | -Note: |
42 | - This tool is inspired by the vdoc tool and its design. However, this is |
43 | - for a more specific use, and can be improved. |
44 |