CMake Fallback

vix.app does not remove CMake.

It gives Vix a simpler project description for common C++ projects, while keeping CMake available for advanced projects.

vix.app        -> simple path
CMakeLists.txt -> full control path

Resolution order

Vix resolves projects in this order:

1. CMakeLists.txt
2. vix.app

This means:

If CMakeLists.txt exists, Vix uses CMakeLists.txt.
If CMakeLists.txt does not exist but vix.app exists, Vix uses vix.app.

So a project like this uses CMake:

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

A project like this uses vix.app:

myapp/
  vix.app
  src/
    main.cpp

Why CMake has priority

CMake has priority because it is the advanced compatibility path.

If a project already has a CMakeLists.txt, Vix assumes the project needs or wants that CMake configuration.

This avoids breaking existing projects.

Existing CMake projects keep working.
vix.app is used only when no CMakeLists.txt exists.

How vix.app works internally

When Vix detects a vix.app project, it generates an internal CMake project.

The generated file is written under:

.vix/generated/app/CMakeLists.txt

Then Vix builds that generated CMake project.

The flow is:

vix.app
  -> .vix/generated/app/CMakeLists.txt
  -> cmake configure
  -> cmake build

Do not edit generated CMake

Do not edit this file manually:

.vix/generated/app/CMakeLists.txt

It is generated by Vix.

If you need to change the build, edit:

vix.app

The generated CMake file can be replaced the next time Vix regenerates the project.

Example vix.app project

Project layout:

hello/
  vix.app
  src/
    main.cpp

vix.app:

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

sources = [
  src/main.cpp,
]

Build:

vix build

Run:

vix run

Vix generates:

hello/.vix/generated/app/CMakeLists.txt

and builds the project from there.

Example CMake project

Project layout:

hello/
  CMakeLists.txt
  src/
    main.cpp

CMakeLists.txt:

cmake_minimum_required(VERSION 3.24)

project(hello LANGUAGES CXX)

add_executable(hello
  src/main.cpp
)

target_compile_features(hello PRIVATE cxx_std_20)

Build:

vix build

Run:

vix run

Vix uses the existing CMakeLists.txt.

If both files exist

If your project has both:

CMakeLists.txt
vix.app

Vix uses:

CMakeLists.txt

The vix.app file is ignored for project resolution.

To test vix.app, rename the CMake file:

mv CMakeLists.txt CMakeLists.txt.bak

Then run:

vix build
vix run

Switching from vix.app to CMake

You can start with vix.app and move to CMake later.

For example, start with:

myapp/
  vix.app
  src/
    main.cpp

Later, when you need full control, add:

CMakeLists.txt

After that, Vix will use CMakeLists.txt.

No special command is needed.

Switching from CMake to vix.app

To switch a simple CMake project to vix.app, create a vix.app file and rename the old CMakeLists.txt.

Example:

mv CMakeLists.txt CMakeLists.txt.bak
touch vix.app

Then write your manifest:

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

sources = [
  src/main.cpp,
]

Build:

vix build

Why vix.app still generates CMake

vix.app is a simpler interface.

CMake is still the compatibility layer underneath.

This gives you:

- simple project configuration
- compatibility with existing C++ build tools
- readable generated CMake for debugging
- a smooth migration path to full CMake

The user experience stays simple, while the ecosystem remains compatible.

vix.app is not a second CMake

vix.app is intentionally small.

It is not meant to support every CMake feature.

It supports common project needs:

- one target
- sources
- include directories
- definitions
- links
- compile options
- link options
- packages
- resources
- output directory

For advanced logic, use CMakeLists.txt.

When CMake fallback is the right choice

Use CMakeLists.txt when your project needs:

- multiple targets in one build file
- custom commands
- generated source files
- install rules
- CTest integration
- FetchContent
- CPM.cmake
- custom toolchains
- custom CMake functions
- platform-specific branches
- package export files
- advanced dependency logic

These are full build-system concerns.

They belong in CMake.

When vix.app is enough

Use vix.app when your project is simple and direct.

Good examples:

- CLI applications
- simple examples
- small libraries
- demos
- prototypes
- learning projects
- small apps with a few dependencies

Example:

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

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

include_dirs = [
  include,
]

Debugging generated CMake

If a vix.app project fails to configure or build, inspect the generated CMake file:

.vix/generated/app/CMakeLists.txt

You can also run:

vix build -v

or:

vix build --cmake-verbose

Use --cmake-verbose when you need raw CMake configure output.

Passing CMake arguments

You can pass extra CMake arguments after --.

Example:

vix build -- -DCMAKE_PREFIX_PATH=/path/to/prefix

This is useful when packages are installed in custom locations.

Example with a custom package prefix:

vix build -- -DCMAKE_PREFIX_PATH=$HOME/local

Package fallback

If a package cannot be found from vix.app, the problem is usually still a CMake package discovery issue.

Example:

packages = [
  fmt:REQUIRED,
]

links = [
  fmt::fmt,
]

If CMake cannot find fmt, you may need:

vix build -- -DCMAKE_PREFIX_PATH=/path/to/fmt

or a normal CMakeLists.txt if the package needs custom setup.

CMake fallback and packages

Remember:

packages -> find_package(...)
links    -> target_link_libraries(...)

packages only finds packages.

It does not link imported targets automatically.

Correct:

packages = [
  fmt:REQUIRED,
]

links = [
  fmt::fmt,
]

Incorrect:

packages = [
  fmt:REQUIRED,
]

CMake fallback and resources

For simple resource copying, use:

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

For complex resource workflows, use CMake.

Examples that may need CMake:

- generated assets
- compressed resources
- embedded binary data
- custom copy commands
- platform-specific resource logic

CMake fallback and tests

For simple tests, use a separate tests/vix.app.

Example:

mathlib/
  vix.app
  tests/
    vix.app
    test_math.cpp

For advanced test infrastructure, use CMake.

Examples:

- CTest
- GoogleTest discovery
- many test targets
- generated test data
- custom fixtures

CMake fallback and multiple targets

vix.app describes one target.

For multiple targets, use one of these approaches:

- one folder with one vix.app per target
- one normal CMakeLists.txt for the full project

Example with one manifest per target:

workspace/
  apps/
    server/
      vix.app
    client/
      vix.app
  libs/
    mathlib/
      vix.app

Example with full CMake control:

workspace/
  CMakeLists.txt
  apps/
    server/
  libs/
    mathlib/

Generated CMake location

For a vix.app project, generated files live under:

.vix/generated/app/

Typical generated file:

.vix/generated/app/CMakeLists.txt

This folder is internal build metadata.

You usually should not commit it.

Should .vix/generated be committed?

Usually, no.

Recommended .gitignore entry:

.vix/generated/

You should commit:

vix.app

You should not commit:

.vix/generated/app/CMakeLists.txt

unless you are debugging or intentionally snapshotting generated output.

Build directories

vix.app still uses normal Vix build directories.

Examples:

build-ninja/
build-dev/
build-release/

Release build:

vix build --preset release

With:

output_dir = bin

you may get:

build-release/bin/myapp

Common mistakes

Expecting vix.app to be used while CMakeLists.txt exists

If this exists:

CMakeLists.txt

Vix uses it.

To use vix.app, rename the CMake file:

mv CMakeLists.txt CMakeLists.txt.bak

Editing generated CMake manually

Do not edit:

.vix/generated/app/CMakeLists.txt

Edit:

vix.app

Trying to express complex CMake logic in vix.app

If the build needs advanced CMake logic, use CMakeLists.txt.

Do not force vix.app to become a second CMake language.

Forgetting links after packages

This is not enough:

packages = [
  fmt:REQUIRED,
]

Correct:

packages = [
  fmt:REQUIRED,
]

links = [
  fmt::fmt,
]

Recommended rule

Use this rule when choosing between vix.app and CMake:

If the build is simple, use vix.app.
If the build needs custom logic, use CMakeLists.txt.

Another way to think about it:

vix.app is the simple path.
CMakeLists.txt is the compatibility path.

Summary

vix.app is a simple project manifest.

CMake remains available for full control.

Resolution order:

1. CMakeLists.txt
2. vix.app

Generated CMake path:

.vix/generated/app/CMakeLists.txt

Do not edit generated files manually.

Use CMakeLists.txt when your project becomes too complex for a small manifest.

Next steps

Continue with:

• Troubleshooting
• Migrating from CMake
• Manifest Reference
• Best Practices