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