Output Directory

vix.app supports output_dir to control where the built target is placed inside the build tree.

This is useful when you want a predictable output layout such as:

build-ninja/bin/myapp

Basic usage

name = hello
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
]

Build:

vix build

The executable can be placed under:

build-ninja/bin/hello

Run:

vix run

What output_dir means

output_dir is relative to the CMake build directory.

Example:

output_dir = bin

means:

${CMAKE_BINARY_DIR}/bin

So with the default Vix build directory:

build-ninja/

the final output becomes:

build-ninja/bin/

Default output location

If you do not set output_dir, the output location depends on the generated CMake project and the selected build system.

Example without output_dir:

name = hello
type = executable
standard = c++20

sources = [
  src/main.cpp,
]

The executable may be produced under:

build-ninja/hello

or another CMake-managed location depending on the target type and generator.

For predictable output, use:

output_dir = bin

Recommended app layout

Project:

hello/
  vix.app
  src/
    main.cpp

vix.app:

name = hello
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
]

After build:

hello/
  build-ninja/
    bin/
      hello

output_dir with resources

resources are copied next to the built target.

So if you use:

output_dir = bin

and:

resources = [
  assets,
]

the output can look like this:

build-ninja/
  bin/
    myapp
    assets/

Complete example:

name = myapp
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
]

resources = [
  assets,
]

Example with config files

Project layout:

config_app/
  vix.app
  src/
    main.cpp
  config/
    app.json

vix.app:

name = config_app
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
]

resources = [
  config,
]

After build:

build-ninja/
  bin/
    config_app
    config/
      app.json

Running manually

If you want to run the executable manually:

./build-ninja/bin/config_app

If your program reads files using relative paths, remember that the current working directory matters.

For example:

std::ifstream file("config/app.json");

will look for config/app.json relative to the process working directory, not always relative to the executable file.

vix run and output_dir

vix run tries to resolve the built executable automatically.

For a manifest like this:

name = myapp
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
]

vix run can find common executable locations such as:

build-ninja/myapp
build-ninja/bin/myapp
build-ninja/src/myapp

So you can usually run:

vix run

without manually typing the executable path.

output_dir for static libraries

You can also use output_dir with static libraries.

Example:

name = mathlib
type = static
standard = c++20
output_dir = lib

sources = [
  src/add.cpp,
  src/mul.cpp,
]

include_dirs = [
  include,
]

The static library output can be placed under:

build-ninja/lib/

output_dir for shared libraries

For shared libraries:

name = plugin
type = shared
standard = c++20
output_dir = lib

sources = [
  src/plugin.cpp,
]

include_dirs = [
  include,
]

The shared library output can be placed under:

build-ninja/lib/

Depending on the platform, the final file may look like:

libplugin.so

libplugin.dylib

plugin.dll

Multiple presets

Vix uses different build directories depending on the preset.

Default development build:

vix build

usually uses:

build-ninja/

Release build:

vix build --preset release

uses:

build-release/

So with:

output_dir = bin

you can get:

build-ninja/bin/myapp

and:

build-release/bin/myapp

output_dir is not an install directory

output_dir controls where the target is placed inside the build directory.

It is not the same as an install prefix.

This:

output_dir = bin

does not install your application globally.

It only affects the build output layout.

For advanced install rules, use a normal CMakeLists.txt.

Avoid absolute output paths

Prefer relative paths:

output_dir = bin

Avoid absolute paths:

output_dir = /usr/local/bin

vix.app is designed for local project builds.

Use install tools or CMake install rules when you need system-wide installation.

Recommended values

For applications:

output_dir = bin

For libraries:

output_dir = lib

For tests:

output_dir = bin

Examples:

name = myapp
type = executable
output_dir = bin

name = mathlib
type = static
output_dir = lib

name = mathlib_tests
type = executable
output_dir = bin

Complete executable example

name = server
type = executable
standard = c++20
output_dir = bin

sources = [
  src/main.cpp,
  src/server.cpp,
]

include_dirs = [
  include,
]

resources = [
  public,
  config,
]

After build:

build-ninja/
  bin/
    server
    public/
    config/

Complete library example

name = mathlib
type = static
standard = c++20
output_dir = lib

sources = [
  src/add.cpp,
  src/mul.cpp,
]

include_dirs = [
  include,
]

After build:

build-ninja/
  lib/
    libmathlib.a

The exact library file name depends on the platform and toolchain.

Complete test example

name = mathlib_tests
type = executable
standard = c++20
output_dir = bin

sources = [
  test_math.cpp,
  ../src/add.cpp,
  ../src/mul.cpp,
]

include_dirs = [
  ../include,
]

resources = [
  data,
]

After build from the tests/ folder:

tests/
  build-ninja/
    bin/
      mathlib_tests
      data/

Run:

vix run

Common mistakes

Expecting output_dir to be relative to the source directory

Incorrect expectation:

output_dir = bin

creates:

project/bin/myapp

Actual behavior:

project/build-ninja/bin/myapp

output_dir is relative to the build directory.

Expecting output_dir to install the binary

output_dir does not install binaries into system paths.

It only controls the build output location.

Use CMake install rules for installation workflows.

Forgetting resources move with output_dir

If you set:

output_dir = bin

and:

resources = [
  assets,
]

then check:

build-ninja/bin/assets/

not:

build-ninja/assets/

Running manually from the wrong directory

If your app expects:

config/app.json

and the file is under:

build-ninja/bin/config/app.json

then running from the project root may not find it unless your app resolves paths relative to the executable.

Troubleshooting

Executable not found

Check the target name:

name = myapp

Then check common output locations:

build-ninja/myapp
build-ninja/bin/myapp
build-release/bin/myapp

Resource not found

Check whether you set output_dir.

With:

output_dir = bin

resources are copied near:

build-ninja/bin/

Wrong preset directory

If you built with:

vix build --preset release

check:

build-release/

not:

build-ninja/

Summary

Use output_dir when you want predictable build outputs.

For applications:

output_dir = bin

For libraries:

output_dir = lib

Remember:

output_dir is relative to the build directory.
resources are copied next to the built target.
vix run can usually find the executable automatically.

Next steps

Continue with:

• Resources
• Examples
• Libraries
• Troubleshooting