v/cmd/v/help/build-c.txt

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

      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.

   -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 charecters from the buffer pointed to by buf to stdout.
         bare_eprint(buf &byte, len u64)
            Print len charecters 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.
            Print "V Panic" + msg, along with an optional backtrace, and then exit.
         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`.

   -os <os>, -target-os <os>
      Change the target OS that V tries to compile for.
      By default, the target OS is the host system.
      When OS is `cross`, V will attempt to output cross-platform C code.

      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):
            `android`, `ios`,
            `freebsd`, `openbsd`, `netbsd`, `dragonfly`,
            `solaris`, `serenity`, `haiku`, `vinix`,
            `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 `-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
      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).

   -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

# 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>
      Use and link an optional garbage collector. Only the Boehm–Demers–Weiser
      garbage collector is supported currently with the following sub-options:

      `-gc boehm` ........... selects the default mode for the architecture
      `-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

      You need to install a `libgc-dev` package first, or install it manually from:

          https://github.com/ivmai/bdwgc

      On Mac OS, it can be installed using homebrew (https://homebrew.sh/) with
      `brew install libgc`.

      Note, `-gc boehm` is complementary to -autofree. The Boehm garbage
      collector is conservative, and it may make your program significantly
      slower if it does many small allocations in a loop. This option
      is intended *mainly* for reducing the memory usage of programs, that
      process large amounts of text in *batch mode* on low/limited memory
      environments like small VPSes, and for which a few ms of garbage
      collection pauses from time to time *do not matter much*.

      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.

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

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

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

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

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