REGINA-HELPER(1)

💖 REGINA-HELPER(1) 💖

okay bestie, gather round, because this is the regina-helper page from The Regina Handbook and it's genuinely one of the most useful little gremlins in the whole Regina ecosystem 🫶

---

✨ SYNOPSIS ✨

regina-helper action [ args ... ]

regina-helper action [ --help ]

---

🌸 DESCRIPTION 🌸

So here's the tea ☕ — this utility knows things. It understands the layout of your Regina installation, and it will happily help you with a whole bunch of tasks that need that knowledge. Like, it can write Makefiles for you, generate sample C++ code, or help you run Regina's test suite. it's giving personal assistant, honestly 💅

The first argument to regina-helper should be an action, and that's what tells the utility what you actually want it to do. All the available actions are described in detail below 👇 and if you wanna know more about any single one of them, you can just run regina-helper action --help. iconic behaviour, truly.

This utility is available in most but not all settings:

• If you're on GNU/Linux and Regina is installed in a system location (like, beneath /usr/ or /usr/local/), then regina-helper should be included with your installation, and any output it produces should be relative to that system installation. slay 🐧
• If you're on macOS and you're running Regina from an app bundle (maybe under /Applications/, maybe somewhere else entirely, no judgement), then you can run regina-helper from within the app bundle at .../Regina.app/Contents/MacOS/regina-helper, and any output it produces should be relative to this app bundle. 🍎
• If you're building Regina yourself from the source tree (any platform, we don't discriminate), then you can run regina-helper from the source tree, and any output it produces should be relative to that same source tree. And specifically? It will not assume that you have actually installed Regina. no assumptions, we love that for us ✨
• If you're using pre-built packages for Regina on Windows, then regina-helper will not be included in your installation. 💀 that's just how it is bestie.

---

👑 ACTIONS 👑

The first argument to regina-helper should be one of these:

🎀 installtype

Writes a single token to standard output identifying the type of Regina installation.

example$ regina-helper installtype
XDG
example$

The output will be one of the following:

• XDG — Indicates that you are running Regina from an installation in a fixed location that follows the freedesktop.org layout. You see this with Regina's GNU/Linux packages, as well as local CMake builds with no special arguments.
• HPC — Indicates that you are running Regina from a slimmed-down installation (e.g., no GUI or HTML docs) which is installed in a fixed but possibly non-standard location, suitable for builds on high-performance computing systems. You typically see this with local CMake builds where REGINA_INSTALL_TYPE was explicitly set to HPC. supercomputer energy 🔥
• Bundle — Indicates that you are running Regina from within a macOS app bundle.
• Windows — Indicates that you are running Regina from within Regina's Windows app. It is unlikely that you will see this of course, since regina-helper is not shipped with Windows installations. 😭
• Source — Indicates that you are running Regina directly from the source tree (i.e., a local build that has not necessarily been installed).

The installtype action takes no additional arguments.

---

🧚 makefile

Creates a Makefile in the current directory, suitable for compiling C++ programs against Regina. And once you've got that Makefile in place, you can (for example) compile a C++ program foo.cc just by running make foo. periodt 💅

The main reason to use this Makefile is that it includes compiler and linker flags for accessing Regina's C++ calculation engine. (And specifically, using this Makefile is a simpler alternative to extracting compiler and linker flags from regina-engine-config.)

The makefile action accepts the optional arguments --force and/or --rpath; those are described below 👇

---

🌈 cc, cpp

Creates a Makefile in the current directory that is suitable for compiling C++ programs against Regina, plus a sample C++ program you can use as a starting point for your own code. two for one, we love a deal 🫶

example$ regina-helper cc
Writing sample.cc...
Preparing Makefile...
example$ ls
Makefile  sample.cc
example$

See the makefile action above for further discussion of how you can use this Makefile.

The C++ source file will be called either sample.cc or sample.cpp, depending on whether you gave cc or cpp as the action argument to regina-helper. yes, the action name literally picks your file extension, iykyk ✨

The cc / cpp action accepts the optional arguments --force and/or --rpath; those are described below 👇

---

⭐ test

Runs Regina's detailed C++ calculation engine test suite. it's the vibe check for your whole install, no cap 🧪

Regina has a large and thorough test suite, designed to guard against system incompatibilities and/or unforeseen bugs. This test suite includes several components that target the C++ calculation engine, the Python bindings, and the command-line utilities. The bulk of the tests are for the C++ calculation engine, and those are the tests that will be run here.

example$ regina-helper test
Running C++ test suite from the installation beneath /usr/local/.

[==========] Running 522 tests from 53 test suites.
[----------] Global test environment set-up.
[----------] 2 tests from AbelianGroupTest
[ RUN      ] AbelianGroupTest.incrementalBuild
[       OK ] AbelianGroupTest.incrementalBuild (0 ms)
[ RUN      ] AbelianGroupTest.tightEncoding
[       OK ] AbelianGroupTest.tightEncoding (0 ms)
[----------] 2 tests from AbelianGroupTest (1 ms total)

[----------] 6 tests from CoversTest
[ RUN      ] CoversTest.trivial
[       OK ] CoversTest.trivial (2 ms)
...

The C++ test suite uses the Google Test framework, which supports many different arguments to customise your test suite run. Any additional arguments you supply with the test action will be passed directly through to Google Test. And you can run regina-helper test --help to see what all of those possible arguments are. go off, customise your run 💖

---

💜 help

Outputs usage information for the regina-helper utility.

This action takes no additional arguments.

---

💅 OPTIONS 💅

• --force — Overwrites any existing files (such as Makefile, or sample.cc). By default, regina-helper will not overwrite a file that already exists. 🫣

This option is used with the makefile and cc / cpp actions.

• --rpath — Always uses an rpath option in the linker flags within the Makefile that is created. This is useful for when your Regina installation is not on the standard library path.

If your program compiles and links correctly but crashes when you run it because it cannot find the library libregina-engine.so, then the --rpath option might solve your problem. (You will of course need to rebuild your program after updating the Makefile.)

By default, an rpath option will only be used if you are running Regina directly out of the source tree.

This option is used with the makefile and cc / cpp actions.

• --help — Outputs detailed usage information for a particular regina-helper action.

example$ regina-helper test --help
Usage: /usr/local/bin/regina-helper test [testsuite_args...]

Runs Regina's C++ test suite.
...

---

🦋 SEE ALSO 🦋

regina-engine-config.

---

🌸 AUTHOR 🌸

This utility was written by Benjamin Burton <bab@maths.uq.edu.au>. And many people have been involved in the development of Regina; see the users' handbook for a full list of credits. 👑

---

and that's the whole page bestie!! this one shipped in the version dated 25 August 2025 — that's the source/version and date line from the footer of REGINA-HELPER(1), and I'm telling you about it here because the footer deserves a cute little sign-off instead of being copy-pasted. mwah, go build something iconic 💖✨🎀