|
|
# Compilation
|
|
|
`graph-tool` can be installed either via a package manager, or by manual compilation. The easiest method is via a package manager. Please see below a list of options for different operating systems.
|
|
|
|
|
|
Graph-tool was tested extensively only on
|
|
|
[GNU/Linux](http://www.gnu.org) and MacOS X systems, but should also be
|
|
|
usable on other systems where the below requirements are met.
|
|
|
|
|
|
- [x] A C++14 compiler ([GCC]() version 5 or above, or [clang](http://clang.llvm.org/) version 3.4 or above).
|
|
|
- [x] The [Boost](http://www.boost.org/) libraries, version 1.54 or above.
|
|
|
- [x] [Python](http://www.python.org/) version 2.7, 3 or above.
|
|
|
- [x] The [expat](http://expat.sourceforge.net/) XML library.
|
|
|
- [x] The [SciPy](http://www.scipy.org/) python module.
|
|
|
- [x] The [Numpy](http://numpy.scipy.org/) python module, version 1.7 or above.
|
|
|
- [x] The [CGAL](http://www.cgal.org/) C++ geometry library, version 3.5 or above.
|
|
|
- [ ] The [sparsehash](http://code.google.com/p/sparsehash/) template library (optional, but recommended).
|
|
|
- [ ] The [GTK+ 3](http://www.gtk.org/), [cairomm](http://cairographics.org/cairomm), [pycairo](http://cairographics.org/pycairo/) and [matplotlib](http://matplotlib.sourceforge.net/) libraries, used for graph drawing (optional).
|
|
|
- [ ] The [Graphviz](http://www.graphviz.org/) packaged for graph drawing, with the python bindings enabled (optional, deprecated).
|
|
|
|
|
|
Having installed the above dependencies, the module can be compiled in the usual way:
|
|
|
|
|
|
```bash
|
|
|
$ ./configure
|
|
|
$ make
|
|
|
```
|
|
|
|
|
|
After compilation, the module can be installed in the default Python module directory by running:
|
|
|
``` bash
|
|
|
$ make install
|
|
|
```
|
|
|
## Memory requirements for compilation
|
|
|
|
|
|
Graph-tool requires relatively large amounts of RAM (~ 3 GB) during compilation, because it uses [template metaprogramming](http://en.wikipedia.org/wiki/Template_metaprogramming) extensively. Most compilers are still not not very well optimized for this, which means that even though the program is relatively small, it will still use up lots of RAM during compilation, specially if optimizations are used (and you do want to use them). Below you can see the memory usage during compilation using GCC 5.2.0 and clang 3.7.0, on a 64-bit GNU/Linux system with an Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz.
|
|
|
Note that although graph-tool is a Python library, it is implemented in C++, and thus has C++ dependencies such as [Boost](http://www.boost.org/), [CGAL](http://www.cgal.org/) and [expat](http://expat.sourceforge.net/), which are not instalable via Python-only package management systems such as [pip](http://www.pip-installer.org/).
|
|
|
|
|
|
![compilation](/uploads/f1adc8f96193dc74b79f278c7455ea39/compilation.svg)
|
|
|
|
|
|
GCC finishes under 80 minutes, and uses at most slightly below 3 GB. On the other hand, clang takes around 100 minutes, and has a memory use peak around 4 GB.
|
|
|
|
|
|
## Parallel algorithms
|
|
|
graph-tool can run several of its algorithms in [parallel](http://en.wikipedia.org/wiki/Parallel_programming). It makes use of [OpenMP](http://en.wikipedia.org/wiki/Openmp) to do this, which provides a straightforward way of converting serial code into parallel code. OpenMP is an extension to the Fortran, C and C++ languages, which uses compiler directives to achieve automated code parallelization. Since it uses [compiler directives](http://en.wikipedia.org/wiki/Compiler_directive) (`#pragma `in C/C++), it maintains backwards compatibility with compilers that do not support OpenMP, and the code is then compiled cleanly as regular serial code. Thus, support for parallel code in graph-tool is quite optional. If you wish to enable it, just pass the option `--enable-openmp` to the configure script.
|
|
|
|
|
|
<a name="note-macos></a>
|
|
|
## Note for MacOS X users
|
|
|
|
|
|
Although graph-tool is a Python library, it is implemented in C++, and thus has C++ dependencies such as [Boost](http://www.boost.org/), [CGAL](http://www.cgal.org/) and [expat](http://expat.sourceforge.net/), which are not installable via Python-only package management systems such as [pip](http://www.pip-installer.org/) or [EasyInstall](http://pypi.python.org/pypi/setuptools). Unlike most GNU/Linux distributions, the MacOS X system does not include integrated package management with automated dependency tracking, which means that the dependencies would have to be installed individually by hand. Since they also have their own dependencies, this would trigger the manual installation of many libraries, which is quite time consuming, error-prone and is not recommended for inexperienced users. Instead, the best option is to use one of the third-party package management software available, such as [Macports](http://www.macports.org/) or [Homebrew](http://brew.sh/).
|
|
|
|
|
|
Macports allows for the installation of graph-tool with a single command:
|
|
|
|
|
|
```
|
|
|
port install py-graph-tool
|
|
|
```
|
|
|
|
|
|
With Homebrew the installation is also straightforward:
|
|
|
|
|
|
```
|
|
|
brew tap homebrew/science
|
|
|
brew install graph-tool
|
|
|
```
|
|
|
See [below](#macos) for more notes on installing on MacOS X, as well as the [FAQ](#faq).
|
|
|
|
|
|
If you encounter an error installing graph-tool via Macports or Homebrew, please file a bug report via each respective project, not to graph-tool directly.
|
|
|
|
|
|
# Pre-compiled Packages
|
|
|
## Debian & Ubuntu
|
... | ... | @@ -147,6 +92,7 @@ With [Homebrew](http://brew.sh/) the installation is also straightforward, since |
|
|
brew tap homebrew/science
|
|
|
brew install graph-tool
|
|
|
```
|
|
|
If you encounter an error installing graph-tool via Macports or Homebrew, please file a bug report via each respective project, not to graph-tool directly.
|
|
|
|
|
|
#### Compiler choice in MacOS X
|
|
|
|
... | ... | @@ -194,4 +140,63 @@ dyld: lazy symbol binding failed: Symbol not found: __ZN5boost6python7objects23r |
|
|
Expected in: flat namespace
|
|
|
```
|
|
|
|
|
|
A: This is due to different flavors of the C++ standard library (libc++ and libstdc++) being used for Boost and graph-tool itself. This is resolved by either compiling everything using clang with c++11 mode activated (which could be cumbersome, since the same would have to be done for everything else which uses Boost), or simply by upgrading to Mavericks or newer (see [here](https://trac.macports.org/ticket/43086) for more info). |
|
|
\ No newline at end of file |
|
|
A: This is due to different flavors of the C++ standard library (libc++ and libstdc++) being used for Boost and graph-tool itself. This is resolved by either compiling everything using clang with c++11 mode activated (which could be cumbersome, since the same would have to be done for everything else which uses Boost), or simply by upgrading to Mavericks or newer (see [here](https://trac.macports.org/ticket/43086) for more info).
|
|
|
|
|
|
# Manual compilation
|
|
|
|
|
|
Graph-tool was tested extensively only on
|
|
|
[GNU/Linux](http://www.gnu.org) and MacOS X systems, but should also be
|
|
|
usable on other systems where the below requirements are met.
|
|
|
|
|
|
- [x] A C++14 compiler ([GCC]() version 5 or above, or [clang](http://clang.llvm.org/) version 3.4 or above).
|
|
|
- [x] The [Boost](http://www.boost.org/) libraries, version 1.54 or above.
|
|
|
- [x] [Python](http://www.python.org/) version 2.7, 3 or above.
|
|
|
- [x] The [expat](http://expat.sourceforge.net/) XML library.
|
|
|
- [x] The [SciPy](http://www.scipy.org/) python module.
|
|
|
- [x] The [Numpy](http://numpy.scipy.org/) python module, version 1.7 or above.
|
|
|
- [x] The [CGAL](http://www.cgal.org/) C++ geometry library, version 3.5 or above.
|
|
|
- [ ] The [sparsehash](http://code.google.com/p/sparsehash/) template library (optional, but recommended).
|
|
|
- [ ] The [GTK+ 3](http://www.gtk.org/), [cairomm](http://cairographics.org/cairomm), [pycairo](http://cairographics.org/pycairo/) and [matplotlib](http://matplotlib.sourceforge.net/) libraries, used for graph drawing (optional).
|
|
|
- [ ] The [Graphviz](http://www.graphviz.org/) packaged for graph drawing, with the python bindings enabled (optional, deprecated).
|
|
|
|
|
|
Having installed the above dependencies, the module can be compiled in the usual way:
|
|
|
|
|
|
```bash
|
|
|
$ ./configure
|
|
|
$ make
|
|
|
```
|
|
|
|
|
|
After compilation, the module can be installed in the default Python module directory by running:
|
|
|
``` bash
|
|
|
$ make install
|
|
|
```
|
|
|
|
|
|
The above will install the library in the standard directories, and usually the final step requires root privileges.
|
|
|
|
|
|
## Installing in a specific location (e.g. in a home directory)
|
|
|
|
|
|
The library can be installed in non-standard locations. For example, the usual convention of installing local programs in the `.local` subdirectory of a user's home can be achieved by:
|
|
|
|
|
|
```bash
|
|
|
$ ./configure --prefix=$HOME/.local --with-python-module-path=$HOME/.local/lib/python3.6/site-packages
|
|
|
make install
|
|
|
```
|
|
|
|
|
|
After the library has been installed, we need to make sure that the Python interpreter knows where to find it. In modern OSs, the above should already be in the interpreter's path. But otherwise (or in case some other path is being used), we need to modify the `PYTHONPATH` environment variable
|
|
|
```bash
|
|
|
$ export PYTHONPATH="$PYTHONPATH:$HOME/.local/lib/python3.6/site-packages"
|
|
|
```
|
|
|
|
|
|
## Installing in a virtualenv
|
|
|
|
|
|
## Memory requirements for compilation
|
|
|
|
|
|
Graph-tool requires relatively large amounts of RAM (~ 3 GB) during compilation, because it uses [template metaprogramming](http://en.wikipedia.org/wiki/Template_metaprogramming) extensively. Most compilers are still not not very well optimized for this, which means that even though the program is relatively small, it will still use up lots of RAM during compilation, specially if optimizations are used (and you do want to use them). Below you can see the memory usage during compilation using GCC 5.2.0 and clang 3.7.0, on a 64-bit GNU/Linux system with an Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz.
|
|
|
|
|
|
![compilation](/uploads/f1adc8f96193dc74b79f278c7455ea39/compilation.svg)
|
|
|
|
|
|
GCC finishes under 80 minutes, and uses at most slightly below 3 GB. On the other hand, clang takes around 100 minutes, and has a memory use peak around 4 GB.
|
|
|
|
|
|
## Parallel algorithms
|
|
|
graph-tool can run several of its algorithms in [parallel](http://en.wikipedia.org/wiki/Parallel_programming). It makes use of [OpenMP](http://en.wikipedia.org/wiki/Openmp) to do this, which provides a straightforward way of converting serial code into parallel code. OpenMP is an extension to the Fortran, C and C++ languages, which uses compiler directives to achieve automated code parallelization. Since it uses [compiler directives](http://en.wikipedia.org/wiki/Compiler_directive) (`#pragma `in C/C++), it maintains backwards compatibility with compilers that do not support OpenMP, and the code is then compiled cleanly as regular serial code. Thus, support for parallel code in graph-tool is quite optional. It is enabled by default, but if you wish to disable it, just pass the option `--disable-openmp` to the configure script.
|
|
|
|