docs: update debugging information

cmd/v/help/build-c.txt

@@ -1,42 +1,29 @@
-Usage: v [build flags] ['build'] <file.v|directory>
+Usage: v [C build flags] ['run'] <target.v|target_directory> [run options]
 
 This command compiles the given target, along with their dependencies, into an executable.
 
-This help topic explores C-backend specific build flags.
+This help topic explores the C-backend specific build flags. For more general build help,
-For help regarding building an executable, see `v help build`.
+see also `v help build`.
-
-These build flags are enabled on `build` and `run` as long as the backend is set to `c`:
 
+# Interfacing the C compiler, passing options to it:
    -cc <compiler>
       Change the C compiler V invokes to the specified compiler.
       The C compiler is required to support C99.
-      Officially supported/tested C compilers include: `clang`, `gcc`, `tcc`, `mingw-w64` and `msvc`.
+      Officially supported/tested C compilers include:
+      `clang`, `gcc`, `tcc`, `mingw-w64` and `msvc`.
 
    -cflags <flag>
       Pass the provided flag as is to the C compiler.
       Can be specified multiple times to provide multiple flags.
       Use quotes to wrap the flag argument if it contains spaces.
 
-   -printfn <fn_name>
+   -showcc
-      Prints the content of the generated C function named fn_name. You can repeat that many times.
+      Prints the C command that is used to build the program.
-      This is useful when you just want to quickly tweak the generated C code,
-      without opening the generated .c file in an text editor.
-
-   -cg
-      Enable generating more debug information in the compiled executable.
-      This makes program backtraces more useful.
-      Using debuggers like gdb/lldb with such executables is easier too.
-
-   -compress
-      Strip the compiled executable to compress it.
 
    -freestanding
       Build the executable without dependency on libc.
       Supported only on `linux` targets currently.
 
-   -live
-      Build the executable with live capabilities (`[live]`).
-
    -os <os>, -target-os <os>
       Change the target OS that V tries to compile for.
       By default, the target OS is the host system.
@@ -44,6 +31,25 @@ These build flags are enabled on `build` and `run` as long as the backend is set
       List of OS supported by V: `linux`, `windows`, `ios`, `mac`, `freebsd`, `openbsd`,
                                  `netbsd`, `dragonfly`, `solaris`, `android` and `haiku`.
 
+      Note that V has the concept of platform files, i.e. files ending
+      with `_platform.c.v`, and usually only the matching files are used in
+      a compilation, and also it supports a `_default.c.v` file, that will
+      be used, when no other more specific `_platform.c.v` file is found.
+      The default is mainly useful for writing shims for new platforms,
+      until a more specialized _platform.c.v is written instead.
+
+      For example, suppose you have these 3 files:
+          x_default.c.v
+          x_windows.c.v
+          x_linux.c.v
+      If you compile with `-os freebsd`, then x_default.c.v will be used.
+      If you compile with `-os linux`, then x_linux.c.v will be used.
+      If you compile with `-os windows`, then x_windows.c.v will be used.
+      If you compile with `-os cross`, then all, *except x_default.c.v*
+      will be used, wrapped in conditional compilation guards, so that
+      the generated C source code will be larger, but will compile on all
+      explicitly supported platforms without source changes.
+
    -m32, -m64
       Specify whether 32-bit or 64-bit machine code is generated.
 
@@ -54,6 +60,37 @@ These build flags are enabled on `build` and `run` as long as the backend is set
       Tell V to compile a shared object instead of an executable.
       The resulting file extension will be `.dll` on Windows and `.so` on Unix systems
 
+# Memory management
+   -autofree
+      Free memory used in functions automatically.
+
+   -manualfree
+      Do not free memory used in functions (the developer has to put x.free()
+      and unsafe{free(x)} calls manually in this mode).
+      Some short lived applications, like compilers and other CLI tools are
+      more performant without autofree.
+
+# Miscellaneous:
+   -printfn <fn_name>
+      Print the content of the generated C function named fn_name.
+      You can repeat that many times with different function names.
+      This is useful when you just want to quickly tweak the generated
+      C code, without opening the generated .c file in a text editor,
+      i.e. it enables this workflow:
+
+      1) change vlib/v/gen/cgen.v
+      2) ./v -o v2 cmd/v && ./v2 -printfn main__main bug.v
+      3) inspect the produced C, and goto 1) till the bug is fixed.
+
+      Since V compiles itself very fast (especially with tcc),
+      this loop is very short usually.
+
+   -compress
+      Strip the compiled executable to compress it.
+
+   -live
+      Build the executable with live capabilities (`[live]`).
+
    -no-prelude
       Prevents V from generating a prelude in generated .c files, useful for freestanding targets
       where eg. you replace C standard library with your own, or some definitions/headers break something.
@@ -62,15 +99,31 @@ These build flags are enabled on `build` and `run` as long as the backend is set
       Useful for similar use-case as above option, except it replaces V-generated prelude with
       your custom one loaded from specified <path>.
 
+# Debugging:
+   -g
+      Generate more debug information in the compiled executable.
+      This makes program backtraces more useful.
+      Using debuggers like gdb/lldb with such executables is easier too.
+      Unlike `-cg` (described below), `-g` will enforce V source line numbers
+      so that your debugger and the stacktraces will show you directly
+      what .v file is responsible for each call/panic.
+
+   -cg
+      Like -g, but do not use V source line numbers.
+      When debugging code that wraps C libraries, this option may be
+      more useful than -g, since it will reduce the amount of context
+      switching, that you need to do, while looking at .v and .c sources.
+      This option is usually used in combination with `-keepc`.
+
+   -keepc
+      Do not remove the temporary .tmp.c and .tmp.c.rsp files.
+      Also do not use a random prefix for them, so they would be fixed and predictable.
+
+      NB: when writing low level code that interfaces/wraps an existing C library,
+      it is frequently helpful to use these together: -keepc -cg -showcc -show-c-output
+
    -showcc
       Prints the C command that is used to build the program.
 
-   -keepc
+   -show-c-output
-      Do not remove the temporary .tmp.c and .tmp.c.rsp files. Also do not use a random prefix for them, so they would be fixed and predictable.
+      Prints the output, that your C compiler produced, while compiling your program.
-
-   -autofree
-      Free memory used in functions automatically.
-      
-   -manualfree
-      Do not free memory used in functions (the developer has to put x.free() and unsafe{free(x)} calls manually in this mode).
-      Some short lived applications, like compilers and other CLI tools are more performant without autofree.

cmd/v/help/build.txt

@@ -1,27 +1,37 @@
-Usage: v [build flags] <file.v|directory>
+Usage: v [build flags] ['run'] <target.v|target_directory> [run options]
 
 This command compiles the given target, along with their dependencies, into an executable.
 
-When compiling packages, build ignores files that end in '_test.v'.
+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.
 
-When compiling a single main package, build writes the resulting executable to an output file
+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 when writing a Windows executable.
+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 build to write the resulting executable or object to the d output file or directory,
+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 -debug"` on *nix,
+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.
 
-The build flags are shared by the build and run commands:
+NB: the build flags are shared with the run command too:
 
    -b <backend>, -backend <backend>
       Specify the backend to use while building the executable.
@@ -39,7 +49,7 @@ The build flags are shared by the build and run commands:
       Enable the specified experiment.
       Currently, the only experiment available is: `prealloc`
 
-   -cg
+   -g
       Compile the executable in debug mode, allowing code to be debugged more easily.
 
    -o <output>, -output <output>
@@ -62,7 +72,9 @@ The build flags are shared by the build and run commands:
       By default, -path is just "@vlib|@vmodules" .
 
    -prod
-      Compile the executable in production mode where most optimizations are enabled.
+      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.
 
    -prof, -profile <file.txt>
       Compile the executable with all functions profiled.
@@ -104,9 +116,9 @@ The build flags are shared by the build and run commands:
       up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags .
 
    -color, -nocolor
-      Force the use of ANSI colors for the error/warning messages, or disable them completely.
+      Force the use of ANSI colors for the V error/warning messages, or disable them completely.
-      By default V tries to show its errors/warnings in ANSI color. The heuristic that it uses
+      By default, the V compiler tries to show its errors/warnings in ANSI color. The heuristic
-      to detect whether or not to use ANSI colors may not work in all cases.
+      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-syntax
@@ -129,7 +141,7 @@ The build flags are shared by the build and run commands:
       Hide all warnings.
 
    -W
-      Treat all warnings as errors, even in development builds.
+      Treat *all V warnings* as errors, even in development builds.
 
    -Wfatal-errors
       Unconditionally exit with exit(1) after the first error.
@@ -138,8 +150,8 @@ The build flags are shared by the build and run commands:
    -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,
+      NB: in the future, this will be turned ON by default,
-      and will become an error, after vlib is cleaned up.
+      and will become an error, after vlib modules are cleaned up.
 
 For C-specific build flags, use `v help build-c`.
 

doc/docs.md

@@ -2982,12 +2982,26 @@ To cast a `voidptr` to a V reference, use `user := &User(user_void_ptr)`.
 
 To debug issues in the generated C code, you can pass these flags:
 
+- `-g` - produces a less optimized executable with more debug information in it.
+    V will enforce line numbers from the .v files in the stacktraces, that the
+    executable will produce on panic. It is usually better to pass -g, unless
+    you are writing low level code, in which case use the next option `-cg`.
 - `-cg` - produces a less optimized executable with more debug information in it.
+	The executable will use C source line numbers in this case. It is frequently
+    used in combination with `-keepc`, so that you can inspect the generated
+    C program in case of panic, or so that your debugger (`gdb`, `lldb` etc.)
+    can show you the generated C source code.
 - `-showcc` - prints the C command that is used to build the program.
+- `-show-c-output` - prints the output, that your C compiler produced
+    while compiling your program.
+- `-keepc` - do not delete the generated C source code file after a successful
+    compilation. Also keep using the same file path, so it is more stable,
+    and easier to keep opened in an editor/IDE.
 
-For the best debugging experience, you can pass all of them at the same time:
+For best debugging experience if you are writing a low level wrapper for an existing
-`v -cg -showcc yourprogram.v`,
+C library, you can pass several of these flags at the same time:
-then just run your debugger (gdb/lldb) or IDE on the produced executable `yourprogram`.
+`v -keepc -cg -showcc yourprogram.v`, then just run your debugger (gdb/lldb) or IDE
+on the produced executable `yourprogram`.
 
 If you just want to inspect the generated C code,
 without further compilation, you can also use the `-o` flag (e.g. `-o file.c`).