(build) Compilation commands for the V language

[Avey777]

The compilation command for V language code is:

• Default output is GC：

  GC only (default):v xxx.v

• You can automatically insert 90%～100% of memory free() code during compilation, and manage the remaining 0%～10% through GC：

  Autofree (-autofree)：v -autofree xxx.v

• You can use arena to manage memory：

  Arena (-prealloc)：v -prealloc xxx.v

• You can disable GC and manually manage memory：

  Manual (-gc none)v -gc none xxx.v

• You can disable GC and only use autofree to manage freed memory：

  Just autofree (-autofree -gc none)v -autofree -gc none xxx.v

---

• The cross-compilation command for V language is：

  v -os=target_operating_system -arch=target_architecture source_file.v
  v -os=windows -arch=amd64 xxx.v

---

Compile to C, then use emscripten or similar to create the WASM code.

• Default output is WASI：

  v -b wasm xxx.v

• You can also be explicit with：

  v -b wasm -os wasi xxx.v

• If you want WASM for the browser, use：

  v -b wasm -os browser xxx.v

• If you want WASM and disable GC and only use autofree to manage freed memory, use:

  v -b wasm -autofree -gc none xxx.v

[JalonSolov]

The -b option is used to specify the backend to use. You can see this in the output of v help build:

$ v help build
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 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 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 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 -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.
    * `go`                - V outputs Go source code, which is then passed to a Go compiler.
    * `interpret`         - V will interpret the V program directly, instead of compiling it first. Same as `v interpret file.v`.
    * `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.
    * `native`            - V outputs a native executable directly (see -arch x64|arm64 and -os linux|macos) (EXPERIMENTAL).

  -d <flag>[=<value>], -define <flag>[=<value>]
    Define the provided flag.
    If value is not provided, it is assumed to be set to `true`.
    `value` should be `1` or `0` to indicate `true` and `false` respectively otherwise.

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

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

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

  -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

  -message-limit <limit>
    The maximum amount of warnings / errors / notices, that will be accumulated (defaults to 100).
    The checker will abort prematurely once this limit has been reached.
    Setting this to 0 or a negative value, will disable the limit.

  -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-unused
    Skip generating C/JS code for functions, that are provably not used by your project.
    This speeds up compilation, and reduces the generated output size.
    It is still experimental, due to historical reasons, but please do try it,
    and report issues, if compilation breaks with that option for your program.

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

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

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

  -show-timings
    Print a summary about how long each compiler stage took, for example:
      PARSE: 152ms
      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:
    `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.

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

For C-specific build flags, use `v help build-c`.
For JS-specific build flags, use `v help build-js`.
For Native-specific build flags, use `v help build-native`.

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

$

[Avey777]

v -autofree -gc none xxx.v

Does this command disable GC and only use autofree to manage memory?

[Avey777]

v -b wasm -autofree -gc none xxx.v

Is this okay？

[JalonSolov]

Yes to both.

[MicahElliott]

Some of this appears to have changed since this answer. It is now possible to generate a list of v files with this (which is the ctags/etags recipe):

./v cmd/v -print-v-files