Regina Calculation Engine
Static Public Member Functions | List of all members
regina::NGlobalDirs Class Reference

Provides global routines that return directories in which various components of Regina are installed on the system. More...

#include <file/nglobaldirs.h>

Static Public Member Functions

static std::string home ()
 Returns Regina's primary home directory on the system. More...
 
static std::string pythonModule ()
 Returns the directory in which Regina's python module is installed, or the empty string if the module is installed in python's standard site-packages directory. More...
 
static std::string census ()
 Returns the directory containing the large machine-encoded census data files. More...
 
static std::string pythonLibs ()
 Returns the directory in which optional "helper" Python libraries are installed. More...
 
static std::string examples ()
 Returns the directory in which example data files (including the smaller but human-browsable census data files) are installed. More...
 
static std::string engineDocs ()
 Returns the directory in which API documentation for Regina's calculation engine is installed. More...
 
static std::string data ()
 Returns the directory containing miscellaneous data files for internal use Regina's calculation engine. More...
 
static void setDirs (const std::string &homeDir, const std::string &pythonModuleDir, const std::string &censusDir=std::string())
 Tells Regina where data files are installed. More...
 

Detailed Description

Provides global routines that return directories in which various components of Regina are installed on the system.

By default, these routines are only useful with a fixed filesystem installation of Regina (e.g., a typical Linux install). Specifically, they return the relevant directories as they were configured by cmake at build time.

If Regina may have been moved around on the filesystem (e.g., if you are running an app bundle on MacOS), then you must call setDirs() when your application starts. Otherwise the directories that NGlobalDirs returns might be incorrect, and might not even exist.

The directories returned by home(), pythonModule() and census() can be independently changed at runtime, by calling setDirs(). All other directories maintained by this class are subdirectories of home().

At present this class does not support running Regina directly out of the source tree. This might be supported in future versions of Regina.

Member Function Documentation

std::string regina::NGlobalDirs::census ( )
inlinestatic

Returns the directory containing the large machine-encoded census data files.

These data files are not human-browsable: instead they are built for fast performance and small size. Users can access them by calling NCensus::lookup().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/data/census .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine data directory.
std::string regina::NGlobalDirs::data ( )
inlinestatic

Returns the directory containing miscellaneous data files for internal use Regina's calculation engine.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/data .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine data directory.
std::string regina::NGlobalDirs::engineDocs ( )
inlinestatic

Returns the directory in which API documentation for Regina's calculation engine is installed.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/engine-docs .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's calculation engine documentation directory.
std::string regina::NGlobalDirs::examples ( )
inlinestatic

Returns the directory in which example data files (including the smaller but human-browsable census data files) are installed.

This is computed automatically as a subdirectory of home().

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/examples .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's example and census data directory.
std::string regina::NGlobalDirs::home ( )
inlinestatic

Returns Regina's primary home directory on the system.

This directory should contains subdirectories data, icons/, examples/ and so on.

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's primary home directory.
std::string regina::NGlobalDirs::pythonLibs ( )
inlinestatic

Returns the directory in which optional "helper" Python libraries are installed.

These libraries are not a formal part of Regina, but can be made to load automatically as extra user libraries through Regina's python settings.

On a typical GNU/Linux system, this directory might (for example) be /usr/local/share/regina/pylib .

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's optional Python library directory.
std::string regina::NGlobalDirs::pythonModule ( )
inlinestatic

Returns the directory in which Regina's python module is installed, or the empty string if the module is installed in python's standard site-packages directory.

Warning
If Regina is not installed in the exact location configured at compile time (e.g., if you are running a MacOSX app bundle), you must call setDirs() before calling this routine.
If you are running out of the source tree, this routine will almost certainly return an incorrect (and possibly non-existent) directory.
Returns
Regina's python module directory.
static void regina::NGlobalDirs::setDirs ( const std::string &  homeDir,
const std::string &  pythonModuleDir,
const std::string &  censusDir = std::string() 
)
static

Tells Regina where data files are installed.

You must call this at runtime if Regina is not installed in the location that was configured by cmake at build time (e.g., if you are running a MacOSX app bundle).

Empty strings are treated as follows:

  • If homeDir or censusDir is an empty string, then the corresponding directory will not be changed.
  • If pythonDir is an empty string then this has an explicit meaning, namely that the python module has been installed in python's standard site-packages directory.
Parameters
homeDirRegina's primary home directory; this will be returned by homeDir().
pythonModuleDirthe directory containing Regina's python module, or the empty string if the module has been installed in python's standard site-packages directory; this will be returned by pythonModule().
censusDirThe directory containing the large machine-encoded census data files; this will be returned by census().

The documentation for this class was generated from the following file:

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).