Build Tools

vx supports various build systems, compilers, and task runners.

Build Cache Tools

vx provides compilation cache tools to speed up builds across projects. See Build Cache for detailed documentation.

Tool	Languages	Best For
sccache	Rust, C/C++, CUDA	Cross-language, CI/CD
ccache	C/C++	Native C/C++ projects
buildcache	C/C++ (MSVC)	Windows Visual Studio

bash

# Install sccache (supports Rust + C/C++)
vx install sccache
vx sccache --show-stats

# Install ccache (optimized for C/C++)
vx install ccache
vx ccache -s

# Install buildcache (best for MSVC)
vx install buildcache
vx buildcache -s

.NET SDK & MSBuild

.NET SDK

The .NET SDK includes the dotnet CLI, MSBuild, NuGet, and compilers for C#, F#, and VB.NET.

bash

# Install .NET SDK
vx install dotnet@latest
vx install dotnet 8.0        # LTS version

# Common commands
vx dotnet --version
vx dotnet new console -n MyApp
vx dotnet build
vx dotnet run
vx dotnet test
vx dotnet publish -c Release

MSBuild (Bundled with .NET SDK)

MSBuild is the Microsoft Build Engine, bundled with .NET SDK. vx automatically uses dotnet msbuild when you run vx msbuild.

bash

# MSBuild commands (uses dotnet msbuild)
vx msbuild MyProject.csproj
vx msbuild MySolution.sln /p:Configuration=Release
vx msbuild /t:Build /p:Platform=x64
vx msbuild /t:Clean
vx msbuild /t:Restore

# Equivalent to:
vx dotnet msbuild MyProject.csproj

RFC 0028: Bundled Runtime

MSBuild is a "bundled runtime" - it's not independently installable but comes with .NET SDK. When you run vx msbuild, vx:

Finds the .NET SDK installation (vx-managed or system)
Executes via dotnet msbuild
On Windows, can also use Visual Studio's standalone MSBuild if .NET SDK is not available

Example .NET Build Workflow:

bash

# Create new project
vx dotnet new webapi -n MyApi

# Build with MSBuild
cd MyApi
vx msbuild MyApi.csproj /p:Configuration=Release

# Or use dotnet build (simpler)
vx dotnet build -c Release

C/C++ Compilers

MSVC Build Tools (Windows)

Microsoft Visual C++ compiler and build tools for Windows development.

bash

# Install MSVC Build Tools
vx install msvc@latest
vx install msvc 14.40       # Specific version

# Runtime executable override syntax (recommended)
vx msvc::cl main.cpp -o main.exe
vx msvc::link main.obj
vx msvc::nmake
vx msvc::lib /OUT:mylib.lib *.obj

# Direct aliases (common tools)
vx cl main.cpp              # Same as: vx msvc::cl
vx nmake                    # Same as: vx msvc::nmake

# Version-specific usage
vx msvc@14.40::cl main.cpp   # Use MSVC 14.40
vx msvc@14.29::cl legacy.cpp # Use MSVC 14.29 (VS2019)

Available MSVC Tools:

Tool	Command	Description
cl	`vx msvc::cl` / `vx cl`	C/C++ compiler
link	`vx msvc::link`	Linker
lib	`vx msvc::lib`	Library manager
nmake	`vx msvc::nmake` / `vx nmake`	Make utility
ml64	`vx msvc::ml64`	MASM x64 assembler
dumpbin	`vx msvc::dumpbin`	Binary file dumper
editbin	`vx msvc::editbin`	Binary file editor

Example CMake + MSVC Workflow:

bash

# Configure with MSVC
vx cmake -B build -G "NMake Makefiles"

# Build
vx nmake -C build

vx.toml Configuration:

toml

[tools]
msvc = "14.40"

# Or with detailed configuration
[tools.msvc]
version = "14.40"
sdk_version = "10.0.22621"

Using MSVC with other tools (companion tool injection):

When vx.toml includes MSVC and the MSVC companion runtime is already installed/available, vx injects MSVC discovery environment variables (VCINSTALLDIR, VCToolsInstallDir, GYP_MSVS_VERSION, etc.) into subprocess environments, not just MSVC tools. This allows tools that need a C/C++ compiler to discover the vx-managed MSVC installation without a full Visual Studio installation.

If MSVC is missing or the existing installation needs repair, unrelated commands skip this companion injection instead of installing or repairing MSVC during command startup. Run vx setup or vx install msvc@14.42 first when those discovery variables are required.

Supported scenarios include:

node-gyp / Electron: vx npx node-gyp rebuild
CMake: vx cmake -B build (auto-detects MSVC via VCINSTALLDIR)
Cargo (cc crate): vx cargo build for crates with C dependencies
.NET Native AOT: vx dotnet publish -c Release
Meson: vx meson setup build

toml

# vx.toml - MSVC env vars are injected when the companion is installed
[tools]
node = "22"
cmake = "3.28"
rustup = "latest"

[tools.msvc]
version = "14.42"
os = ["windows"]

bash

# node-gyp will automatically find MSVC via VCINSTALLDIR
vx npx node-gyp rebuild

# CMake also discovers the compiler
vx cmake -B build -G "Ninja"

# Cargo cc crate finds MSVC for C dependencies
vx cargo build

# After vx setup or vx install msvc@14.42, verify the variables from any tool
vx node -e "console.log('VCINSTALLDIR:', process.env.VCINSTALLDIR)"
# Output when MSVC is available: VCINSTALLDIR: C:\Users\you\.vx\store\msvc\14.42\VC\

How companion tool injection works:

vx uses a "companion tools" mechanism: when executing any tool (e.g., vx node, vx cmake), vx also calls prepare_environment() for available companion tools defined in vx.toml. This injects discovery/marker environment variables without polluting the full compilation environment (LIB/INCLUDE/PATH). Missing or broken companions are skipped for unrelated commands; install or repair them explicitly with vx setup or vx install msvc@14.42.

Environment variables injected by MSVC companion:

Variable	Example	Purpose
`VCINSTALLDIR`	`C:\...\VC\`	VS install path (used by node-gyp, CMake, etc.)
`VCToolsInstallDir`	`C:\...\VC\Tools\MSVC\14.42.34433\`	Exact toolchain path
`VSCMD_VER`	`17.0`	VS Command Prompt version
`GYP_MSVS_VERSION`	`2022`	node-gyp VS version hint
`VX_MSVC_ROOT`	`C:\...\store\msvc\14.42`	vx MSVC root path
`VX_MSVC_FULL_VERSION`	`14.42.34433`	Full MSVC version

vcpkg - C++ Package Manager

vcpkg is a C++ library manager that simplifies the installation of C++ libraries and their dependencies. It is particularly useful for native Node.js modules that require C++ dependencies.

Installation

bash

# Install vcpkg
vx install vcpkg

# This downloads the vcpkg-tool binary only. vx ships no ports tree, triplets or
# scripts; the CLI reads ports from VCPKG_ROOT, which you supply when invoking
# vcpkg directly.

vx-Managed Cache Directories

vcpkg stores its downloads and binary caches inside its own install directory:

Directory	Purpose	Location
Downloads	Source archives and assets	`~/.vx/store/vcpkg/<version>/.cache/downloads/`
Archives	Binary cache for compiled packages	`~/.vx/store/vcpkg/<version>/.cache/archives/`

This means:

Per version: each vcpkg version has its own cache, so upgrading vcpkg does not reuse the previous cache
Easy cleanup: uninstalling that version removes its cache along with it

vcpkg itself is installed at ~/.vx/store/vcpkg/<version>/ (e.g., ~/.vx/store/vcpkg/2025.12.16/). The installation contains the vcpkg CLI binary only — no ports tree, triplets, scripts or registry checkout. The CLI reads ports from VCPKG_ROOT, which you supply when invoking vcpkg directly.

What `vx lock` Pins

vx lock pins the vcpkg CLI version only. Everything that decides which C++ libraries you actually get stays outside the lock:

Outside the lock	Effect
Triplet (`x64-windows`, `x64-windows-static`, …)	The same CLI builds different binaries for different triplets.
Ports tree	vx ships the vcpkg CLI as a single binary and no ports tree of its own; the CLI reads ports from `VCPKG_ROOT`.
`VCPKG_ROOT`	Selects the registry checkout the CLI reads, and therefore the port versions it resolves.

To make the dependency graph reproducible as well, pin those separately:

Commit a vcpkg.json manifest with a builtin-baseline, and supply the matching registry checkout (vendored into the repo or added as a git submodule) through VCPKG_ROOT.
Pass the triplet explicitly (vx vcpkg install openssl:x64-windows) instead of relying on the default.

VCPKG_ROOT is taken from your environment only when you invoke vcpkg directly (vx vcpkg …). Inside vx dev, the vcpkg provider sets VCPKG_ROOT to its own install dir (~/.vx/store/vcpkg/<version>/), which holds the CLI binary only, so a value you export beforehand is replaced there.

vx lock guarantees you always get the same vcpkg executable — not the same C++ dependency graph.

Uninstalling

bash

# Uninstall vcpkg
vx uninstall vcpkg

# This removes the installation directory, including that version's downloads
# and binary caches. Other vcpkg versions are unaffected.

Installing C++ Packages

bash

# Install a C++ library
vx vcpkg install openssl

# Install for a specific triplet
vx vcpkg install openssl:x64-windows
vx vcpkg install openssl:x64-windows-static

# Search for packages
vx vcpkg search sqlite

Common Packages for Native Node.js Modules

Package	Description
`winpty`	Terminal emulation library (required by node-pty)
`openssl`	OpenSSL library
`sqlite3`	SQLite database
`libpng`	PNG library
`zstd`	Zstandard compression

Integration with MSVC

When both vcpkg and MSVC are installed, vx automatically integrates vcpkg paths into the MSVC environment. This allows native Node.js modules to find C++ libraries without additional configuration.

bash

# Install vcpkg and MSVC
vx install vcpkg
vx install msvc

# Install winpty (for node-pty)
vx vcpkg install winpty

# Build node-pty in your Electron project
vx npm install node-pty

Environment Variables

vcpkg sets the following environment variables:

Variable	Description
`VCPKG_ROOT`	Path to vcpkg installation
`CMAKE_TOOLCHAIN_FILE`	Path to vcpkg.cmake for CMake integration
`VCPKG_DEFAULT_TRIPLET`	Default triplet (e.g., x64-windows)
`VCPKG_DOWNLOADS`	vx-managed downloads cache directory
`VCPKG_DEFAULT_BINARY_CACHE`	vx-managed binary cache directory
`INCLUDE`	Prepended with vcpkg installed headers path
`LIB`	Prepended with vcpkg installed library path

Using with CMake

bash

# CMake automatically detects vcpkg via CMAKE_TOOLCHAIN_FILE
vx cmake -B build -S .
vx cmake --build build

vx.toml Configuration

toml

[tools]
vcpkg = "latest"
msvc = "14.42"
cmake = "3.28"

# Project-specific C++ dependencies
[dependencies.cpp]
vcpkg_packages = ["winpty", "openssl"]

Task Runners

Just

A handy way to save and run project-specific commands.

bash

vx install `just@latest

vx just --version
vx just --list
vx just build
vx just test
vx just deploy

Example Justfile:

makefile

# Build the project
build:
    cargo build --release

# Run tests
test:
    cargo test

# Format code
fmt:
    cargo fmt

Task (go-task)

Task runner / simpler Make alternative written in Go.

bash

vx install `task@latest

vx task --version
vx task --list
vx task build
vx task test

Example Taskfile.yml:

yaml

version: '3'

tasks:
  build:
    cmds:
      - go build -o app .

  test:
    cmds:
      - go test ./...

Build Systems

CMake

Cross-platform build system generator.

bash

vx install `cmake@latest

vx cmake --version
vx cmake -B build -S .
vx cmake --build build
vx cmake --build build --config Release
vx cmake --install build

Common CMake Workflow:

bash

# Configure
vx cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build
vx cmake --build build --parallel

# Install
vx cmake --install build --prefix /usr/local

Ninja

Small build system with a focus on speed.

bash

vx install `ninja@latest

vx ninja --version
vx ninja -C build
vx ninja -C build clean
vx ninja -C build -j 8

Using with CMake:

bash

vx cmake -B build -G Ninja
vx ninja -C build

protoc

Protocol Buffers compiler.

bash

vx install `protoc@latest

vx protoc --version
vx protoc --cpp_out=. message.proto
vx protoc --python_out=. message.proto
vx protoc --go_out=. message.proto
vx protoc --rust_out=. message.proto

Frontend Build Tools

Vite

Next generation frontend tooling.

bash

vx install vite@latest

vx vite --version
vx vite                    # Start dev server
vx vite build             # Build for production
vx vite preview           # Preview production build

Rust WebAssembly Build Tools

Trunk

Build, bundle, and ship Rust WASM web applications.

bash

vx install trunk@latest

vx trunk --version
vx trunk serve            # Start dev server
vx trunk build --release  # Build optimized app

wasm-pack

Build and package Rust-generated WebAssembly for JavaScript consumers.

bash

vx install wasm-pack@latest

vx wasm-pack --version
vx wasm-pack build
vx wasm-pack test --headless --firefox

WebAssembly Runtimes

Wasmtime

Fast and secure WebAssembly runtime from the Bytecode Alliance.

bash

vx install wasmtime@latest

vx wasmtime --version
vx wasmtime run app.wasm

Wasmer

Universal WebAssembly runtime and package runner.

bash

vx install wasmer@latest

vx wasmer --version
vx wasmer run app.wasm

Project Configuration Example

toml

[tools]
just = "latest"
task = "latest"
cmake = "3.28"
ninja = "latest"
protoc = "latest"
vite = "latest"
trunk = "latest"
wasm-pack = "latest"
wasmtime = "latest"
wasmer = "latest"

[scripts]
build = "just build"
cmake-build = "cmake -B build && cmake --build build"
proto-gen = "protoc --go_out=. *.proto"
dev = "vite"

Build Tools ​

Build Cache Tools ​

.NET SDK & MSBuild ​

.NET SDK ​

MSBuild (Bundled with .NET SDK) ​

C/C++ Compilers ​

MSVC Build Tools (Windows) ​

vcpkg - C++ Package Manager ​

Installation ​

vx-Managed Cache Directories ​

What vx lock Pins ​

Uninstalling ​

Installing C++ Packages ​

Common Packages for Native Node.js Modules ​

Integration with MSVC ​

Environment Variables ​

Using with CMake ​

vx.toml Configuration ​

Task Runners ​

Just ​

Task (go-task) ​

Build Systems ​

CMake ​

Ninja ​

protoc ​

Frontend Build Tools ​

Vite ​

Rust WebAssembly Build Tools ​

Trunk ​

wasm-pack ​

WebAssembly Runtimes ​

Wasmtime ​

Wasmer ​

Project Configuration Example ​

Build Tools

Build Cache Tools

.NET SDK & MSBuild

.NET SDK

MSBuild (Bundled with .NET SDK)

C/C++ Compilers

MSVC Build Tools (Windows)

vcpkg - C++ Package Manager

Installation

vx-Managed Cache Directories

What `vx lock` Pins

Uninstalling

Installing C++ Packages

Common Packages for Native Node.js Modules

Integration with MSVC

Environment Variables

Using with CMake

vx.toml Configuration

Task Runners

Just

Task (go-task)

Build Systems

CMake

Ninja

protoc

Frontend Build Tools

Vite

Rust WebAssembly Build Tools

Trunk

wasm-pack

WebAssembly Runtimes

Wasmtime

Wasmer

Project Configuration Example