|
|
[[_TOC_]]
|
|
|
|
|
|
# Installing using Docker
|
|
|
|
|
|
The most hands-off and OS-agnostic way to install `graph-tool` is using [Docker](https://www.docker.com/). If you have Docker installed, this can be done simply by running:
|
... | ... | @@ -41,10 +43,10 @@ The easiest way to get going is to use a package manager, for which the installa |
|
|
|
|
|
Alternatively, `graph-tool` can be installed from source, by [manual compilation](#manual-compilation). The module uses the standard [GNU build system](https://en.wikipedia.org/wiki/GNU_Build_System) for this (i.e. `./configure; make; make install`), and users wishing to go on this route are recommended to familiarize themselves with it. [Basic instructions](#manual-compilation) are given below, and an in-depth resource is the [Autotools Mythbuster](https://autotools.io/index.html).
|
|
|
|
|
|
# Installation via package managers
|
|
|
## GNU/Linux
|
|
|
## Installation via package managers
|
|
|
### GNU/Linux
|
|
|
|
|
|
### Arch
|
|
|
#### Arch
|
|
|
|
|
|
[Packages for Arch](https://aur.archlinux.org/packages/python-graph-tool/) are available in the Arch User Repository. You can install it with yaourt:
|
|
|
|
... | ... | @@ -57,7 +59,7 @@ yaourt -S python-graph-tool |
|
|
```
|
|
|
depending on the python version.
|
|
|
|
|
|
### Gentoo
|
|
|
#### Gentoo
|
|
|
|
|
|
An ebuild for graph-tool is included in the default [Gentoo](https://www.gentoo.org/) repository. Just do
|
|
|
|
... | ... | @@ -66,7 +68,7 @@ emerge graph-tool |
|
|
```
|
|
|
to install it.
|
|
|
|
|
|
### Debian & Ubuntu
|
|
|
#### Debian & Ubuntu
|
|
|
|
|
|
For [Debian](http://www.debian.org/), add the following lines to your `/etc/apt/sources.list`,
|
|
|
|
... | ... | @@ -119,8 +121,8 @@ sub 4096R/EF5E8538 2017-03-19 [expires: 2022-03-18] |
|
|
sub 4096R/628150AC 2017-03-19 [expires: 2022-03-18]
|
|
|
```
|
|
|
|
|
|
## MacOS X
|
|
|
### Macports
|
|
|
### MacOS X
|
|
|
#### Macports
|
|
|
|
|
|
A portfile is available for installation in MacOS X systems with [Macports](http://www.macports.org/). It is included in the [standard macports list](http://www.macports.org/ports.php?by=name&substr=graph-tool). Just run the following command to install it:
|
|
|
|
... | ... | @@ -128,7 +130,7 @@ A portfile is available for installation in MacOS X systems with [Macports](http |
|
|
port install py-graph-tool
|
|
|
```
|
|
|
|
|
|
### Homebrew
|
|
|
#### Homebrew
|
|
|
|
|
|
With [Homebrew](http://brew.sh/) the installation is also straightforward, since a formula for it is included in the "science" list:
|
|
|
```
|
... | ... | @@ -137,7 +139,7 @@ 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
|
|
|
###### Compiler choice in MacOS X
|
|
|
|
|
|
TL;DR : Just use [clang](http://clang.llvm.org/) for everything.
|
|
|
|
... | ... | @@ -147,13 +149,13 @@ In an ideal world, the correct version should be the latest one from the "stock" |
|
|
|
|
|
(If possible, a much better option would be to use a less [defective](http://www.defectivebydesign.org/apple) platform in the first place.)
|
|
|
|
|
|
## Windows
|
|
|
### Windows
|
|
|
|
|
|
Fully native installation on windows is not supported, but two viable options are using [Docker](#installing-using-docker) (see [here](https://docs.docker.com/docker-for-windows/) for instructions), and using the Ubuntu userspace for windows (more information [here](http://blog.dustinkirkland.com/2016/04/howto-ubuntu-on-windows.html) and [here](https://insights.ubuntu.com/2016/04/14/howto-ubuntu-on-windows-2/)), which allows the native Ubuntu packages to be installed as described [above](#debian-ubuntu).
|
|
|
|
|
|
---------------------------------------
|
|
|
|
|
|
# Manual compilation
|
|
|
## Manual compilation
|
|
|
|
|
|
Graph-tool was tested extensively only on
|
|
|
[GNU/Linux](http://www.gnu.org) and MacOS X systems, but should also be
|
... | ... | @@ -170,7 +172,7 @@ usable on other systems where the below requirements are met. |
|
|
- [ ] 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).
|
|
|
|
|
|
## Generic instructions
|
|
|
### Generic instructions
|
|
|
|
|
|
Having installed the above dependencies (which can be done either manually, or preferably via a package manager), the module can be compiled in the usual way:
|
|
|
|
... | ... | @@ -187,12 +189,12 @@ The above will install the library in the standard directories, and usually the |
|
|
|
|
|
Deviations from the standard directories will require that we inform the `configure` script in specific ways. This is done via configuration options or environment variables passed to the script. The most important ones are listed below:
|
|
|
|
|
|
### Options to the `configure` script
|
|
|
#### Options to the `configure` script
|
|
|
* `--prefix=DIR`: This sets the general installation prefix. If left unspecified, this defaults to `DIR=/usr/local`. Note that this is used to install only peripheral parts of the library, such as README and pkgconfig files. The location of the module itself is specified with the following option.
|
|
|
* `--with-python-module-path=DIR`: This sets the location where the Python module will be installed. If left unspecified, this will be automatically determined using the Python interpreter. The default values may be something like `DIR=/usr/lib/python3.6/site-packages`, but this varies between OSs, virtualenvs, etc.
|
|
|
* `--with-boost-<libname>=NAME`: The Boost libraries are installed with different names across OSs. The `configure` script tries to guess the names using common patterns, but this can fail. With this option, the user can specify the correct name (either the entire library name or just a suffix). For example, if the boost-python library is name `libboost-python-mt-gcc6-py36-foobar`, this can be passed to `configure` as `--with-boost-python=-mt-gcc6-py36-foobar`.
|
|
|
|
|
|
### Environment variables
|
|
|
#### Environment variables
|
|
|
The configure script will consult some shell environment variables that will affect its configuration.
|
|
|
|
|
|
* `CXX`: If defined, this variable should point to C++ compiler that will be used.
|
... | ... | @@ -217,7 +219,7 @@ After the library has been installed, we need to make sure that the Python inter |
|
|
$ export PYTHONPATH="$PYTHONPATH:$HOME/.local/lib/python3.6/site-packages"
|
|
|
```
|
|
|
|
|
|
## Dependencies installed in a nonstandard directory
|
|
|
### Dependencies installed in a nonstandard directory
|
|
|
|
|
|
If any of the dependencies have been installed in a nonstandard directory, we need to pass this information to the `configure` script. Suppose again these have been installed in the `$HOME/.local` directory. In this case we need
|
|
|
```bash
|
... | ... | @@ -226,7 +228,7 @@ $ make install |
|
|
```
|
|
|
(typically, in such cases we also want to install the library itself in the home directory; for this we need to combine with the options in the previous section.)
|
|
|
|
|
|
## Installing in a [virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
|
|
|
### Installing in a [virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
|
|
|
|
|
|
To install graph-tool in a virtualenv we need to activate it before running configure
|
|
|
```bash
|
... | ... | @@ -240,11 +242,11 @@ The `--prefix` is necessary only so that non-python-related parts are installed |
|
|
|
|
|
**Important:** The boost-python dependency **must** be compiled against the same Python version that is used in the virtualenv.
|
|
|
|
|
|
## Troubleshooting
|
|
|
### Troubleshooting
|
|
|
|
|
|
If errors occur when running `configure`, look inside the `config.log` file for information on why the tests failed. Do not forget to include the contents of this file when reporting problems.
|
|
|
|
|
|
## Memory requirements for compilation
|
|
|
### 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.
|
|
|
|
... | ... | @@ -252,6 +254,6 @@ Graph-tool requires relatively large amounts of RAM (~ 3 GB) during compilation, |
|
|
|
|
|
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
|
|
|
### 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.
|
|
|
|