Debug API Reference

This page summarizes the public API exposed by rix/debug.

The documentation examples use the unified Rix facade:

cpp

#include <rix.hpp>

and access Debug through:

cpp

rix.debug

The lower-level debug helpers live under:

cpp

rixlib
rixlib::debug

Use the facade for application code and documentation examples.

Facade entry point

The Debug module is mounted at:

cpp

rix.debug

Common usage:

cpp

rix.debug.print("Hello", "Rix");

const auto message =
    rix.debug.format("Package: {}", "rix/debug");

rix.debug.print(message);

rix.debug.inspect(message);

Headers

Recommended public header:

cpp

#include <rix.hpp>

Independent package header:

cpp

#include <rix/debug.hpp>

Use <rix.hpp> when you want the unified facade:

cpp

rix.csv
rix.debug
rix.auth
rix.pdf

Use <rix/debug.hpp> when you only need the independent debug package.

Namespace

The object-style Debug API lives in:

cpp

rixlib::debug

The simple free helpers live in:

cpp

rixlib

Common public names:

cpp

rixlib::debug::Debug
rixlib::debug::Format
rixlib::debug::Log
rixlib::debug::Inspect
rixlib::format_error

`rix.debug`

rix.debug exposes the public debug facade.

It provides:

cpp

rix.debug.print(...)
rix.debug.eprint(...)
rix.debug.dprint(...)
rix.debug.sprint(...)

rix.debug.format(...)
rix.debug.format.append(...)
rix.debug.format.to(...)

rix.debug.log(...)
rix.debug.log.info(...)
rix.debug.log.warn(...)
rix.debug.log.error(...)

rix.debug.inspect(...)

Use it for examples, development-time output, quick diagnostics, and small tools.

For production application logs, prefer the Vix logging system.

`print`

cpp

template <typename... Args>
void print(const Args &...args) const;

Prints values to stdout, separated by spaces, followed by a newline.

Example:

cpp

rix.debug.print("Hello", "Rix");
rix.debug.print("rows:", 3);
rix.debug.print("ready:", true);

Output shape:

txt

Hello Rix
rows: 3
ready: true

Use print for simple development output and documentation examples.

`eprint`

cpp

template <typename... Args>
void eprint(const Args &...args) const;

Prints values to stderr.

Example:

cpp

rix.debug.eprint("error:", "something failed");

Use eprint for local error output in examples and small command-line tools.

`dprint`

cpp

template <typename... Args>
void dprint(const Args &...args) const;

Writes debug-only output.

Example:

cpp

rix.debug.dprint("debug value:", 42);

Use it for messages that are only useful while developing.

`sprint`

cpp

template <typename... Args>
std::string sprint(const Args &...args) const;

Returns the same value rendering style as print, but as a string.

Example:

cpp

const auto line =
    rix.debug.sprint("rows:", 3);

rix.debug.print(line);

Output:

txt

rows: 3

Use sprint when you want to build a line before printing, storing, or passing it to another API.

`format`

cpp

template <typename... Args>
std::string operator()(
    std::string_view fmt,
    const Args &...args) const;

Creates a formatted string using Rix placeholder syntax.

Example:

cpp

const auto message =
    rix.debug.format("Package: {}", "rix/debug");

rix.debug.print(message);

Output:

txt

Package: rix/debug

format returns a std::string.

It does not print by itself.

Automatic placeholders

Use {} to consume arguments in order:

cpp

const auto message =
    rix.debug.format("{} uses {}", "Rix", "C++");

Output:

txt

Rix uses C++

Each {} uses the next argument.

Explicit placeholders

Use {0}, {1}, and other numeric indexes when the position should be explicit:

cpp

const auto message =
    rix.debug.format("{0} + {0} = {1}", "C++", "Vix.cpp");

Output:

txt

C++ + C++ = Vix.cpp

Do not mix automatic placeholders and explicit placeholders in the same format string.

Escaped braces

Use double opening braces and double closing braces when you need literal braces:

cpp

const auto message =
    rix.debug.format("{{ package }} = {}", "rix/debug");

Output:

txt

{ package } = rix/debug

Unsupported format specifiers

rix.debug.format intentionally supports a small placeholder syntax.

It does not support format specifiers such as:

txt

{:>10}
{:.2f}
{:04d}

Wrong:

cpp

rix.debug.format("{:.2f}", 3.14159);

Use:

cpp

rix.debug.format("value: {}", 3.14159);

For advanced formatting, use another formatting library or normal C++ formatting tools where appropriate.

`format.append`

cpp

template <typename... Args>
void append(
    std::string &out,
    std::string_view fmt,
    const Args &...args) const;

Appends formatted output to an existing string.

Example:

cpp

std::string out = "Rix: ";

rix.debug.format.append(
    out,
    "{}",
    "debug");

rix.debug.print(out);

Output:

txt

Rix: debug

Use append when building a string in steps.

`format.to`

cpp

template <typename... Args>
void to(
    std::string &out,
    std::string_view fmt,
    const Args &...args) const;

Replaces the destination string with formatted output.

Example:

cpp

std::string out = "old value";

rix.debug.format.to(
    out,
    "Package: {}",
    "rix/debug");

rix.debug.print(out);

Output:

txt

Package: rix/debug

The previous content of out is cleared.

`format_error`

cpp

rixlib::format_error

format_error is thrown on invalid format strings or invalid argument access.

Invalid examples:

cpp

rix.debug.format("{", "Rix");
rix.debug.format("}", "Rix");
rix.debug.format("{2}", "Rix");
rix.debug.format("{} {0}", "Rix");
rix.debug.format("{:.2f}", 3.14);

Handle errors when the format string may come from outside your code:

cpp

try
{
  const auto message =
      rix.debug.format("{} {}", "Rix", "Debug");

  rix.debug.print(message);
}
catch (const rixlib::format_error &error)
{
  rix.debug.eprint("format error:", error.what());
  return 1;
}

`log`

cpp

template <typename... Args>
void operator()(
    std::string_view fmt,
    const Args &...args) const;

Writes a debug-level formatted message.

Example:

cpp

rix.debug.log("loaded {} rows", 3);

Output:

txt

[debug] loaded 3 rows

rix.debug.log is a development helper.

For real application logging, prefer vix::log.

`log.info`

cpp

template <typename... Args>
void info(
    std::string_view fmt,
    const Args &...args) const;

Writes an info-level message to stdout.

Example:

cpp

rix.debug.log.info("package {} is ready", "rix/debug");

Output:

txt

[info] package rix/debug is ready

`log.warn`

cpp

template <typename... Args>
void warn(
    std::string_view fmt,
    const Args &...args) const;

Writes a warning-level message to stdout.

Example:

cpp

rix.debug.log.warn("slow path: {}", "csv import");

Output:

txt

[warn] slow path: csv import

`log.error`

cpp

template <typename... Args>
void error(
    std::string_view fmt,
    const Args &...args) const;

Writes an error-level message to stderr.

Example:

cpp

rix.debug.log.error("failed to open {}", "missing.csv");

Output shape:

txt

[error] failed to open missing.csv

Logging recommendation

Use rix.debug.log for:

txt

examples
small command-line demos
local diagnostics
quick package tests
development-only output

Use Vix logging for:

txt

HTTP request logs
service startup logs
deployment diagnostics
production logs
structured application logs
runtime observability

Rule:

txt

rix.debug.log -> development helper
vix::log      -> application logging

`inspect`

cpp

rix.debug.inspect(value);

Inspects a value during development.

Example:

cpp

std::string package = "rix/debug";

rix.debug.inspect(package);

Inspection is useful when you want a clearer development-time view of a value.

For normal output, use print.

For formatted messages, use format.

Complete API example

cpp

#include <rix.hpp>

#include <string>

int main()
{
  rix.debug.print("Hello", "Rix");
  rix.debug.eprint("stderr:", "example");

  const std::string package =
      rix.debug.format("Package: {}", "rix/debug");

  rix.debug.print(package);

  std::string line = "Rix: ";

  rix.debug.format.append(
      line,
      "{}",
      "debug");

  rix.debug.print(line);

  rix.debug.format.to(
      line,
      "module: {}",
      "debug");

  rix.debug.print(line);

  const auto printed =
      rix.debug.sprint("rows:", 3);

  rix.debug.inspect(printed);

  rix.debug.log.info("loaded {} APIs", 4);

  return 0;
}

Run:

bash

vix run debug.cpp

Use with CSV

cpp

#include <rix.hpp>

int main()
{
  const auto table = rix.csv.parse(
      "name,language\n"
      "Ada,C++\n"
      "Gaspard,Vix\n");

  rix.debug.print("rows:", table.size());
  rix.debug.log.info("loaded {} rows", table.size());

  for (const auto &row : table)
  {
    rix.debug.print("fields:", row.size());
  }

  return 0;
}

Use with Auth errors

cpp

#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto login = auth.login({
      "ada@example.com",
      "wrong-password"});

  if (login.failed())
  {
    const auto &error = login.error();

    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(error),
        error.message());

    return 1;
  }

  return 0;
}

Do not print or log authentication secrets.

Avoid:

txt

plain-text passwords
password hashes
session ids
raw token values
private keys
API tokens

Use with PDF errors

cpp

#include <rix.hpp>

int main()
{
  auto doc = rix.pdf.document();

  auto &page = doc.add_page();

  page.text(
      page.x_left(),
      page.y_top(),
      "Hello from rix.pdf");

  auto saved = rix.pdf.save(doc, "");

  if (saved.failed())
  {
    rix.debug.eprint(
        "pdf error:",
        rix.pdf.error.to_string(saved.error()),
        saved.error().message());

    return 1;
  }

  rix.debug.print("created:", "example.pdf");

  return 0;
}

Single-file usage

For quick examples:

bash

vix run debug.cpp

If Rix is not available yet for single-file usage:

bash

vix install -g rix/rix
vix run debug.cpp

Project usage

For a Vix project, add Rix:

bash

vix add rix/rix
vix install

In vix.app:

txt

deps = [
  "rix/rix",
]

A small manifest can look like this:

txt

name = "debug-app"
type = "executable"
standard = "c++20"
output_dir = "bin"

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

include_dirs = [
  "include",
  "src",
]

deps = [
  "rix/rix",
]

packages = [
  "vix",
]

links = [
  "vix::vix",
]

Build and run:

bash

vix build
vix run

Independent package usage

If the project only needs Debug, install:

bash

vix add rix/debug
vix install

In vix.app:

txt

deps = [
  "rix/debug",
]

Then include:

cpp

#include <rix/debug.hpp>

Use this style when you do not need the unified rix.* facade.

Lightweight facade usage

If you want the unified facade but only want Debug mounted:

cpp

#define RIX_ENABLE_DEBUG
#include <rix.hpp>

int main()
{
  rix.debug.print("Hello", "Rix");
  return 0;
}

When at least one RIX_ENABLE_* macro is defined, only selected modules are mounted.

Common mistakes

Expecting `print` to replace placeholders

Wrong:

cpp

rix.debug.print("Package: {}", "rix/debug");

Use format:

cpp

rix.debug.print(
    rix.debug.format("Package: {}", "rix/debug"));

or use the debug logger:

cpp

rix.debug.log.info("Package: {}", "rix/debug");

Mixing placeholder styles

Wrong:

cpp

rix.debug.format("{} {0}", "Rix");

Use automatic placeholders:

cpp

rix.debug.format("{} {}", "Rix", "Debug");

or explicit placeholders:

cpp

rix.debug.format("{0} {1}", "Rix", "Debug");

Using unsupported format specifiers

Wrong:

cpp

rix.debug.format("{:.2f}", 3.14159);

Use simple placeholders:

cpp

rix.debug.format("value: {}", 3.14159);

Using debug log as production logging

rix.debug.log is a small development helper.

For deployed Vix.cpp applications, prefer Vix logging.

Printing secrets

Do not print, inspect, or log:

txt

plain-text passwords
password hashes
session ids
raw token values
private keys
API tokens

Forgetting `deps`

For a Vix project, do not put Rix packages in packages.

Wrong:

txt

packages = [
  "rix/rix",
]

Correct:

txt

deps = [
  "rix/rix",
]

deps is for Vix Registry packages.

packages is for CMake package discovery.

API summary

Main facade:

cpp

rix.debug.print(...)
rix.debug.eprint(...)
rix.debug.dprint(...)
rix.debug.sprint(...)

rix.debug.format(...)
rix.debug.format.append(...)
rix.debug.format.to(...)

rix.debug.log(...)
rix.debug.log.info(...)
rix.debug.log.warn(...)
rix.debug.log.error(...)

rix.debug.inspect(...)

Main types:

cpp

rixlib::debug::Debug
rixlib::debug::Format
rixlib::debug::Log
rixlib::debug::Inspect
rixlib::format_error

Recommended include:

cpp

#include <rix.hpp>

Independent include:

cpp

#include <rix/debug.hpp>

What you should remember

Use print for simple output:

cpp

rix.debug.print("Hello", "Rix");

Use eprint for stderr:

cpp

rix.debug.eprint("error:", "message");

Use format for placeholders:

cpp

auto message = rix.debug.format("Package: {}", "rix/debug");

Use sprint for print-style strings:

cpp

auto line = rix.debug.sprint("rows:", 3);

Use inspect to examine values:

cpp

rix.debug.inspect(value);

Use rix.debug.log only as a development helper.

Prefer Vix logging for real application logs.

For a Vix project, install Rix:

bash

vix add rix/rix
vix install

and use:

txt

deps = [
  "rix/rix",
]

Next step

Continue with the PDF package.

Next: PDF

Debug API Reference ​

Facade entry point ​

Headers ​

Namespace ​

rix.debug ​

print ​

eprint ​

dprint ​

sprint ​

format ​

Automatic placeholders ​

Explicit placeholders ​

Escaped braces ​

Unsupported format specifiers ​

format.append ​

format.to ​

format_error ​

log ​

log.info ​

log.warn ​

log.error ​

Logging recommendation ​

inspect ​

Complete API example ​

Use with CSV ​

Use with Auth errors ​

Use with PDF errors ​

Single-file usage ​

Project usage ​

Independent package usage ​

Lightweight facade usage ​

Common mistakes ​

Expecting print to replace placeholders ​

Mixing placeholder styles ​

Using unsupported format specifiers ​

Using debug log as production logging ​

Printing secrets ​

Forgetting deps ​

API summary ​

What you should remember ​

Next step ​

Debug API Reference

Facade entry point

Headers

Namespace

`rix.debug`

`print`

`eprint`

`dprint`

`sprint`

`format`

Automatic placeholders

Explicit placeholders

Escaped braces

Unsupported format specifiers

`format.append`

`format.to`

`format_error`

`log`

`log.info`

`log.warn`

`log.error`

Logging recommendation

`inspect`

Complete API example

Use with CSV

Use with Auth errors

Use with PDF errors

Single-file usage

Project usage

Independent package usage

Lightweight facade usage

Common mistakes

Expecting `print` to replace placeholders

Mixing placeholder styles

Using unsupported format specifiers

Using debug log as production logging

Printing secrets

Forgetting `deps`

API summary

What you should remember

Next step