mirror of
https://github.com/vlang/v.git
synced 2023-08-10 21:13:21 +03:00
docs: update debugging information
This commit is contained in:
Delyan Angelov
@@ -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.
|
||||
|
||||
@@ -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>
|
||||
@@ -54,7 +64,7 @@ The build flags are shared by the build and run commands:
|
||||
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
|
||||
(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:
|
||||
@@ -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
|
||||
@@ -118,9 +130,9 @@ The build flags are shared by the build and run commands:
|
||||
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:
|
||||
|
||||
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.
|
||||
@@ -129,18 +141,18 @@ 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.
|
||||
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.
|
||||
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`.
|
||||
|
||||
See also:
|
||||
|
||||
Reference in New Issue
Block a user