Rix is the official package layer for Vix.cpp Browse packages
Rix/Docs
Rix

Appearance

Facade vs Independent Packages ​

This guide explains the difference between using the unified Rix facade and using an independent Rix package directly.

Rix supports both styles.

Use the facade when you want the normal public Rix API:

cpp
#include <rix.hpp>

and:

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

Use an independent package when you intentionally want only one package:

cpp
#include <rix/pdf.hpp>

and:

cpp
auto pdf = rixlib::pdf::module();

The short version ​

Use rix/rix for application code and documentation examples.

Use rix/name directly when a project only needs one package and does not need the full facade.

txt
Unified facade        -> rix/rix  -> <rix.hpp>      -> rix.*
Independent package   -> rix/pdf  -> <rix/pdf.hpp>  -> rixlib::pdf::module()

Unified facade ​

The unified facade is the package:

txt
rix/rix

Install it with:

bash
vix add rix/rix
vix install

Use it with:

cpp
#include <rix.hpp>

Then access packages through the global rix object:

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

Independent package ​

An independent package is a focused package such as:

txt
rix/auth
rix/csv
rix/debug
rix/pdf

Install one package directly:

bash
vix add rix/pdf
vix install

Use its header directly:

cpp
#include <rix/pdf.hpp>

Then create the package module:

cpp
auto pdf = rixlib::pdf::module();

Facade example ​

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 through the facade");

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

  return saved.ok() ? 0 : 1;
}

This style is short and readable.

It is the preferred style for most Rix documentation.

Independent package example ​

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

  auto &page = doc.add_page();

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

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

  return saved.ok() ? 0 : 1;
}

This style is useful when the project only needs rix/pdf.

Main difference ​

The difference is not the PDF feature itself.

The difference is the entry point.

Facade:

cpp
#include <rix.hpp>

rix.pdf.document()

Independent:

cpp
#include <rix/pdf.hpp>

auto pdf = rixlib::pdf::module();
pdf.document()

Both styles use the same package underneath.

When to use the facade ​

Use the facade when:

txt
you are writing application code
you want one include
you use more than one Rix package
you want rix.auth, rix.csv, rix.debug, rix.pdf
you are writing documentation examples
you want the public Rix style

Example:

cpp
#include <rix.hpp>

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

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

  auto doc = rix.pdf.document();

  rix.debug.print("rows:", table.size());

  return 0;
}

When to use an independent package ​

Use an independent package when:

txt
you only need one package
you want a smaller dependency scope
you are building a focused library
you do not need the global rix facade
you want direct package ownership in the file

Example:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

  return pdf.save(doc, "output.pdf").ok() ? 0 : 1;
}

Project dependency for facade usage ​

For facade usage, add:

bash
vix add rix/rix
vix install

In vix.app:

txt
deps = [
  "rix/rix",
]

Then include:

cpp
#include <rix.hpp>

Project dependency for independent usage ​

For independent usage, add only the package you need.

Example for PDF:

bash
vix add rix/pdf
vix install

In vix.app:

txt
deps = [
  "rix/pdf",
]

Then include:

cpp
#include <rix/pdf.hpp>

Do not put Rix packages in packages ​

Rix packages belong in deps.

Wrong:

txt
packages = [
  "rix/rix",
]

Correct:

txt
deps = [
  "rix/rix",
]

For independent usage:

txt
deps = [
  "rix/pdf",
]

deps is for Vix Registry packages.

packages is for CMake package discovery.

Facade naming ​

The facade follows this model:

txt
Registry package  -> rix/rix
Header            -> <rix.hpp>
Access            -> rix.*

Examples:

cpp
rix.auth.memory()
rix.csv.parse(...)
rix.debug.print(...)
rix.pdf.document()

This is the normal public Rix style.

Independent naming ​

Independent packages follow this model:

txt
Registry package  -> rix/name
Header            -> <rix/name.hpp>
Namespace         -> rixlib::name
Module helper     -> rixlib::name::module()

Example for PDF:

txt
Registry package  -> rix/pdf
Header            -> <rix/pdf.hpp>
Namespace         -> rixlib::pdf
Module helper     -> rixlib::pdf::module()

Side-by-side comparison ​

NeedUseInstallIncludeAccess
Normal app usageFacaderix/rix<rix.hpp>rix.*
Multiple packagesFacaderix/rix<rix.hpp>rix.auth, rix.pdf
Docs and examplesFacaderix/rix<rix.hpp>rix.*
One focused packageIndependentrix/name<rix/name.hpp>rixlib::name::module()
Smaller dependency scopeIndependentrix/name<rix/name.hpp>package module

Facade with auth ​

cpp
#include <rix.hpp>

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

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

  return registered.ok() ? 0 : 1;
}

Install:

bash
vix add rix/rix
vix install

In vix.app:

txt
deps = [
  "rix/rix",
]

Facade with CSV ​

cpp
#include <rix.hpp>

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

  rix.debug.print("rows:", table.size());

  return 0;
}

This uses both rix.csv and rix.debug, so the facade is a good fit.

Facade with PDF ​

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

  return saved.ok() ? 0 : 1;
}

This is the preferred style for PDF examples in the Rix docs.

Independent PDF ​

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

  auto &page = doc.add_page();

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

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

  return saved.ok() ? 0 : 1;
}

Install:

bash
vix add rix/pdf
vix install

In vix.app:

txt
deps = [
  "rix/pdf",
]

Independent debug ​

cpp
#include <rix/debug.hpp>

int main()
{
  auto debug = rixlib::debug::module();

  debug.print("Hello from rix/debug");

  return 0;
}

Use this style only when the independent package exposes a module helper.

For most examples, prefer:

cpp
#include <rix.hpp>

and:

cpp
rix.debug.print(...)

Lightweight facade ​

The facade can be reduced with feature macros.

Example:

cpp
#define RIX_ENABLE_PDF
#define RIX_ENABLE_DEBUG
#include <rix.hpp>

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

  rix.debug.print("PDF ready");

  return 0;
}

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

This gives a middle path between full facade and fully independent package usage.

Default facade behavior ​

If no feature macro is defined, all currently mounted modules are enabled.

This means:

cpp
#include <rix.hpp>

gives access to:

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

This keeps simple examples short and backward-compatible.

Feature macro examples ​

Only PDF:

cpp
#define RIX_ENABLE_PDF
#include <rix.hpp>

PDF and debug:

cpp
#define RIX_ENABLE_PDF
#define RIX_ENABLE_DEBUG
#include <rix.hpp>

Auth only:

cpp
#define RIX_ENABLE_AUTH
#include <rix.hpp>

CSV and debug:

cpp
#define RIX_ENABLE_CSV
#define RIX_ENABLE_DEBUG
#include <rix.hpp>

Available macros include:

txt
RIX_ENABLE_AUTH
RIX_ENABLE_CSV
RIX_ENABLE_DEBUG
RIX_ENABLE_PDF

Which style should docs use? ​

Rix docs should start with the public facade.

Use:

cpp
#include <rix.hpp>

and:

cpp
rix.pdf.document()
rix.auth.memory()
rix.csv.parse(...)
rix.debug.print(...)

Then show independent package usage later as an alternative.

This keeps the docs consistent and teaches one public style first.

Which style should applications use? ​

Most applications should use:

bash
vix add rix/rix
vix install

Then:

cpp
#include <rix.hpp>

This gives the cleanest application code.

Use independent packages only when the app has a clear reason to avoid the unified facade.

Which style should libraries use? ​

A focused library can use an independent package when it only needs one Rix package.

Example:

bash
vix add rix/pdf
vix install

Then:

cpp
#include <rix/pdf.hpp>

This avoids depending on the full facade when the library only needs PDF types or PDF generation.

Single-file usage with facade ​

Create a file:

bash
mkdir -p ~/rix-facade-example
cd ~/rix-facade-example
touch main.cpp

Add:

cpp
#include <rix.hpp>

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

Run:

bash
vix run main.cpp

If Rix is not available globally:

bash
vix install -g rix/rix
vix run main.cpp

Single-file usage with independent package ​

Create a file:

bash
mkdir -p ~/rix-independent-example
cd ~/rix-independent-example
touch main.cpp

Add:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

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

  return saved.ok() ? 0 : 1;
}

Run:

bash
vix run main.cpp

If the package is not available globally:

bash
vix install -g rix/pdf
vix run main.cpp

Project usage with facade ​

bash
vix new facade-app --app
cd facade-app
vix add rix/rix
vix install

In vix.app:

txt
deps = [
  "rix/rix",
]

In src/main.cpp:

cpp
#include <rix.hpp>

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

Build and run:

bash
vix build
vix run

Project usage with independent package ​

bash
vix new independent-pdf-app --app
cd independent-pdf-app
vix add rix/pdf
vix install

In vix.app:

txt
deps = [
  "rix/pdf",
]

In src/main.cpp:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

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

  return saved.ok() ? 0 : 1;
}

Build and run:

bash
vix build
vix run

Migration from independent package to facade ​

Before:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

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

  return saved.ok() ? 0 : 1;
}

After:

cpp
#include <rix.hpp>

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

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

  return saved.ok() ? 0 : 1;
}

Update vix.app:

txt
deps = [
  "rix/rix",
]

instead of:

txt
deps = [
  "rix/pdf",
]

Migration from facade to independent package ​

Before:

cpp
#include <rix.hpp>

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

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

  return saved.ok() ? 0 : 1;
}

After:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

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

  return saved.ok() ? 0 : 1;
}

Update vix.app:

txt
deps = [
  "rix/pdf",
]

instead of:

txt
deps = [
  "rix/rix",
]

Avoid mixing styles without a reason ​

This is usually unnecessary:

cpp
#include <rix.hpp>
#include <rix/pdf.hpp>

If you use the facade, prefer:

cpp
#include <rix.hpp>

and:

cpp
rix.pdf

If you use the independent package, prefer:

cpp
#include <rix/pdf.hpp>

and:

cpp
auto pdf = rixlib::pdf::module();

Keep one style per file unless there is a clear reason.

Common mistakes ​

Using the independent include but writing facade code ​

Wrong:

cpp
#include <rix/pdf.hpp>

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

Correct independent usage:

cpp
#include <rix/pdf.hpp>

int main()
{
  auto pdf = rixlib::pdf::module();

  auto doc = pdf.document();

  return 0;
}

Or use the facade:

cpp
#include <rix.hpp>

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

  return 0;
}

Installing rix/pdf but including <rix.hpp> ​

If the project uses:

cpp
#include <rix.hpp>

then install the facade package:

bash
vix add rix/rix
vix install

and keep:

txt
deps = [
  "rix/rix",
]

Installing rix/rix but expecting only one package ​

rix/rix is the unified facade.

If you want only PDF, use:

bash
vix add rix/pdf
vix install

or use the lightweight facade macros with rix/rix.

Putting Rix packages in packages ​

Wrong:

txt
packages = [
  "rix/pdf",
]

Correct:

txt
deps = [
  "rix/pdf",
]

Using rix.debug.log as production logging ​

rix.debug is useful for examples and development output.

For real Vix applications, prefer the Vix logging system.

What you should remember ​

Facade style:

bash
vix add rix/rix
vix install
cpp
#include <rix.hpp>

rix.pdf.document()

Independent style:

bash
vix add rix/pdf
vix install
cpp
#include <rix/pdf.hpp>

auto pdf = rixlib::pdf::module();

Use deps in vix.app:

txt
deps = [
  "rix/rix",
]

or:

txt
deps = [
  "rix/pdf",
]

For most Rix docs and application examples, prefer:

cpp
#include <rix.hpp>

and:

cpp
rix.*

Next step ​

Continue with feature macros.

Next: Feature macros

Released under the MIT License.

Copyright © 2026 Rix