Manifest Reference

This page documents every field supported by vix.app.

A vix.app file is a simple manifest placed at the root of a project.

Example:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

File format

vix.app uses a simple key-value format.

Supported forms:

key = value

key = [value1, value2, value3]

key = [
  value1,
  value2,
  value3,
]

Comments are supported with #:

# This is a comment
name = hello # inline comment

Values can be quoted when needed:

sources = [
  "src/with space.cpp",
]

Use quotes when a value contains spaces, commas, or special characters.

Resolution rule

Vix resolves project files in this order:

1. CMakeLists.txt
2. vix.app

If CMakeLists.txt exists, Vix uses it directly.

If no CMakeLists.txt exists but vix.app exists, Vix uses vix.app.

Supported fields

Field	Required	Description
name	Yes	Target name
type	No	Target type
standard	No	C++ standard
sources	Yes	Source files
include_dirs	No	Include directories
defines	No	Preprocessor definitions
links	No	Libraries or CMake targets to link
compile_options	No	Compiler flags
link_options	No	Linker flags
compile_features	No	CMake compile features
packages	No	Packages passed to find_package(...)
resources	No	Files or directories copied after build
output_dir	No	Output directory inside the build tree

name

Required.

The name field defines the target name.

name = hello

Vix uses this name as the default build target.

For example:

name = hello
type = executable

generates a target named hello.

This name is also used by vix run to find the executable after building.

Recommended rules:

- Use letters, numbers, `_`, or `-`
- Avoid spaces
- Keep the name short and stable

Good examples:

name = hello

name = mathlib

name = softadastra_server

Avoid:

name = "my app"

type

Optional.

Default:

type = executable

The type field defines what kind of target Vix should generate.

Supported values:

type = executable

type = static

type = static-library

type = shared

type = shared-library

type = library

executable

Creates an executable application.

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

sources = [
  src/main.cpp,
]

static

Creates a static library.

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

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

shared

Creates a shared library.

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

sources = [
  src/plugin.cpp,
]

library

Creates a library target using the default library behavior supported by Vix.

name = core
type = library
standard = c++20

sources = [
  src/core.cpp,
]

standard

Optional.

Default:

standard = c++20

The standard field defines the C++ language standard.

Supported values:

standard = c++17

standard = c++20

standard = c++23

Example:

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

sources = [
  src/main.cpp,
]

This sets the generated CMake target to use the selected C++ standard.

sources

Required.

The sources field lists the source files used by the target.

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

Source paths are relative to the directory containing vix.app.

Example layout:

myapp/
  vix.app
  src/
    main.cpp
    app.cpp

Manifest:

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

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

Inline array syntax is also supported:

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

If a path contains spaces, quote it:

sources = [
  "src/my file.cpp",
]

If a source file does not exist, Vix reports an error before generating the CMake project.

include_dirs

Optional.

The include_dirs field lists include directories.

include_dirs = [
  include,
  third_party/asio/include,
]

Example layout:

myapp/
  vix.app
  include/
    myapp/
      app.hpp
  src/
    main.cpp

Manifest:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

C++ usage:

#include <myapp/app.hpp>

Include paths are relative to the directory containing vix.app.

defines

Optional.

The defines field adds preprocessor definitions.

defines = [
  MYAPP_VERSION="1.0.0",
  MYAPP_ENABLE_LOGGING=1,
]

Example:

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

sources = [
  src/main.cpp,
]

defines = [
  MYAPP_VERSION="1.0.0",
  MYAPP_DEBUG=1,
]

C++ usage:

#ifndef MYAPP_VERSION
#define MYAPP_VERSION "unknown"
#endif

Definitions are passed to the generated target.

links

Optional.

The links field lists libraries or CMake targets to link.

links = [
  Threads::Threads,
  fmt::fmt,
  m,
]

Use links for:

- CMake imported targets
- system libraries
- local library targets
- simple linker library names

Example:

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

sources = [
  src/main.cpp,
]

packages = [
  Threads:REQUIRED,
]

links = [
  Threads::Threads,
]

Important:

packages finds packages.
links links targets or libraries.

packages does not link automatically.

compile_options

Optional.

The compile_options field adds compiler options to the target.

compile_options = [
  -Wall,
  -Wextra,
  -Wpedantic,
]

Example:

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

sources = [
  src/main.cpp,
]

compile_options = [
  -Wall,
  -Wextra,
  -Wpedantic,
]

You can also write:

compile_options = [-Wall, -Wextra, -Wpedantic]

Compiler options can be platform-specific.

For example, GCC or Clang options may not work with MSVC.

link_options

Optional.

The link_options field adds linker options to the target.

link_options = [
  "-Wl,--as-needed",
]

Quote values that contain commas:

link_options = [
  "-Wl,--as-needed",
]

Example:

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

sources = [
  src/main.cpp,
]

link_options = [
  "-Wl,--as-needed",
]

Linker options are toolchain-specific.

compile_features

Optional.

The compile_features field adds CMake compile features to the target.

compile_features = [
  cxx_std_20,
]

Example:

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

sources = [
  src/main.cpp,
]

compile_features = [
  cxx_std_20,
]

Common values:

cxx_std_17
cxx_std_20
cxx_std_23

In most projects, standard is enough.

Use compile_features when you need explicit CMake feature declarations.

packages

Optional.

The packages field generates find_package(...) calls in the internal CMake project.

packages = [
  Threads:REQUIRED,
  fmt:REQUIRED,
  "Boost:COMPONENTS=system,filesystem:REQUIRED",
]

Supported forms:

<name>
<name>:REQUIRED
<name>:COMPONENTS=a,b
<name>:COMPONENTS=a,b:REQUIRED

Examples:

packages = [
  Threads,
]

packages = [
  Threads:REQUIRED,
]

packages = [
  "Boost:COMPONENTS=system,filesystem",
]

packages = [
  "Boost:COMPONENTS=system,filesystem:REQUIRED",
]

Important:

packages only calls find_package(...).
It does not link the imported targets automatically.

You must link imported targets through links.

Correct:

packages = [
  fmt:REQUIRED,
]

links = [
  fmt::fmt,
]

Incorrect:

packages = [
  fmt:REQUIRED,
]

The incorrect example finds fmt, but does not link fmt::fmt.

resources

Optional.

The resources field copies files or directories next to the built target after a successful build.

resources = [
  assets,
  "data/config.json=config/config.json",
]

Supported forms:

<src>
<src>=<dest>

Copy with basename

resources = [
  assets,
]

This copies assets next to the built target.

Copy with custom destination

resources = [
  "data/config.json=config/config.json",
]

This copies:

data/config.json

to:

config/config.json

next to the built target.

Common use cases:

- assets
- config files
- templates
- public files
- development certificates

output_dir

Optional.

The output_dir field controls where the built target is placed inside the build tree.

output_dir = bin

Example:

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

sources = [
  src/main.cpp,
]

After building, the executable can be placed under:

build-ninja/bin/hello

If output_dir is relative, Vix resolves it relative to the CMake build directory.

For example:

output_dir = bin

means:

${CMAKE_BINARY_DIR}/bin

Complete example

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

sources = [
  src/main.cpp,
  src/app.cpp,
  src/network/client.cpp,
]

include_dirs = [
  include,
  third_party/asio/include,
]

defines = [
  MYAPP_VERSION="1.2.3",
  MYAPP_ENABLE_LOGGING=1,
]

packages = [
  Threads:REQUIRED,
  fmt:REQUIRED,
  "Boost:COMPONENTS=system,filesystem:REQUIRED",
]

links = [
  Threads::Threads,
  fmt::fmt,
  Boost::system,
  Boost::filesystem,
]

compile_options = [
  -Wall,
  -Wextra,
  -Wpedantic,
]

link_options = [
  "-Wl,--as-needed",
]

compile_features = [
  cxx_std_23,
]

resources = [
  assets,
  "data/config.json=config/config.json",
]

Minimal example

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

sources = [
  src/main.cpp,
]

Static library example

name = mathlib
type = static
standard = c++17

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

include_dirs = [
  include,
]

Shared library example

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

sources = [
  src/plugin.cpp,
]

include_dirs = [
  include,
]

Common mistakes

Missing sources

Incorrect:

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

Correct:

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

sources = [
  src/main.cpp,
]

Package found but target not linked

packages only calls find_package(...).

You still need to link the imported target:

packages = [fmt:REQUIRED]
links = [fmt::fmt]

Source path is wrong

Incorrect:

sources = [
  main.cpp,
]

when your file is actually here:

src/main.cpp

Correct:

sources = [
  src/main.cpp,
]

CMakeLists.txt exists

If your project has both:

CMakeLists.txt
vix.app

Vix uses CMakeLists.txt.

To use vix.app, remove or rename CMakeLists.txt.

Next steps

Continue with:

• Examples
• Packages and Links
• Sources and Includes
• Troubleshooting