Run on Linux

Linux is the primary host for Visao. The instructions below also apply on macOS.

Installation from tarball

After receiving the release tarball:

tar xzf visao-<version>-linux-x86_64.tar.gz -C /opt/
cd /opt/visao
ls
# bin/  lib/  stdlib/  dockerfile/

Add the bin directory to PATH for the current shell:

export PATH="/opt/visao/bin:$PATH"

For a permanent setup, append the same line to ~/.bashrc, ~/.zshrc, or your shell’s per-user init file. Multi-user installs typically drop a file under /etc/profile.d/ instead.

The bin folder also contains visaotest, the gtest runner. You can leave it on PATH. It checks the install.

Smoke test

visao --version
echo 'int main(void) { return 0; }' > /tmp/hello.c
visao --language c /tmp/hello.c

Both commands complete without errors. The first prints a version line with the git short hash. The second prints engine progress in dim, no reports, and a final ✓ Finished successfully · NNN ms line.

Toolchain prep

Linux distributions usually have at least one of gcc/clang on PATH. Confirm that Visao sees them and prime the cache:

visao --update-toolchains

To diagnose probe selection, set VISAO_DETAILED_TOOLCHAIN=y for one run:

VISAO_DETAILED_TOOLCHAIN=y visao --language c /tmp/hello.c 2>&1 | less

This prints every probe command, every (cpu, os) combination it considered, and the reasoning behind the eventual match.

Cross-target compilers

To register a non-host GCC (for example an arm-none-eabi cross toolchain) without putting it on PATH, pass --compiler-path per invocation:

visao --compiler-path "gcc:/opt/arm-none-eabi/bin/arm-none-eabi-gcc" \
      --cpu arm --os linux --language c \
      -I include -- firmware/*.c

Headers for the cross target come from the cross-toolchain itself during the probe. Use --isystem for SDK headers that live outside the cross-toolchain tree.

Where files end up

The release tarball does not create files outside its install root. User-level state goes to:

• $XDG_CONFIG_HOME/visao/tccache.txt (defaults to $HOME/.config/visao/tccache.txt). This file holds the toolchain probe cache.

Probing uses /dev/null directly as input, so a temporary probe.c never reaches disk.