Skip to content

debug.md

Latest commit

 

History

History
762 lines (518 loc) · 11.1 KB

debug.md

File metadata and controls

762 lines (518 loc) · 11.1 KB
Raw

Debug Example

This page shows a small debug example using the public Rix facade.

The example uses:

#include <rix.hpp>

and accesses debug helpers through:

rix.debug

Use this example when you want simple printing, formatting, and inspection from a small C++ file.

For real Vix applications, prefer the Vix logging system for application logs.

Create the file

mkdir -p ~/rix-debug-example
cd ~/rix-debug-example
touch debug.cpp

Add:

#include <rix.hpp>

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

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

  rix.debug.print(package);

  rix.debug.print("loaded debug APIs:", 4);
  rix.debug.eprint("warning:", "this is printed to stderr");

  rix.debug.inspect(package);

  return 0;
}

Run it:

vix run debug.cpp

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

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

Expected output shape:

Hello Rix
Package: rix/rix
loaded debug APIs: 4
"Package: rix/rix"

The warning line is printed to stderr.

What this example does

The example prints values with:

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

It formats a string with:

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

It prints an error or warning-style message to stderr with:

rix.debug.eprint("warning:", "this is printed to stderr");

It inspects a value with:

rix.debug.inspect(package);

Print values

Use rix.debug.print to print values separated by spaces:

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

Output:

Hello Rix

You can pass several values:

rix.debug.print("name:", "Ada", "language:", "C++");

Output shape:

name: Ada language: C++

Print to stderr

Use rix.debug.eprint for stderr output:

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

Use this for examples, small tools, and visible failure messages.

For real Vix application logs, prefer the Vix logging system.

Debug-only print

Use rix.debug.dprint for debug-only printing:

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

Use this when you want temporary debug output during development.

Format strings

Use rix.debug.format to create a string from placeholders:

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

Then:

rix.debug.print(message);

Output:

Hello, Rix

Automatic placeholders

Use {} for automatic argument order:

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

Output:

Rix uses C++

Explicit placeholders

Use {0}, {1}, and other indexes for explicit argument positions:

const auto message = rix.debug.format(
    "{0} is built for {1}. {0} keeps examples simple.",
    "Rix",
    "C++");

Output:

Rix is built for C++. Rix keeps examples simple.

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

Escaped braces

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

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

```txt id="d9v6np"
{ package } = rix/rix

Unsupported format specifiers

The debug formatter intentionally stays small.

This is not supported:

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

Use simple placeholders:

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

Format into an existing string

You can write formatted output into an existing string:

std::string out;

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

rix.debug.print(out);

Append formatted output

Use append when you want to add formatted text to an existing string:

std::string out = "Result: ";

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

rix.debug.print(out);

Output:

Result: ok

Format complete example

#include <rix.hpp>

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

  const auto api = rix.debug.format(
      "{0} exposes print, format, and inspect helpers.",
      "rix/debug");

  rix.debug.print(package);
  rix.debug.print(api);

  std::string out;

  rix.debug.format.to(
      out,
      "Status: {}",
      "ready");

  rix.debug.print(out);

  rix.debug.format.append(
      out,
      " / rows: {}",
      3);

  rix.debug.print(out);

  return 0;
}

Run:

vix run debug.cpp

Inspect values

Use rix.debug.inspect to inspect a value:

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

rix.debug.inspect(package);

Inspection is useful when you want to see a value in a more debug-oriented form.

Sprint values

Use rix.debug.sprint to create a string from printed values:

const auto message = rix.debug.sprint(
    "name:",
    "Ada",
    "language:",
    "C++");

rix.debug.print(message);

This is useful when you want print-style rendering but need the result as a string.

Debug with CSV

#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());

  for (const auto &row : table)
  {
    rix.debug.inspect(row);
  }

  return 0;
}

Run:

vix run debug.cpp

Debug with auth

#include <rix.hpp>

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

  auto registered = auth.register_user({
      "ada@example.com",
      "correct-password"});

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

    return 1;
  }

  rix.debug.print("registered:", registered.value().email());
  rix.debug.print("user id:", registered.value().id());

  return 0;
}

Use debug output to make examples easier to understand.

Do not print passwords, session ids, or token values in production logs.

Debug with PDF

#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, "debug-pdf.pdf");

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

    return 1;
  }

  rix.debug.print("created:", "debug-pdf.pdf");
  return 0;
}

Use in a Vix project

Create a project:

vix new rix-debug-example --app
cd rix-debug-example

Add Rix:

vix add rix/rix
vix install

Make sure vix.app contains:

deps = [
  "rix/rix",
]

A minimal vix.app can look like this:

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

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

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

deps = [
  "rix/rix",
]

packages = [
  "vix",
]

links = [
  "vix::vix",
]

Put the example code in:

src/main.cpp

Build and run:

vix build
vix run

Single-file usage

For examples, tests, and quick experiments:

vix run debug.cpp

If needed:

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

For project usage, prefer:

vix add rix/rix
vix install

and keep the dependency in vix.app:

deps = [
  "rix/rix",
]

Use only debug with the facade

If you want the rix.* facade style but only want debug mounted, define the feature macro before including rix.hpp:

#define RIX_ENABLE_DEBUG
#include <rix.hpp>

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

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

Use the independent package

For independent usage, install:

vix add rix/debug
vix install

In vix.app:

deps = [
  "rix/debug",
]

Then include the debug package header directly:

#include <rix/debug.hpp>

Use this style when a project only needs debug and does not need the full unified Rix facade.

For most examples in this documentation, prefer:

#include <rix.hpp>

About logging

rix.debug contains small debug helpers for examples and development output.

For real Vix applications, prefer the Vix logging system.

Use:

rix.debug.print(...)
rix.debug.eprint(...)
rix.debug.format(...)
rix.debug.inspect(...)

for documentation examples, quick experiments, and simple tools.

Use Vix logging for application logs, production diagnostics, and runtime logging.

Common mistakes

Forgetting to install Rix

If rix.hpp is not found, install Rix first.

For a project:

vix add rix/rix
vix install

For single-file usage:

vix install -g rix/rix

Putting Rix in packages

Wrong:

packages = [
  "rix/rix",
]

Correct:

deps = [
  "rix/rix",
]

deps is for Vix Registry packages.

packages is for CMake package discovery.

Mixing placeholder styles

Wrong:

rix.debug.format("{} uses {1}", "Rix", "C++");

Use automatic placeholders:

rix.debug.format("{} uses {}", "Rix", "C++");

or explicit placeholders:

rix.debug.format("{0} uses {1}", "Rix", "C++");

Do not mix both styles in one string.

Using unsupported format specifiers

Wrong:

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

Correct:

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

Printing sensitive values

Avoid printing passwords, raw tokens, and session ids in production.

For docs and examples, keep output simple and safe.

Using debug output as production logging

For examples:

rix.debug.print(...)

For real Vix applications, prefer the Vix logging system.

What you should remember

Use the facade:

#include <rix.hpp>

Print values:

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

Print to stderr:

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

Format strings:

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

Inspect values:

rix.debug.inspect(text);

Run a simple file:

vix run debug.cpp

For project usage:

vix add rix/rix
vix install

and keep:

deps = [
  "rix/rix",
]

Next step

Continue with the PDF examples.

Next: PDF example