Resources

vix.app supports copying resource files or directories next to the built target.

Use the resources field when your application needs files at runtime.

Common examples:

assets/
config.json
templates/
public/
data/

Basic example

Project layout:

asset_app/
  vix.app
  src/
    main.cpp
  assets/
    message.txt

vix.app:

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

sources = [
  src/main.cpp,
]

resources = [
  assets,
]

Build:

vix build

The assets directory is copied next to the built target.

If the executable is placed under:

build-ninja/bin/asset_app

then the resources are copied near it:

build-ninja/bin/assets/

Why resources exist

C++ applications often need runtime files.

For example:

- images
- JSON config files
- templates
- static web files
- certificates for local development
- test data
- language files

Without resource copying, you may build the executable successfully but fail at runtime because files are missing.

resources solves this by copying required files after a successful build.

Copy a directory

To copy a whole directory, list it under resources:

resources = [
  assets,
]

Example layout:

myapp/
  vix.app
  src/
    main.cpp
  assets/
    logo.png
    config.json

After build:

build-ninja/
  bin/
    myapp
    assets/
      logo.png
      config.json

Copy a single file

You can copy a single file:

resources = [
  config.json,
]

Example layout:

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

After build:

build-ninja/
  myapp
  config.json

or, when output_dir = bin is used:

build-ninja/
  bin/
    myapp
    config.json

Copy with a custom destination

You can copy a resource to a custom destination using:

source=destination

Example:

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

This copies:

data/config.json

to:

config/config.json

next to the built target.

Example output:

build-ninja/
  bin/
    myapp
    config/
      config.json

Multiple resources

You can copy several resources:

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

This is useful for applications with several runtime directories.

Complete example

Project layout:

myapp/
  vix.app
  src/
    main.cpp
  assets/
    logo.txt
  data/
    config.json

vix.app:

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

sources = [
  src/main.cpp,
]

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

src/main.cpp:

#include <vix.hpp>

#include <fstream>
#include <string>

int main()
{
  std::ifstream file("config/config.json");

  if (!file)
  {
    vix::print("config file not found");
    return 1;
  }

  std::string content;
  std::getline(file, content);

  vix::print("config:", content);
  return 0;
}

Build and run:

vix build
vix run

Resources and output_dir

resources are copied next to the built target.

If you do not set output_dir, the target is usually built under the build directory:

build-ninja/

If you set:

output_dir = bin

then the target is placed under:

build-ninja/bin/

and resources are copied there.

Example:

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

sources = [
  src/main.cpp,
]

resources = [
  assets,
]

Output:

build-ninja/
  bin/
    myapp
    assets/

Resources and vix run

vix run runs the built executable.

Because resources are copied next to the executable, your app can read them using paths relative to the executable location or runtime working directory, depending on how your app handles paths.

For simple apps, keep resource access predictable.

Example:

config/config.json
assets/logo.png

Avoid hardcoding absolute paths.

Resource paths are relative to vix.app

Resource source paths are relative to the directory containing vix.app.

Example:

myapp/
  vix.app
  assets/
    logo.png

Correct:

resources = [
  assets,
]

Incorrect:

resources = [
  myapp/assets,
]

because vix.app is already inside myapp/.

Resources inside tests

Tests can also use resources.

Project layout:

myapp/
  tests/
    vix.app
    test_config.cpp
    data/
      config.json

tests/vix.app:

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

sources = [
  test_config.cpp,
]

resources = [
  data,
]

Build and run:

cd tests
vix run

The test data is copied next to the test executable.

Custom destination for tests

Example:

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

This lets the test read:

config/config.json

instead of:

data/config.json

Resource syntax

Supported forms:

<src>
<src>=<dest>

Form 1: source only

resources = [
  assets,
]

This copies assets using its original basename.

Form 2: source and destination

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

This copies the source to a custom destination next to the built target.

Quoting resources

Quote resource values when they contain special characters.

Recommended:

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

Also quote paths with spaces:

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

For clean projects, avoid spaces in resource paths when possible.

Directory resources

When the source is a directory, Vix copies the directory.

Example:

resources = [
  assets,
]

Input:

assets/
  logo.png
  style.css

Output:

assets/
  logo.png
  style.css

File resources

When the source is a file, Vix copies the file.

Example:

resources = [
  config.json,
]

Input:

config.json

Output:

config.json

Renaming files

Use src=dest to rename a file.

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

This copies:

data/dev.json

as:

config.json

next to the built target.

Nesting files

Use src=dest to place a file inside a directory.

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

Output:

config/
  dev.json

Recommended structure

For applications:

myapp/
  vix.app
  src/
    main.cpp
  include/
    myapp/
      app.hpp
  assets/
    logo.png
  config/
    app.json

Manifest:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

resources = [
  assets,
  config,
]

Web server example

For a small web server, you may want to copy static files.

Project layout:

webapp/
  vix.app
  src/
    main.cpp
  public/
    index.html
    app.css

vix.app:

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

sources = [
  src/main.cpp,
]

resources = [
  public,
]

After build:

build-ninja/
  bin/
    webapp
    public/
      index.html
      app.css

Config file example

Project layout:

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

vix.app:

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

sources = [
  src/main.cpp,
]

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

After build:

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

What resources should not be used for

Do not use resources for files that need to be compiled.

For source files, use:

sources = [
  src/main.cpp,
]

For include directories, use:

include_dirs = [
  include,
]

For runtime files, use:

resources = [
  assets,
]

Generated resources

If your resources are generated before build, make sure they exist before running:

vix build

For complex generated resources, use a normal CMakeLists.txt.

Examples that may need CMake:

- generated assets
- code generation
- resource compression
- embedding binary files
- custom copy rules

Common mistakes

Resource path does not exist

Incorrect:

resources = [
  asset,
]

when the real directory is:

assets/

Correct:

resources = [
  assets,
]

Expecting resources to compile

Incorrect:

resources = [
  src/main.cpp,
]

Correct:

sources = [
  src/main.cpp,
]

Forgetting output_dir location

If you use:

output_dir = bin

your executable and resources are under:

build-ninja/bin/

not directly under:

build-ninja/

Using absolute runtime paths

Avoid code like:

std::ifstream file("/home/user/project/config.json");

Prefer relative resource paths or application-controlled runtime paths.

Troubleshooting

Config file not found at runtime

Check where the executable is built.

If you use:

output_dir = bin

look under:

build-ninja/bin/

Check that the resource was copied there.

Resource copied but app still cannot find it

Your app may be running with a different working directory.

Either:

- open files relative to the executable location
- run from the output directory
- use a runtime config path
- pass a path through command-line arguments

Directory copied but content missing

Check that the files exist before build.

Also check that your path is relative to the directory containing vix.app.

Summary

Use resources for runtime files.

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

Use output_dir when you want a predictable output folder:

output_dir = bin

Recommended app pattern:

myapp/
  vix.app
  src/
  include/
  assets/
  config/

Recommended manifest:

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

sources = [
  src/main.cpp,
]

include_dirs = [
  include,
]

resources = [
  assets,
  config,
]

Next steps

Continue with:

• Output Directory
• Examples
• Tests
• Troubleshooting