This command compiles the given target, along with their dependencies, into an executable.

Usage:
  v [build flags] ['run'] <target.v|target_directory> [run options]

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`.

   -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.

   -ldflags <flag>
      Pass the provided flag as is to the C compiler *after every other C option*.
      Can be specified multiple times to provide multiple flags.
      Use quotes to wrap the flag argument, if it contains spaces.

      Note: V also supports the environment variables CFLAGS and LDFLAGS.
      The contents of the CFLAGS variable will be prepended as is, at the start
      of the C backend command, right after the name of the compiler.
      The contents of the LDFLAGS variable will be appended as is, at the end
      of the C backend command, after all other options.

   -cstrict
      Turn on additional C warnings. This slows down compilation
      slightly (~10% for gcc), but sometimes provides better error diagnosis.

   -cmain <MainFunctionName>
      Useful with framework like code, that uses macros to re-define `main`,
      like SDL2 does for example.
      With that option, V will always generate:
        `int MainFunctionName(int ___argc, char** ___argv) {`
        ... for the program entry point function, *no matter* the OS.
      Without it, on non Windows systems, it will generate:
        `int main(int ___argc, char** ___argv) {`
        ... and on Windows, it will generate:
          a) `int WINAPI wWinMain( HINSTANCE instance,
                                   HINSTANCE prev_instance,
                                   LPWSTR cmd_line,
                                   int show_cmd){`
          when you are compiling applications that `import gg`.
        ... or it will generate:
          b) `int wmain(int ___argc, wchar_t* ___argv[], wchar_t* ___envp[]){`
          when you are compiling console apps.

   -subsystem <auto|console|windows>
      Useful to change the generated main function on Windows.
      Ignored on other platforms. The default is `auto`.
      When set to `console` V will generate a `wmain` main function.
      When set to `windows` V will generate a `wWinMain` main function,
      even when you are not compiling `gg` apps.

   -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.

   -bare-builtin-dir <bare-builtin-dir>
      Use with `-freestanding`. This specifies the directory to the
      implementation of some basic builtin functions. The list is as follows:
         bare_print(buf &byte, len u64)
            Print len characters from the buffer pointed to by buf to stdout.
         bare_eprint(buf &byte, len u64)
            Print len characters from the buffer pointed to by buf to stderr.
         bare_panic(msg string)
            Print "V panic: " + msg, along with an optional backtrace
            and/or the V commit hash, and then exit.
         @[export: 'malloc']
         __malloc(n usize) &C.void
            Allocates n bytes of memory and returns the pointer to the first
            byte.
         @[export: 'free']
         __free(ptr &C.void)
            Free the block of memory ptr allocated by malloc.
         realloc(old_area &C.void, new_size usize) &C.void
            Allocates a new area of size new_size, copies old_area
            to the new area, and returns a pointer to the new area.
         @[export: 'calloc']
         __calloc(nmemb usize, size usize) &C.void
            Like malloc, but sets all the bytes to `0` first.
         memcpy(dest &C.void, src &C.void, n usize) &C.void
            Moves n bytes from dest to src, and returns dest
         memmove(dest &C.void, src &C.void, n usize) &C.void
            Like memcpy, but guaranteed to work if dest and src overlap.
         memcmp(a &C.void, b &C.void, n usize) int
            Compare two buffers of length n. If a and b are equal, return 0.
            Otherwise, return the difference between the first different letter.
         strlen(s &C.void) usize
            Returns the amount of bytes until the first `0`, starting at s
         memset(s &C.void, c int, n usize) &C.void
            Sets n bytes starting at s to c (c is casted to a char)
            and returns s.
         getchar() int
            Read one character from stdin and return it.
         vsprintf(str &char, format &char, ap va_list) int
            See `man vsprintf`.
         vsnprintf(str &char, size usize, format &char, ap va_list) int
            See `man vsnprintf`.
         bare_backtrace() string
            Return a backtrace that can be printed. If backtraces are not
            supported, return a message stating that backtraces do not work.
         @[export: 'exit']
         __exit(code int)
            Exit with code code. code is allowed to be ignored.

         The module declaration should be `builtin`. The default Linux
         implementation can be found in `vlib/builtin/linux_bare`.

   -cross
      With `-cross`, V will attempt to output cross-platform C code.

   -os <os>, -target-os <os>
      Change the target OS that V tries to compile for.
      By default, the target OS is the host system.

      Here is a list of the operating systems, supported by V:
      (CI tests runs on every commit/PR for each of these):
            `windows`, `linux`, `macos`

      The compiler is known to also work, and has support for these operating
      systems also (although we do not test it as regularly as for the above):
            `vinix`,
            `ios`,
            `android`, `termux`,
            `freebsd`, `openbsd`, `netbsd`, `dragonfly`,
            `solaris`, `serenity`, `haiku`,
            `plan9`,
            `wasm32`, `wasm32-wasi`, `wasm32-emscripten`

      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 `-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
      Whether 32-bit or 64-bit machine code will be generated.
      NB: if you need to produce 32-bit code, *and* you are cross compiling
      to another OS, you may need to also set the environment variable
      VCROSS_COMPILER_NAME, in order to override the default cross compiler,
      that V will use (`x86_64-w64-mingw32-gcc` for targeting Windows, and
      `clang` for targeting Linux from other operating systems).

   -macosx-version-min 10.7
      Only relevant on macos. It will be passed as -mmacosx-version-min=10.7 to
      the C backend compiler clang . It is 10.7 on macos by default. If you
      pass `-macosx-version-min 0`, then that flag will not be passed at all.

   -sanitize
      Pass flags related to sanitization to the C compiler.

   -shared
      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

   -is_o
      Tell V to compile an .o object file instead of an executable.
      This is useful if you plan to create a module, that will be later linked to a
      larger program, potentially written in another language.
      Note: this option currently works with gcc/clang/tcc, but not msvc.
      Note: use either -no-skip-unused or tag the functions you expect to be publicly
      usable in the .o file with `@[markused]` . Adding `-gc none` may be also needed,
      unless you plan to link with -lgc later.

# 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.

   -gc <mode>
      V uses a garbage collector by default. Only the Boehm–Demers–Weiser garbage collector
      is supported currently with the following sub-options:

      `-gc boehm` ........... use default garbage collector (same as not specifying option)
      `-gc boehm_full` ...... full garbage collection mode
      `-gc boehm_incr` ...... incremental/generational garbage collection mode
      `-gc boehm_full_opt` .. optimized full garbage collection mode
      `-gc boehm_incr_opt` .. optimized incremental/generational garbage collection mode
      `-gc boehm_leak` ...... leak detection mode
      `-gc none` ............ no garbage collector

      Note: the garbage collector is complementary to -autofree. The Boehm garbage
      collector is conservative, and it may affect program speed if it does many small
      allocations in a loop.

      The option `-gc boehm_leak` is intended for leak detection in
      manual memory management. The function `gc_check_leaks()`
      can be called to get detection results. This function is a no-op
      when `-gc boehm_leak` is not supplied.

      Use `-gc none` to completely disable the garbage collector, in case of
      wanting to handle memory manually, or strictly using `-autofree`.

      Note: some short lived applications, like compilers and other CLI tools can be
      more performant, without autofree, and without a garbage collector, instead
      relying on the OS to free the allocated memory automatically, after their
      process ends.

      On most supported platforms, the source of the used garbage collector is
      located in `thirdparty/libgc/`, produced by post-processing
      `https://github.com/ivmai/bdwgc`. If you have installed libgc by other means,
      (through your distro's package manager or by compiling it yourself and
      installing it), you can also tell V to use it instead of its own copy,
      by adding `-d dynamic_boehm` to the command line while compiling your program.

      On Debian you can use `sudo apt install libgc-dev`.

      On macOS, you can install it, using homebrew (https://homebrew.sh/)
      with `brew install libgc`.

# 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
      Compress the compiled executable with UPX.
      Note: `upx` should be installed beforehand.
      In most Linux distros it is in a package named `upx-ucl`.
      On macOS, you can install it with `brew install upx`.
      On Windows, you can download it from https://upx.github.io/ .

   -live
      Build the executable with live capabilities (`[live]`).

   -no-preludes
      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.

   -custom-prelude <path>
      Useful for similar use-case as above option, except it replaces V-generated prelude with
      your custom one loaded from specified <path>.

# Debugging:
   -g, -debug
      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, -cdebug
      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.

   -show-c-output
      Prints the output, that your C compiler produced, while compiling your program.

   -dump-c-flags file.txt
      Write all C flags into `file.txt`, one flag per line.
      If `file.txt` is `-`, write to stdout instead.

   -dump-modules file.txt
      Write all module names used by the program in `file.txt`, one module per line.
      If `file.txt` is `-`, write to stdout instead.

   -dump-files file.txt
      Write all used V file paths used by the program in `file.txt`, one module per line.
      If `file.txt` is `-`, write to stdout instead.

   -dump-defines file.txt
      Write all system and user defines, that V knows about for the current program, one per line.
      If `file.txt` is `-`, write to stdout instead.
      Example sample of the content of that file:
          system,linux,eval
          system,amd64,eval
          system,solaris,skip
          system,solaris,skip
          user,gcboehm,eval
          user,gg_record_trace,skip

   -no-rsp
      By default, V passes all C compiler options to the backend C compiler
      in so called "response files" (https://gcc.gnu.org/wiki/Response_Files).
      This works in most cases, since it works around command line length
      limitations on older systems (and windows), but some C compilers
      (older versions of tcc for example) do not support them at all. When
      you use -no-rsp, V will pass the C compiler options directly to the C
      compiler, on the command line, without writing an .rsp file first.

   -no-std
      By default, V passes -std=gnu99(linux)/-std=c99 to the C backend, but some compilers do
      not support that, even though they may be able to compile the produced
      code, or have other options that can be tuned to allow it.
      Passing -no-std will remove that flag, and you can then use -cflags ''
      to pass the other options for your specific C compiler.

   -assert aborts
      Call abort() after an assertion failure. Debuggers usually
      install signal handlers for SIGABRT, so your program will stop and you
      will get a backtrace. If you are running your program outside of a
      debugger, you will most likely get a core dump file.

   -assert backtraces
      Call print_backtrace() after an assertion failure. Note that
      backtraces are not implemented yet on all combinations of
      platform/compiler.

   -assert continues
      Just prints the failed assertion then continues. Useful if you want to see
      the failures of many assertions that are all in the same test_ function.

   -thread-stack-size 4194304
      Set the thread stack size to 4MB. Use multiples of 4096.
      The default is 8MB, which is enough for compiling V programs, with deeply
      nested expressions (~40 levels).
      It may need to be increased, if you are getting stack overflow errors for
      deeply recursive programs like some of the stages of the V compiler itself,
      that use relatively few threads.
      It may be decreased, to reduce the memory footprint of programs that launch
      hundreds/thousands of threads, but where each of the threads does not need
      a big stack.

   -fast-math
      When present, pass either -ffast-math or /fp:fast (for msvc) to the C compiler.
      See https://en.wikipedia.org/wiki/Floating-point_arithmetic#%22Fast_math%22_optimization
          https://learn.microsoft.com/en-us/cpp/build/reference/fp-specify-floating-point-behavior?view=msvc-170&redirectedfrom=MSDN
          https://clang.llvm.org/docs/UsersManual.html#cmdoption-ffast-math
          https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ffast-math

   -div-by-zero-is-zero
      Avoids division by zero errors, by treating `x / 0` as being equal to `0`.
      It also treats `x % 0` as being equal to `x`, because `x%y`==`x-y*(x/y)`,
      which in turn eliminates another source of division by zero errors.
      It is mainly useful when prototyping games, and other experimental code with
      lots of arithmetic expressions, where you do not want to check for the zero divisor
      all the time (which can break your flow).
