Installation instructions : Ready to compile

The classic installation details are specified in the INSTALL.[linux,mac,win] files available in the tulip source code root directory. However, if you are reading this tutorial/documentation, you may be interested in using Tulip in a more advanced fashion whether by creating new perspectives, plug-ins or algorithms. The following instructions will help you to prepare your system by installing the Tulip program ready to be compiled and modified to your convenience.

How to proceed ?

The installation process is not complicated, it can however take some time depending on your computer. Before starting the Tulip set-up, as a developer, you must be aware of some of the Tulip intern behaviours.

Foreword: Debug and Release modes

Tulip can be compiled and thus executed in two different modes. The first one, called Release, is the classic Tulip execution mode. The application should be executed this way when you are only using the originaly integrated tool of Tulip or the add-ons included with the plug-in library. Most users will only be interested in this mode.

Nevertheless, because Tulip is a research tool, the users testing their algorithms or plug-ins may not be sure of their code source reliability. These people should be more concerned with the second mode available, the Debug mode. With it, the whole program will be slightly slower as the execution is monitored with sanity assertions. If an unexpected behaviour happens and one of the assertion detect it, Tulip will pop an error message expliciting the problem encounter.

These modes must be separated as their behaviour are entirely different. A program instance compiled in Debug mod can not be used to launch a Release version of Tulip and vice versa. For instance, a few functionalities will need assertions only checked in debug mode to run correctly, some of these cases are presented in the Tulip library tutorial section.

Setting up the system

If you want to be able to recompile Tulip, you have to organize the different directories which will contain the source code, the libraries and the executables. The disposition we propose here and use in the following steps is just a suggestion. It allows a clear distinction between each directory and their use and gives you the ability to have several working versions of Tulip at the same time on your computer.

First, select the directory in which you want to set the application (you must have the appropriate permissions from the OS) and create here the directory Tulip-4.X (where X is adapted to the current version number). Into that folder, create five subdirectories:

  • tulip-src : the source files will be kept here
  • build-debug : where we stock the generated build file (with the mode Debug)
  • build-release : where we stock the generated build file (with the mode Release)
  • install-debug : the program will be installed here (with the mode Debug)
  • install-release : the program will be installed here (with the mode Release)

You should obtain a directory hierarchy similar to this one:

_images/install_rep.png

Installation on a UNIX-like OS

Requirements

To compile and run Tulip, you will need the following tools/libraries:

  • libqt4-dev
  • libfreetype6-dev
  • zlib1g-dev
  • libglew-dev
  • libjpeg-dev
  • libpng12-dev
  • build-essential
  • cmake
  • doxygen
  • libxml2-dev
  • qt4-dev-tools

Plus, one of the following version of the python library:

  • python2.5-dev
  • python2.6-dev
  • python2.7-dev

You will have to use system dedicated package installer (apt-get, yum ...) to install or update directly all the previously listed packages. This action will modify your current system so you may need administrator or super-user access and rights on the OS.

Download the source code

You can obtain the Tulip source code in several ways. The easiest is to pick them directly from the Sourceforge website (by following this link). This method, nevertheless, is not always the best choice. If you want to work actively with Tulip, you will need to keep your project up to date.

The other, slightly more complicated, solution is to use the subversion development repository. This allows you to easily keep your Tulip version up to date. The Unix/Linux based systems should be able to run the svn tool with the following commands

$ cd [...]/Tulip-4.X/
$ svn checkout svn://svn.code.sf.net/p/auber/code/tulip tulip-src

You can choose the access path and the target dir tulip-src according to your preference. Do not forget where the source code is located, you will need the path for completing the compilation and for specifying it to your API.

Once you have import the source code using svn, you can easily update it with the commands

$ cd [...]/Tulip-4.X/tulip-src
$ svn update

Generate the MakeFiles

Tulip uses cmake to generate the build instructions. In the following instructions we will use cmake-gui, offering a compliant graphic interface, to create the appropriate package files.

You must start by indicating the source code path and the file in which the binaries will be build:

_images/install_cmakegui_build_conf.png

In the example, we are showing the steps for a Release type build. The given paths must be modified according to your own preferences.

Then press on the Configure button, select the project generator (Unix Makefiles by default), use the default compilers or specify new ones and validate. cmake-gui will create empty folders in the build directory. We can now specify the installation information.

_images/install_cmakegui_build_generate.png

The two important fields to fill are the CMAKE_BUILD_TYPE and the CMAKE_INSTALL_PREFIX. The build type value must be set to Release or Debug (with capitals) and the install prefix indicates where the program will be installed. We do not want to use the default /user/local/ path as we may wish to exploit different versions of the application. In our case, the install directory will be in [...]/Tulip-4.X/install-release.

Click again on the Configure button to turn the red colour of the fields off. If this operation failed, ensure you have installed all the needed dependencies, filled appropriatly the fields, then try again.

Press the Generate button. If you have correctly set all the values, the two last lines of the prompt should be

Configuring done
Generating done

You can now close cmake-gui.

Use the Makefiles

Compile the packages

With the makefiles generated, we just have to execute them. Using your terminal, go into your build directory and use the command

$ make -jY

where Y is not greater than the number of cores on your processor.

This operation can take several minutes, so here comes the time for a well deserved break!

Install the packages

Once the make instruction is finished, you can install Tulip by using the command

$ make install

This operation can take a little time too. At the end, your installation path specified to cmake-gui will contained the binaries and the libraries of the application. You can now launch Tulip in its Release version by using the commands

$ cd [...]/Tulip-4.X
$ ./install-release/bin/tulip

You now just have to repeat the previously detailed steps while specifying to the appropriate fields the value debug instead of release to achieve the second build configuration.

Installation on a Windows system

Requirements

You will need to download the following packages in order to compile Tulip.

For a 64-bits build :

For a 32-bits build :

For both builds :

Setting up the build environment

The installation described on this page can be run on both 32 and 64-bits systems. In order to simplify the documentation, the steps will be explained using an x64 architecture by default. If you are completing this installation on a 32-bits operating system, please change the 64 value in the proposed paths with 32.

First install Python, CMake and NSIS (use default options). For the last one, you will need to add its root directory to the PATH environment variable. This can be achieved in the System Properties, tab Advanced System Parameters. You will need to click on the Environment Variables button and create or modify the user variable named PATH by adding the value

C:\Program Files (x86)\NSIS

in it (if you have used the default installation path).

MinGW

Extract the MinGW toolchain to

C:\mingw64

Open the Qt4 archive and extract the content of the ported64 directory to

C:\mingw64

It provides some precompiled dependencies Tulip needs (zlib, freetype).

Qt4

Extract then the directory Qt64-4.8.5 (resp. Qt32-4.8.5) from it to your directory of choice, for instance

C:\Qt

Then, create a file named qt.conf to

C:\Qt\Qt64-4.8.5

with the following content

[Paths]
Prefix = ../

It is needed by CMake to correctly setup the Tulip build.

Before proceeding, launch the script to reset the Qt path to its actual one.

Msys

Extract the content of the Msys archive to

C:\mingw64

Edit or create the file

C:\mingw64\msys\etc\fstab

and set its contents to

C:/mingw64/mingw

It is needed by CMake to find the compilers.

To launch the MSYS shell easily, we will create a new shortcut. Its target will be

C:\mingw64\msys\msys.bat --mintty

The option enables the use of MinTTY, an alternative to rxvt. Move the shortcut to a location where it will be easily accessible (on the desktop, in the taskbar or in the start menu) and run it.

Glew

Extract the Glew archive to your directory of choice (for instance C:/). With a MSYS shell launch from the previously created shortcut, navigate to the Glew folder through the command

$ cd /c/glew-1.10.0

Then compile GLEW by simply entering the command

$ make

Once GLEW compiled, copy the include and lib directories to

C:\mingw64

Everything is now set up to build Tulip.

Preparing the build

Importing the Tulip source code

If you have followed the recommandations given at the top of this page, you should have created somewhere a directory called Tulip-4.X in which you can find the folder tulip-src.

To import the Tulip source into it, you can either get a release tarball or checkout the subversion repository with svn. The Msys shell can provide such tool or you may try a solution with a graphic interface, like Tortoise SVN.

With the MSYS shell, use the command

$ cd /c/[...]/Tulip-4.X

to navigate to the designated folder and get the Tulip files with the instruction

$ svn checkout svn://svn.code.sf.net/p/auber/code/tulip tulip-src

With Tortoise SVN, after a right click on tulip-src, select the action SVN Checkout a specify the checkout repository with the address

svn://svn.code.sf.net/p/auber/code/tulip

CMake and the build options

As explained previously, Tulip can be build using two different modes: Release and Debug. In the current demonstration, we will use the Release profile. If you want to use the other one, just adapt the appropriate fields by remplacing the term Release with Debug.

With the Msys shell, enter the build-release folder

$ cd /c/[...]/Tulip-4.X/build-release

and launch the following command

$ cmake-gui ../tulip-src

You can also run CMake-gui with its executable (in C:\Program Files (x86)\CMake 2.8). You will, however, need to specify the source and build directories.

Once the CMake GUI appear click on Configure and then select “MinGW Makefiles” generator.

CMake will then display an error message. If you have run CMake through the Msys shell, just reclick on Configure, otherwise, if you have run the executable directly, you will need to specify the filepath to the make tool

CMAKE_MAKE_PROGRAM = C:/mingw64/bin/mingw32-make.exe

then click again on Configure.

CMake will once more display an error message. This time, it did not find Qt4. Just fill the CMake variable QT_QMAKE_EXECUTABLE with the path to qmake.exe

QT_QMAKE_EXECUTABLE = C:/Qt/Qt64-4.8.5/bin/qmake.exe

Relaunch CMake configuration. You will then have to specify the following CMake variables (check “Grouped” and “Advanced” if you don’t see them)

FREETYPE_INCLUDE_DIR_freetype2 = C:/mingw64/include/freetype2
FREETYPE_INCLUDE_DIR_ft2build = C:/mingw64/include/
FREETYPE_LIBRARY = C:/mingw64/bin/libfreetype-6.dll

ZLIB_INCLUDE_DIR = C:/mingw64/include/
ZLIB_LIBRARY = C:/mingw64/bin/zlib1.dll

GLEW_INCLUDE_DIR = C:/mingw64/include/
GLEW_LIBRARY = C:/mingw64/lib/glew32.dll

You can use the Add entry button to add them, CMake will automatically merge variables using the same name (the * _LIBRARY are of type FILEPATH and the others are of type PATH).

Python should be automatically found, nevertheless, if you are using a 64-bits OS, you will have to replace the content of the variable PYTHON_LIBRARY by the path of the dll corresponding to the Python version used. If you have installed the 2.7, set it to

PYTHON_LIBRARY = C:/Windows/System32/python27.dll

and if you are using the 3.3, change it to

PYTHON_LIBRARY = C:/Windows/System32/python33.dll

Finish the CMake configuration by setting

CMAKE_BUILD_TYPE = Release

and by changing the variable CMAKE_INSTALL_PREFIX to your installation directory of choice, for instance

CMAKE_INSTALL_PREFIX = C:/[...]/Tulip-4.X/install-release

The default value is incorrect as you can not write in C:\Program Files (x86)\tulip without admin privileges. Finally, add a new CMake variable (click on Add Entry for that) of type PATH

CMAKE_LIBRARY_PATH = C:/mingw64/bin;C:/mingw64/lib

Relaunch one last time the CMake configuration, everything should be alright now (except the Python documentation generation but it is not critical, you will need to install the Sphinx Python module in order to generate it).

Click on Generate to produce the Makefiles and exit the CMake GUI.

Building Tulip

To build the Tulip software, return in the MSYS shell and, from the build directory, just enter the command

$ mingw32-make.exe

You can use parallel build to speed things up by adding the -jX option (set X to your number of processors).

Installing Tulip

Once Tulip is fully compiled, enter the following command to install it

$ mingw32-make.exe install

Once it is finished, you can run the executable

tulip.exe

located in the bin folder of the Tulip installation directory to launch the software.