Build on Linux

Getting ready

This guide is a step-by-step tutorial explaining how to build Analysis Situs from sources on Linux OS. Ubuntu 22.04 is used as a reference system, although the compilation process should be similar for other Linux distributives. It should be noted that Analysis Situs is a C++-written project whose language support is deliverately narrowed down to C++11 standard for the sake of better compatibility with older compilers.

Analysis Situs is entirely free and can be compiled without any commercial products or 3-rd parties. Still, for comfortable development under Linux OS, the authors of Analysis Situs recommend using the following proprietary software (although you may freely choose the free alternatives to the packages listed below):

GitKraken as a git client.
CLion as a C++ IDE.

The compilation procedure given below assumes that you have a "clean" installation of Linux. As a result, it goes through all of the steps to install the required third-party dependencies, some of which your system may already have installed. If this is the case, you may skip the corresponding steps. Also, keep in mind that Analysis Situs is a rapidly evolving project. Although we try to minimize the dependencies and keep the compilation process as clean as possible, some inconsistencies may pop up. Please, report, if you encounter any.

Install development tools

CMake

Analysis Situs is configured with CMake. To install CMake, you go like this:

sudo apt install cmake-qt-gui

To make sure that CMake is installed properly, run it like this from the Terminal:

cmake-gui&

You should be able to see the CMake window:

It is recommended to try to configure the project for the first time to observe all missing dependencies. To do that, you have to input the source and the build directories, then press "Configure" and choose "Unix Makefiles" as the generator:

The next stage is to specify "/usr/lib" as the value of "3RDPARTY_DIR" and set "INSTALL_DIR" to the directory where Analysis Situs will be copied upon successful compilation. Also, specify "Release" as "CMAKE_BUILD_TYPE" to compile the project in the optimized mode (for debugging, you may want to type "Debug").

Keep the CMake GUI dialog open and proceed with installation of other 3-rd party libraries following this guide.

Rapidjson

Analysis Situs provides a comprehensive framework for feature recognition. To output the recognition results in a persistent way, it uses JSON format. At the level of C++, JSON documents are manipulated with Rapidjson library. To install Rapidjson, use the following command:

sudo apt-get -y install rapidjson-dev

Eigen

Eigen is a header-only library for linear algebra. Install the development version as follows:

sudo apt-get -y install libeigen3-dev

OpenCascade dependencies

Tcl/Tk and freeimage are the dependencies of OpenCascade. Install with:

sudo apt-get install -y tcl tcl-dev tk tk-dev libfreeimage-dev

Other dependencies for graphics are to be installed in the following way:

sudo apt-get install -y libxmu-dev libxi-dev
sudo apt-get install -y libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev libosmesa6-dev

OpenCascade

Analysis Situs uses OpenCascade 7.6 as a geometric kernel. We prefer to build OpenCascade from sources. To do that, execute the following commands one after another (make sure to set your working directory properly):

mkdir /home/quaoar/work/opencascade
cd /home/quaoar/work/opencascade
wget https://github.com/Open-Cascade-SAS/OCCT/archive/refs/tags/V7_6_0.tar.gz
tar zxvf V7_6_0.tar.gz
mkdir /home/quaoar/work/opencascade/OCCT-7_6_0/build
cd /home/quaoar/work/opencascade/OCCT-7_6_0/build
cmake .. \
    -DCMAKE_BUILD_TYPE=release \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DUSE_FREEIMAGE=ON
make -j8
sudo make install

It should be noted that here we install OpenCascade into the system directory "/usr". That is why you would need administrative permissions for "make install".

At this point, it might be interesting to check that OpenCascade has been installed successfully by giving it a test run. For that, you can go like this:

cd /usr/bin
./draw.sh

In the launched DRAW session, give the following commands:

pload ALL
box a 0 0 0 1 1 1
vinit
display a
vfit

It should be noted that on Linux, OpenCascade uses MESA (i.e. software rendering), so you should be able to work with 3D graphics even without video drivers preinstalled.

Qt

Qt is the UI framework used by Analysis Situs. Install it with the following commands:

sudo apt-get update
sudo apt-get -y install libqt5x11extras5-dev
sudo apt-get -y install qttools5-dev

VTK

The visualization in Analysis Situs is based entirely on VTK framework. Unlike Qt, here it is necessary to have a specific version of the library. We prefer to build VTK from sources. To do that, use the following commands:

cd /home/quaoar/work
wget https://www.vtk.org/files/release/8.2/VTK-8.2.0.tar.gz
tar xvfz ./VTK-8.2.0.tar.gz
cd /home/quaoar/work/VTK-8.2.0
mkdir build
cd /home/quaoar/work/VTK-8.2.0/build
cmake .. \
    -DVTK_Group_Qt=ON \
    -DVTK_QT_VERSION=5 \
    -DVTK_RENDERING_BACKEND=OpenGL2 \
    -DVTK_Group_Imaging=YES \
    -DVTK_Group_Qt=YES \
    -DVTK_Group_Views=YES \
    -DBUILD_SHARED_LIBS=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr
make -j8
sudo make install

It might happen that you encounter compilation or linking problems because VTK-8.2 is quite obsolete, while gcc compiler, Qt and potentially something else in your Linux environment is more up-to-date. For example, VTK-8.2 would not see any compilation issues on Ubuntu 20.04, while on Ubuntu 22.04 the situation becomes worse. Ideally, Analysis Situs should be migrated to a newer version of VTK, but that was hardly possible last time we tried it.

Generate Makefiles

At this point you can try reconfiguring Analysis Situs in CMake:

Once the configuration is done, you can head over to the build directory of Analysis Situs and try making it for the first time:

make
make install

To run Analysis Situs, navigate to the installation directory and run its bash executable like this:

./asiExe.sh

To test if Analysis Situs is operational, consider executing the following commands in the "Active Script" console:

make-box a 0 0 0 1 1 1
set-as-part a

Pay attention to the visualization of edges. If your video-driver is fine, you should be able to see them.

Dockerfile

The procedure detailed above is automated in the Dockerfile available in your working copy of Analysis Situs. Therefore, you may prefer to build Analysis Situs with UI in a Docker container.