# Compiling Regina Into a &cpp; Project

®ina; offers its mathematical core as a &cpp; shared library. This means that your own &cpp; applications can make use of ®ina;'s functionality, much like they might use any other mathematical library.

®ina; is released under the &gnu; General Public License, which restricts how you may use it in other software. These restrictions are to benefit and encourage mathematical software that is free to use, modify and redistribute. For further information, please read the license details or write to the authors if you have any specific questions.

## Installing the Development Files

To build ®ina; into your own projects, you must install ®ina;'s development files; that is, the &cpp; headers and development libraries.

- If you downloaded an &rpm;-based &linux; package (e.g., for &fedora;, &mandriva; or &suse;), you should already have the development files installed. Check that the headers are present in `/usr/include/regina/`.

- If you downloaded a &debian;-based &linux; package (e.g., for &debian; or &ubuntu;), you will need to install the separate package `regina-normal-dev`. Check that the headers are present in `/usr/include/regina-normal/`.

- If you built ®ina; yourself, you should already have the &cpp; headers and development libraries installed. Check that the headers are present in `/usr/local/include/regina/` (or wherever you chose to install ®ina;).

- If you use &windows; or if you downloaded the drag-and-drop app bundle on &macosx;, the development files are not available. This is because it is too difficult at present to ensure that your development environment is compatible.

®ina; uses some other libraries in turn, and you will need the development files for these libraries also. You should install these through ready-made packages if at all possible: they are available in every major &linux; distribution. The extra libraries you will need are:

GNOME &xml; library (libxml2)

- Look for a package named `libxml2-dev`, `lib64xml2-devel` or `libxml2-devel`.

&gnu; multiprecision arithmetic libraries for &ccpp; (libgmp and libgmpxx)

- Look for a package named `libgmp-dev`, `lib64gmp-devel`, `libgmp-devel` or `gmp-devel`. Some distributions (such as &mandriva;) ship the &cpp; library separately in a package named `gmpxx-devel`.

On some platforms you might also need development files for the zlib compression library (libz), and a lightweight database library (which will be one of Tokyo Cabinet (libtokyocabinet), QDBM (libqdbm) or the Lightning Memory-Mapped Database (liblmdb)). Which of these you need will depend on how your linker works and how ®ina; was built. If you do need any of these, look for a package named `zlib1g-dev`, `zlib1-devel` or `zlib-devel`, and an appropriate option from `libtokyocabinet-dev`, `libtokyocabinet-devel`, `tokyocabinet-devel`, `libqdbm-dev`, `qdbm-devel`, `liblmdb-dev`, `liblmdb-devel` or `lmdb-devel`.

## Compiler and Linker Flags

When you compile your own &cpp; code that uses ®ina;'s calculation engine, you will need to pass some extra flags to the compiler. There are two ways to do this: a simple way using a Makefile, and a more complex but more flexible way that extracts ®ina;'s compiler and linker flags and passes them through to &gcc;.

### Using a Makefile

You can use the `regina-helper` tool to create a Makefile. This Makefile is suitable for compiling small programs that are entirely contained in a single &cpp; source file.

        example$ regina-helper makefile
        Preparing Makefile...
        example$ ls
        Makefile
        example$

If you have a &cpp; source file named `mycode.cc` (for example), you can put it in the same directory as the Makefile and compile it by typing `make mycode`. The Makefile will ensure that the compiler receives all of the necessary flags for building your program against ®ina;.

### Passing Flags to &gcc;

®ina; also ships with a utility `regina-engine-config`, which will give you the necessary flags explicitly. To find the compiler and linker flags, run `regina-engine-config --cflags` and `regina-engine-config --libs` respectively.

        example$ regina-engine-config --cflags
        -I/usr/include/regina-normal -I/usr/include -I/usr/include/libxml2
        example$ regina-engine-config --libs
        -L/usr/lib -lregina-engine /usr/lib/libxml2.so /usr/lib/libgmp.so /usr/lib/libgmpxx.so /usr/lib/libz.so -lpthread
        example$

If your code is a single &cpp; source file, you can compile and link a final executable in a single step:

        example$ g++ mycode.cc `regina-engine-config --cflags --libs`
        example$

If your code is spread across multiple source files, you should set up your build system so that it fetches the compiler and linker flags from `regina-engine-config`.

Note that compiler and linker flags will differ from system to system. You should always use `regina-engine-config` to find out what they are, and not just copy the flags that appear in the examples above.

The compiler and linker flags that `regina-engine-config` outputs are tailored to the &gnu; &cpp; compiler (g++) and Clang. If you use a different compiler, you might need to adjust your flags accordingly.

## &api; Documentation

You can access full &api; documentation by selecting Help Python &api; Reference from the menu. This describes in detail the &cpp; objects, classes and methods that ®ina; makes available. You can also read this &api; documentation online at ®enginedocsurlbase;.

Don't be worried because the menu says “&python; Reference”. The &api; documentation is really a &cpp; reference: &python; users are simply granted access to the &cpp; library through an extra layer of &python; bindings.