Scroll to navigation

REGINA-HELPER(1) The Regina Handbook REGINA-HELPER(1)

NAME

regina-helper - Helper utility for working with a Regina installation

SYNOPSIS

regina-helper action [ args ... ]

regina-helper action [ --help ]

DESCRIPTION

This utility understands the layout of your Regina installation, and it can help you with a variety of tasks that require this knowledge. For example, it can create Makefiles and/or sample C++ code for you, or help you run Regina's test suite.

The first argument to regina-helper should be an action, indicating what you want the utility to do. The available actions are described in detail below. To learn more about what an action does, you can run regina-helper action --help.

This utility is available in most but not all settings:

•
If you are using GNU/Linux and you have Regina installed in a system location (e.g., beneath /usr/ or /usr/local/), then regina-helper should be included with your installation, and any output it produces should be relative to this system installation.
•
If you are using macOS and you are running Regina from an app bundle (which might be under /Applications/ or might be somewhere else), then you can run regina-helper from within the app bundle (.../Regina.app/Contents/MacOS/regina-helper), and any output it produces should be relative to this app bundle.
•
If you are building Regina yourself from the source tree (on any platform), then you can run regina-helper from the source tree, and any output it produces should be relative to this same source tree. In particular, it will not assume that you have actually installed Regina.
•
If you are using pre-built packages for Regina on Windows, then regina-helper will not be included in your installation.

ACTIONS

The first argument to regina-helper should be one of the following actions:

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:

Indicates that you are running Regina from an installation in a fixed location that follows the freedesktop.org layout. This is seen with Regina's GNU/Linux packages, as well as local CMake builds with no special arguments.
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. This is typically seen with local CMake builds where REGINA_INSTALL_TYPE was explicitly set to HPC.
Indicates that you are running Regina from within a macOS app bundle.
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.
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.

Creates a Makefile in the current directory, suitable for compiling C++ programs against Regina. In particular, once you have your Makefile in place, you can (for example) compile a C++ program foo.cc just by running make foo.

The main reason for using this Makefile is that it includes compiler and linker flags for accessing Regina's C++ calculation engine. (In particular, 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; these are described below.

Creates a Makefile in the current directory that is suitable for compiling C++ programs against Regina, as well as a sample C++ program that can be used as a starting point for your own code. 



    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.

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

Runs Regina's detailed C++ calculation engine test suite.

Regina has a large and thorough test suite, designed to guard against system incompatibilities and/or unforseen 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 that you supply with the test action will be passed directly through to Google Test. You can run regina-helper test --help to see what all of these possible arguments are.

Outputs usage information for the regina-helper utility.

This action takes no additional arguments.

OPTIONS

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.

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.

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>. Many people have been involved in the development of Regina; see the users' handbook for a full list of credits.

25 August 2025