Getting Started with vix.app

This guide shows how to create a small C++ project with vix.app.

A vix.app project does not need a handwritten CMakeLists.txt.

You describe the project in a small manifest file, then Vix builds and runs it.

Create the project

Create a new folder:

mkdir hello-vix-app
cd hello-vix-app

Create the source directory:

mkdir -p src

Create the main file:

touch src/main.cpp

Add this code to src/main.cpp:

#include <vix.hpp>

int main()
{
  vix::print("Hello from vix.app");
  return 0;
}

Create vix.app

Create a file named vix.app in the project root:

touch vix.app

Add this content:

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

sources = [
  src/main.cpp,
]

Your project should now look like this:

hello-vix-app/
  vix.app
  src/
    main.cpp

Build the project

Run:

vix build

Vix will detect vix.app, generate an internal CMake project, and build your application.

The generated CMake project is written under:

.vix/generated/app/CMakeLists.txt

You should not edit this generated file manually.

Edit vix.app instead.

Run the project

Run:

vix run

Vix will build the project if needed, then run the executable.

Expected output:

Hello from vix.app

Use an include directory

For a slightly more realistic project, add an include/ directory:

mkdir -p include/hello
touch include/hello/message.hpp

Add this to include/hello/message.hpp:

#pragma once

#include <string>

namespace hello
{
  inline std::string message()
  {
    return "Hello from a header file";
  }
}

Update src/main.cpp:

#include <vix.hpp>
#include <hello/message.hpp>

int main()
{
  vix::print(hello::message());
  return 0;
}

Update vix.app:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

Build and run again:

vix build
vix run

Add compile definitions

You can add preprocessor definitions with defines:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

defines = [
  HELLO_VERSION="1.0.0",
  HELLO_DEBUG=1,
]

Example usage in C++:

#include <vix.hpp>

#ifndef HELLO_VERSION
#define HELLO_VERSION "unknown"
#endif

int main()
{
  vix::print("Version:", HELLO_VERSION);
  return 0;
}

Add compiler options

You can add compiler flags with compile_options:

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

sources = [
  src/main.cpp,
]

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

These options are passed to the generated target.

Set an output directory

Use output_dir to place the built executable in a specific build output folder:

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

sources = [
  src/main.cpp,
]

After building, the executable will be placed under:

build-ninja/bin/

Run it with:

vix run

or manually:

./build-ninja/bin/hello

Use packages and links

packages is used for find_package(...).

links is used for target_link_libraries(...).

For example, to use Threads:

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

sources = [
  src/main.cpp,
]

packages = [
  Threads:REQUIRED,
]

links = [
  Threads::Threads,
]

Important rule:

packages finds packages.
links links targets or libraries.

packages does not automatically link imported targets.

Add resources

Resources are copied next to the built target after a successful build.

Example:

mkdir -p assets
echo "hello config" > assets/config.txt

Update vix.app:

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

sources = [
  src/main.cpp,
]

resources = [
  assets,
]

After building, assets/ will be copied next to the executable.

Build presets

vix build uses embedded Vix presets.

Common commands:

vix build

vix build --preset dev

vix build --preset release

Default behavior usually uses the development Ninja build directory:

build-ninja/

Release builds use:

build-release/

Project detection rule

Vix resolves projects in this order:

1. CMakeLists.txt
2. vix.app

If both files exist, Vix uses CMakeLists.txt.

If you want Vix to use vix.app, do not keep a CMakeLists.txt in the same project root.

Complete minimal example

hello/
  vix.app
  src/
    main.cpp

vix.app:

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

sources = [
  src/main.cpp,
]

src/main.cpp:

#include <vix.hpp>

int main()
{
  vix::print("Hello from vix.app");
  return 0;
}

Commands:

vix build
vix run

Next steps

Continue with:

• Manifest Reference
• Examples
• Packages and Links
• Tests