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

docs: update debugging information

Browse Source
This commit is contained in:
Delyan Angelov 2021-01-13 12:50:35 +02:00
parent 219486f0a5
commit cf93be918f
No known key found for this signature in database
GPG Key ID: 66886C0F12D595ED
3 changed files with 137 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
cmd/v/help/build-c.txt
View File

@ -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.
For help regarding building an executable, see `v help build`.
These build flags are enabled on `build` and `run` as long as the backend is set to `c`:
This help topic explores the C-backend specific build flags. For more general build help,
see also `v help build`.
# 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>
Prints the content of the generated C function named fn_name. You can repeat that many times.
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.
-showcc
Prints the C command that is used to build the program.
-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
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.
-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.
-show-c-output
Prints the output, that your C compiler produced, while compiling your program.

42
cmd/v/help/build.txt
View File

@ -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.
By default V 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.
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-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,
and will become an error, after vlib is cleaned up.
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`.

20
doc/docs.md
View File

@ -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:
`v -cg -showcc yourprogram.v`,
then just run your debugger (gdb/lldb) or IDE on the produced executable `yourprogram`.
For best debugging experience if you are writing a low level wrapper for an existing
C library, you can pass several of these flags at the same time:
`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`).