Jun 23, 2025

v: Quickstart and common usage for the V compiler

Overview

The v command is the V language compiler and toolkit. It can compile files, build projects, run code, start a REPL, format sources, and watch for changes. This guide shows practical, example-first usage and highlights common gotchas.

Basic compile and run

Compile a single file to an executable:

v path/to/file.v

Compile the current directory as a project (builds the default target):

v .

Compile a file and run it in one step:

v run path/to/file.v

Compile a file and produce an executable named after the file (crun):

v crun path/to/file.v

Tip: If your file contains a main function, v path/to/file.v will produce an executable with the same base name. If you want a custom name, rename the output after building.

Recompile on changes (watch)

Re-compile on every modification to a file:

v watch path/to/file.v

Re-run the file automatically on changes:

v watch run path/to/file.v

To watch a whole project and auto-rebuild on changes, point to the project directory:

v watch .

REPL and formatting

Open the V REPL for quick experimentation:

v repl

Format a file in place (write changes back):

v fmt -w path/to/file.v

Quick note: auto-formatting is handy before commits or reviews to keep style consistent.

Practical examples

Compile and run a small program:

# Suppose hello.v defines a main function
v run hello.v

Format and then build a project in one go (pseudo-workflow):

v fmt -w src/*.v
v .    # or v build if your project has a build.json or v.mod setup

Common pitfalls

Missing modules or dependencies: ensure your V project has a proper module setup (e.g., module mymod and a v.mod file) and that dependencies are installed.
Path problems: when using v path/to/file.v, make sure the path is correct relative to your current directory. Use absolute paths if needed.
Watch mode performance: watching large projects can consume CPU; limit watch to smaller subsets or rely on targeted builds during heavy development.
Formatting drift: running v fmt is a safe way to keep formatting consistent; consider integrating it into pre-commit hooks.

Quick checklist

Do you have a v.mod in your project root? If not, initialize or use v . in the right directory.
Are you compiling the right target (file vs. project)? Use v path/to/file.v or v . accordingly.
Want immediate feedback? Use v run path/to/file.v to see output without manual build steps.

When to choose which command

One-off script or experiment: v run file.v.
Building a standalone executable for distribution: v file.v (then run or rename output).
Development with rapid changes: v watch path/to/file.v or v watch ..
Interactive exploration: v repl.