← All questions

"Unknown VM", "Unexpected backend name: cpp", and RAKUPP_VM_NAME

A few modules check which virtual machine they run on, and stop if it is not one they know. On Raku++ that check sees cpp, so they stop with messages like these:

Unknown VM; don't know how to build
Unexpected backend name: cpp

This page explains what the messages mean, the environment variable that gets past them, and when that variable is the right thing to use. The other places the two engines differ are in where Raku++ and Rakudo differ, and installing modules in general is in installing and finding modules.

Checked 2026-10-18 with Raku++ 5.4.1 (main) and Rakudo v2026.09.

rakupp install LibraryMake fails with "Unknown VM; don't know how to build" #

$ rakupp install LibraryMake
…
testing LibraryMake: 1 file
FAILED: 01-basic.t
  Unknown VM; don't know how to build
    in sub get-vars at …/lib/LibraryMake.rakumod line 161
    in block <unit> at …/t/01-basic.t line 7

LibraryMake: its own test suite fails under rakupp — not installing (--no-test to override)

Install it with the variable set:

RAKUPP_VM_NAME=moar rakupp install LibraryMake

You need the variable once, for this one install. LibraryMake is a build helper: 29 distributions in the ecosystem depend on it, most of them to compile their C code when they are installed. Among them are LibXML, Font::FreeType, Digest::SHA1::Native, Math::DistanceFunctions::Native and Math::SparseMatrix::Native. Once LibraryMake is in the store, those install with a plain rakupp install, because the installer already gives their build step the name it expects (below). Only LibraryMake's own test suite asks the question outside a build step.

rakupp install --no-test LibraryMake installs it too, but without running the test. With the variable the test runs and passes.

Why does $*VM.name say cpp? #

It names the backend that runs the program, as it does in Rakudo:

say $*VM.name;
say $*RAKU.VMnames;

Raku++   cpp      (cpp js)
Rakudo   moar     (moar jvm js)

cpp is the interpreter and --exe; a program compiled with --target=js answers js. Rakudo answers moar on MoarVM and jvm on the JVM.

A module that checks for moar usually does it to read build settings out of $*VM.config: the C compiler, the object-file suffix, how a shared library is named. Raku++ fills $*VM.config with this machine's real toolchain, so the code in the moar branch works here, and the name is the only thing in the way:

say $*VM.config<cc obj dll ldshared>;

Raku++   (cc .o lib%s.dylib -dynamiclib)
Rakudo   (clang .o lib%s.dylib -dynamiclib)

(macOS; on Linux the library is lib%s.so and the flag -shared.)

What exactly does RAKUPP_VM_NAME change? #

Three answers, and nothing else:

$ RAKUPP_VM_NAME=moar rakupp -e 'say $*VM.name; say $*RAKU.compiler.backend; say $*RAKU.VMnames'
moar
moar
(cpp js moar)

• $*VM.name answers the value you gave.
• $*RAKU.compiler.backend answers it too. In Rakudo the two are the same string, and a module that reads one of them must not find the other one saying something different.
• The value is added to $*RAKU.VMnames, so $*VM.name eq any($*RAKU.VMnames) still holds.

$*VM.config stays as it was, and so does the engine. The variable adds no nqp:: operations and no MoarVM internals, so a module that really needs MoarVM gets further and then fails anyway. An empty value is ignored, and the name stays cpp. Rakudo has no such variable: it answers moar with the variable set or not.

Why is moar not the default? #

Because it is not true, and other programs ask the same question for other reasons. A program that sees moar may take a path written for MoarVM, use nqp:: operations that only exist there, or report the wrong backend in a bug report. The default is the honest answer, and the variable is for when you have looked at a module and decided its moar branch is the right one here.

There is one place the installer answers moar on its own: the build step of a distribution, a Build.rakumod or a builder named in META6.json. The ecosystem's build recipes read their toolchain behind a moar check and have no other branch, and that step is the installer's own work. Nothing outside it sees the name: not your programs, and not the distribution's test suite. That is why LibraryMake's dependents build without the variable, and why LibraryMake itself, which has no build step but tests its own recipe, does not.

It worked before, or it works on another machine #

Up to v3.x, $*VM.name answered moar; since v4.0.0 it answers cpp. A LibraryMake installed before that stays installed, so a machine set up earlier has it, and a fresh machine cannot install it without the variable. rakupp install --list shows what a store already holds.

Do I have to keep the variable set? #

For LibraryMake, no: only the install needs it. For a module that checks the name every time it is loaded, yes, on every run. uniprop is one: it checks in a BEGIN block, so use uniprop dies on Raku++ without the variable.

export RAKUPP_VM_NAME=moar      # for the rest of this shell session

With the variable set, uniprop installs, loads and answers:

$ RAKUPP_VM_NAME=moar rakupp -e 'use uniprop; say uniprop-str("a", "Script")'
Latin

That needs a Raku++ newer than 5.4.1. In 5.4.1 the module loads, but its three subs die with X::Multi::NoMatch: an engine bug in how they are declared, since fixed. If you only need what uniprop's subs answer, the uniprop method and sub built into the language do the same, on both engines and with no variable:

say "a".uniprop("Script");             # Latin
say uniprop(0x31, "Numeric_Value");    # 1

Which modules need it? #

The ones known today:

NativeHelpers::Blob used to be on this list. The installer now ships its own copy, and installs it as provided by rakupp with no variable needed.

If another module dies with a message like the ones at the top of this page, look at the line it names. If that line checks $*VM.name, try the run with RAKUPP_VM_NAME=moar, and report the module at https://github.com/ash/rakupp/issues either way, so it can be listed here.