The build system for V

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

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.

This enables you to do for example: `v -cc gcc -g run myfile.v -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'.

The default compiler:
  On macOS, Linux, and BSD, `v` compiles with the experimental V3 compiler (vlib/v)
  by default. When V3 cannot yet build an eligible program, V automatically falls
  back to the established compiler in vlib/v, so builds keep working. Unless the
  environment variable V_C_ERROR_BUG_REPORT_DISABLED=1 is set, a reportable
  fallback also sends the V version, target, and build options to
  https://bugs.vlang.io, plus a bounded snippet of the failing V source when one
  is available. Any snippet is a strict subset and the whole file is never
  uploaded. An internal V3 compiler error on a short program or a directory build
  such as `v .` submits metadata only. If the input selected for a source excerpt
  changes after V3 parses it, that report also submits metadata only, rather than
  source V3 did not parse. Before submitting, the stable compiler verifies that
  it parsed the same bytes for every captured project input; otherwise no fallback
  report is submitted. An unchanged input mapped from a generated-C error can still
  upload a strict-subset excerpt of it, even for a short file.
  Inline-assembly fallbacks and reports that cannot fit safely through the retry
  environment are notice-only; test compilations and GitHub CI also submit no
  report to the default endpoint. A custom fallback URL set with
  V_C_ERROR_BUG_REPORT_URL remains active in CI. The -bug-report-url option
  selects the established compiler and configures only its reports. Pass
  `-old-compiler` (see `v help build-c`) to always use the established compiler
  and skip the V3 attempt and its fallback reporting. The established compiler
  can still report its own eligible generated-C failures; set
  V_C_ERROR_BUG_REPORT_DISABLED=1 to disable all such submissions.

Use `v build script.vsh` to compile a `.vsh` script without running it.
`v -skip-running script.vsh` works too.
See `v help vsh` for what script mode changes.

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 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 V to write the resulting executable or object to the output file or directory,
instead of the default behavior described in the last two paragraphs.
If the output ends with a path separator, it is treated as an output directory and
V will infer the filename from the target, creating the directory if needed.

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

NB: the build flags are shared with the run command too:

  -b <backend>, -backend <backend>
    Specifies the backend that will be used for building the executable.
    Current list of supported backends:
    * `c` (default)       - V outputs C source code, which is then passed to a C compiler.
    * `fastc`             - V parses supported source directly to C without an AST and compiles
                            it with the bundled TinyCC; available on macOS, Linux, and Windows
                            hosts. V executables built from `cmd/v` (`make`, `makev.bat`,
                            `v self`, `v up`) include it unless they are built with
                            `-d skip_fastc`.
                            Supports array/map literals, checked array indexing, and `in`/`!in`.
                            See doc/fastc.md for supported constructs and current limitations.
    * `go`                - V outputs Go source code, which is then passed to a Go compiler.
    * `js`                - V outputs JS source code which can be passed to NodeJS to be ran.
    * `js_browser`        - V outputs JS source code ready for the browser.
    * `js_node`           - V outputs JS source code to run with nodejs.
    * `js_freestanding`   - V outputs JS source code with no hard runtime dependency.
    * `arm64`             - V outputs a native ARM64 executable directly on macOS.
                            Enable it with `v -compile-backend arm64 self`, then use
                            `v -b arm64 -gc none file.v` (EXPERIMENTAL).
    * `wasm`              - V outputs a WebAssembly module directly
	                        (see -os wasi|browser) (EXPERIMENTAL).

    `-b native` has been replaced by `-b arm64`. A native AMD64 backend is not available yet;
    use `v -b c -arch amd64 file.v` for AMD64 compilation through the C backend.

  -d <flag>[=<value>], -define <flag>[=<value>]
    Define the provided flag.
    If `value` is not provided, it is assumed to be set to `true`.
    `value` can be any pure literal like `32` (i64),`34.98` (f64), `false` (bool),
    `v` (char) or `"V rocks"` (string).
    In V code you can use `value := $d('<flag>', <default value>)` to retrieve the
    value assigned to `<flag>`.
    If no flag identifier (or value) is assigned, `$d()` will return the passed `<default value>`.

  -g, -debug
    Compile the executable in debug mode, allowing code to be debugged more easily.

  -o <output>, -output <output>
    Force V to output the executable in a specific location
    (relative to the current working directory if not absolute).
    If <output> ends with a path separator, V treats it as a directory.

  -obf, -obfuscate
      Turn on obfuscation for the code being built. Currently only renames symbols.

  -path
    Specify the order of path V looks up in while searching for imported dependencies,
    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
                  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:
      -path "/v/my_project_private_modules|@vlib|@vmodules"
    By default, -path is just "@vlib|@vmodules" .
    Project-local module lookup is resolved from the compiled target/importing file,
    not from the shell current working directory.

  -exclude
    Specify an exclude pattern that will be applied as a filter over the full paths of the .v
    files, that otherwise would have been selected for compilation.
    Note:
       @vroot is expanded to the location, where the v executable is.
       @vlib is expanded do the location where your vlib/ folder is (next to your v executable).
       @vmodules is expanded with the location of your ~/.vmodules/ folder.
    Example:
       `./v -exclude @vlib/math/*.c.v vlib/math/math_test.v`
            ^ run the math test file, using only pure .v files, excluding the .c.v overrides.

  -file-list
    Specifies a comma-separated list of paths for compilation. Paths can be to individual .v files
	or directories; all .v files found recursively within directories are included.
    Example:
       `./v main.v -file-list "src/part_a.v,src/part_b.v,lib/moda"

  -prod
    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.
    TinyCC is not a -prod compiler: `-cc tcc`, or any compiler that resolves to TinyCC,
    stops with `tcc is not allowed with -prod`. `-b fastc` is not supported with `-prod` either.
    Note: gcc versions > 12.0 often have issues with inlining, that manifest with `-prod`.
    To work around them, you can use `-prod -cflags -fno-inline-small-functions` .

  -warn-about-allocs
    Warn about array initialization, string interpolation, string concatenation, and casts to
    interfaces that allocate, and about allocations the source does not show: `&Struct{}`,
    values converted to an interface without a cast (arguments, assignments, returns, struct
    fields, appended elements), slices of strings and fixed arrays, and locals moved to the
    heap because their address escapes. Add `@[freed]` after an assignment to suppress
    allocation warnings for allocations that the assignment frees explicitly.

  -no-prod-options
    Useful in combination with -prod and -cflags, for allowing more complete customisation,
    of what flags will be used for the C compiler, for example:
       `v -prod -no-prod-options -cflags "-Os" program.v`
    will compile the program, without passing `-O3` and `-flto`, that would otherwise
    have been used, but passing `-Os` instead. Note, since `-prod` is used, the V compiler
    itself will still compile your potential `$if prod {` branches, and it will still do the
    optimisations on the V side, that -prod enables. You can also use it to compile programs
    with different optimisation options passed to the C compiler, like `-O2` instead of
    the default ones, which can be beneficial for working with older or newer buggy compilers.

  -no-bounds-checking
    Programs compiled with this option, will do no runtime checking of array access operations.
    Note that the performance impact of the bounds checking is usually below 3%, so in most
    cases, it is preferable to not turn it off, than disable it, and have a program that may
    do out of bounds accesses.

  -force-bounds-checking
    Programs compiled with this option, will *ALWAYS* do runtime checking of array access
    operations, even inside functions/methods, that were tagged with `@[direct_array_access]`.
    This allows for more convenient testing of modules that do use `@[direct_array_access]`,
    extensively (like `math.big`), without constantly edititing their source code to remove/add
    the tag. Note: this option overrides -no-bounds-checking .

  -disable-explicit-mutability, --disable-explicit-mutability
    Allow ordinary variables and mutable call arguments in user code to omit explicit `mut`.
    `mut`/`shared`/`atomic` in function and method signatures remain unchanged.

  -trace-calls
    Log entries to generated V functions on stderr (C backend only).
    Each record contains the thread id, elapsed timer value, stack delta in bytes,
    and module/function name with its parameter count (including method receivers).
    Startup (C.main and _vinit) and cleanup (_vcleanup) are also traced.
    Tracing disables the module cache so imported functions are instrumented too.
    Stack deltas are relative to the startup frame, not individual frame sizes;
    they are only meaningful for the startup thread.
    Example: v -trace-calls run examples/hello_world.v

  -trace-fns <patterns>
    Restrict -trace-calls to comma-separated function or module names/glob patterns.
    This selects entries, not their callees. The trace header is still printed
    when no function matches. Quote wildcard patterns to avoid shell expansion.
    Example: v -trace-calls -trace-fns 'main.*,println,_vcleanup' run program.v

  -prof, -profile <file.txt>
    Compile the executable with all functions profiled.
    The profile results will be stored in `file.txt`.
    The format is 4 fields, separated by a space, for each v function:
      a) how many times it was called
      b) how much *nanoseconds in total* it took
      c) an average for each function (i.e. (b) / (a) )
      d) the function name

    NB: you can also combine this command with `run` command.
        For example - `v -prof prof.txt run main.v`

    NB: the profiler is *NOT* currently thread safe, so look at the profile results of
        multithreaded programs very sceptically !

    NB: if you want to output the profile info to stdout, use `-profile -`.

    NB: you can use `import v.profile`, and then calls to `profile.on(false)`
        and `profile.on(true)` to temporarily turn it off and on again.

    NB: if you do NOT want the profile to contain information from before your
        program's `fn main()` starts, pass `-d no_profile_startup` too.
        (V constants, and module init() functions are evaluated before `main()` is called)

    NB: You can also select specific functions for profiling. For example:
        v -profile-fns println,i64_str -profile - run examples/hanoi.v
        In this case, the profile counters will be updated only for them,
        *and* for the functions that they call.
        The profile result (after the program finishes), will look similar to this:
          127          0.721ms           5680ns println
          127          0.693ms           5456ns _writeln_to_fd
          127          0.565ms           4449ns _write_buf_to_fd
          127          0.045ms            353ns _v_malloc
          127          0.017ms            131ns malloc_noscan
          127          0.017ms            133ns _v_free
          127          0.014ms            113ns vmemmove
          127          0.110ms            866ns i64_str
          127          0.016ms            127ns tos

  -e <code>, -e=<code>
    Compile and run inline V source as a script. Compiler options go before -e; arguments
    after the source are passed to the program. The program exit status is returned.
    For example: v -e 'println(1)'

  -http
    Serve the current directory on localhost:4001. Equivalent to:
    v -e 'import net.http.file; file.serve()'

  -message-limit <limit>
    The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 200).
    The compiler may stop accumulating additional diagnostics, once this limit has been reached.
    Setting this to a negative value like -1, will disable the limit.
    Setting this to 0, will stop showing errors, but the compiler will still exit with a non zero
    exit code, if there are any.

  -no-parallel
    Do not run the compiler in parallel (currently only the cgen stage has parallelization).

  -profile-no-inline
    Skip [inline] functions when profiling.

  -skip-running
    Skip the automatic running of a _test.v or .vsh file. Useful for debugging and testing.
    V's testing program `v test` uses that option, to measure and report independently the
    duration of each _test.v comptime, and then the duration of its runtime.
    Note: the same effect can be achieved by setting the environment variable VNORUN to 1.

  -no-skip-unused
    Generate C/JS code for all functions, including those that are provably not used by your
    project. By default, V skips them, which speeds up compilation, and reduces the generated
    output size. Use this option if your program breaks only because of that, and please
    report the issue.

  -stats
    Enable more detailed statistics reporting, while compiling test files.
    You can use that with `v test` too, for example:
      v -stats test vlib/
    ... will run test_ functions inside all _test.v files inside vlib/ ,
    and will report detailed statistics about how much time each test_ function took, how many
    assertions were made, how many tests passed/failed and so on.

  -translated
    Enable features that are discouraged in regular V code but required for translated V code.

  -q
    Tell V to be quieter, and to not show many otherwise helpful messages, that only get in your
    way once you have read them a few dozen times. One example is the notice message, usually
    shown for `v -prod run file.v`, that says that -prod should not be used with run .
    Note, this option *does not affect* errors/warnings/notices, just messages that V prints in
    order to be more user friendly, in common situations, that are error prone for new users, and
    that just needlessly take vertical space, once you are well aware of them.
    Note: setting `VQUIET` to 1, has the same effect.

  -v
    Enable verbosity in the V compiler while compiling

  -print-v-files
    Just print the list of all parsed .v files, then stop processing further.
    This is useful for running external processing tools:
      ./v -print-v-files cmd/v | etags -L -
        ... will generate a TAGS file, that emacs can then use to jump
    to the definition of functions used by v itself. For vim:
      ./v -print-v-files cmd/v | ctags -L -
        ... will generate a similar tags file, that vi compatible editors can use.
    NB: an useful, although not entirely accurate regexp based Universal Ctags options file
      for V is located in `.ctags.d/v.ctags` . If you use https://ctags.io/ , it will be used
      up automatically, or you can specify it explicitly with --options=.ctags.d/v.ctags .

  -color, -nocolor
    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
    Scans, parses, and checks the files without compiling the program.
    It checks every function. A build leaves out the bodies of the standard library functions
    that the program cannot reach, as it does not compile them either; the environment
    variable V_CHECK_LIBRARY_BODIES=all makes a build check them too.

  -check-syntax
    Only scan and parse the files, but then stop. Useful for very quick syntax checks.

  -json-errors
    Print each error, warning and notice as one JSON object per line on stderr, for editors and
    other tools that read them, instead of the text with a source excerpt. For example:
      {"file":"a.v","line":3,"col":7,"end_line":3,"end_col":14,"severity":"error","message":"..."}
    The lines and the columns start at 1, a column counts bytes, and the end is the position
    after the reported span. The severity is `error`, `warning` or `notice`. A diagnostic can
    also have `details`, `label` for the label of the text form when it says more than the
    severity (like `builder error`), and `called_from` for an error inside a template. The
    exit code does not change. Combine it with -check to get the diagnostics without building
    the program.

  -show-timings
    Print elapsed time for each compiler stage and the total compilation time.
    Uses the same benchmark summary as -v, including memory usage and cache metrics,
    without verbose compiler traces. -silent suppresses this summary, as does writing
    generated C to stdout with -o -.

    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.

  -n
    Hide all notices, without hiding warnings or errors.

  -N
    Treat *all V notices* as errors.

  -w
    Hide all warnings.

  -W
    Treat *all V warnings* as errors, even in development builds.

  -Wfatal-errors
    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.
    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 modules are cleaned up.

  -check-return
    Note about all calls, that ignore the return value of
    the corresponding fn/method.
    NB: this is still experimental, the rules for it will
    change, it may be dropped completely, or it may become the default.

For C-specific build flags, use `v help build-c`.
For JS-specific build flags, use `v help build-js`.
For WebAssembly-specific build flags, use `v help build-wasm`.

See also:
   `v help run` for documentation regarding `v run`.

Production C builds reject TinyCC, including executable aliases. This restriction does not
apply to help/version commands or non-C backends.
