Skip to content

Latest commit

 

History

History
413 lines (313 loc) · 17.4 KB

Install.md

File metadata and controls

413 lines (313 loc) · 17.4 KB
Raw

SimTaDyn Compilation Guide

Compiling SimTaDyn (short version)

This document explains the different steps for getting, compiling the SimTaDyn code source take from the git master branch or the development branch. and how to install it. For other SimTaDyn branches, specially for the release-EPITA-2004 branch, please read the INSTALL file associated to this branch.

Type the following code in your Linux console. This will download the SimTaDyn code source, download needed third part libraries, compile the whole code source, install the executable (if desired) and launch it.

git clone --recurse-submodules https://github.com/Lecrapouille/SimTaDyn.git --depth=1
cd SimTaDyn/
make download-external-libs
make compile-external-libs
make -j4
./build/SimTaDyn
# optional:
sudo make install
SimTaDyn

Steps for compiling SimTaDyn (long explanations)

Reading the next of this document is not necessary. It just gives more informations about the previous commands. Table of contents:

Step 1: Install packages that SimTaDyn depends on:

SimTaDyn code is based on C++11, modern OpenGL (>= 3.3), gtkmm >= 3.22 and gtksourceviewmm (which are C++ interfaces for GTK+ and GtkSourceView a boosted version of the GTK+ text editor) and other small libraries like libSOIL (for loading image files) or zipper (a C++ manipulationg zip archives).

Click on the link matching your operating system, for knowing how to install these libraries:

Step 2: Clone the SimTaDyn code source and its external parts:

Step 2.1: download the SimTaDyn code source from github Swimming Octocat:

git clone --recurse-submodules https://github.com/Lecrapouille/SimTaDyn.git

A SimTaDyn/ folder should have been created and will be refered as the root directory of your project.

The --depth=1 is optional: it allows to reduce the download duration by avoiding downloading the full history of commits. This is useful if you just want to compile to source whithout contributing to source code development.

Because not all libraries can be installed from disribution packages as explained in step 1, you will have to download and compile them from github. For some reasons which will not be explained here, SimTaDyn does use git submodule and therefore special options of the Makefile has to be called like explained in step 2.20

Step 2.2: download third parts. This is made by two bash scripts which can be called by the main Makefile:

cd SimTaDyn/
make download-external-libs
make compile-external-libs

Note: As alternative, you can do this:

cd SimTaDyn/external/
./download-external-libs.sh Linux
./compile-external-libs.sh Linux
  • If you are not working on Linux, but OSX or Windows: replace Linux by Darwin or Windows.
  • These libraries are not installed in your environnement. In the case of you desire them, you have to go to each directories and type:
sudo make install

Note: for the moment, you cannot download and compile with multiple jobs from makefile for the moment because it just calls a bash script.

Step 3: Compile the SimTaDyn code source:

SimTaDyn does not use ./configure script. Call directly the Makefile:

cd SimTaDyn/
make -j4

Note:

  • -jX is optional and is used for compiling faster the code source. X refers to the desired number of threads (usually 2 * number of cores of your computer. For example X = 2 * 2).

If you want to compile whith a different compilator use CXX like:

make CXX=clang++-3.9 -j4
Step 4: getting fun with SimTaDyn:

From code source:

cd SimTaDyn/
./build/SimTaDyn

or directly if SimTaDyn has been installed on your system:

SimTaDyn

Note: for the moment, SimTaDyn does not take options but will in the future.

Step 5: Install data that SimTaDyn depends on:

If you like SimTaDyn you can install it by typing:

sudo make install

By default:

  • the binary will be placed in /usr/bin and named SimTaDyn-<version>
  • its data and documentation placed in /usr/share/SimTaDyn/<version>/.
  • refers to the content of the file SimTaDyn/VERSION.
  • External libraires needed by SimTaDyn will not be installed.

If you do not like the default location, Pass to Makefile options DESTDIR, PREFIX and BINDIR or directly edit the file .makefile/Makefile.header (note: touching a makfile file will force a whole project compilation).

Installing packages that SimTaDyn depends on

Currently, gtkmm >= 3.22 is mandatory to get SimTaDyn worked correctly with OpenGL due to a bug in gtkmm solved in this version. Not all Ubuntu versions contains this version. In addition OpenGL is hardly supported by GTK+, a shame !

Ubuntu

Ubuntu >= 17.04

For Ubuntu >= 17.04, gtkmm >= 3.22 is available. Install directly the following packages (this will take you around 1 GB in your disk space):

sudo apt-get update && apt-get install cmake libgtksourceviewmm-3.0-dev freeglut3 freeglut3-dev mesa-common-dev libglu1-mesa-dev libglew-dev libglfw3-dev libdw-dev

If needed and for fixing some Gtk-Message like: "Failed to load module overlay-scrollbar":

sudo apt-get install overlay-scrollbar*

Ubuntu < 17.04

For Ubuntu versions < 17.04, gtkmm >= 3.22 is not available. If you have a 64-bits machine you could install Docker, pull an image of Ubuntu 17.04 and inside the docker, follow instructions described in below section.

If you have a 32-bits (which is my case), unfortunately Docker does not support 32-bits architecture, so you will have to compile by yourself, GTK+ and gtkmm source code. Link here.

Mac OS X

SimTaDyn compiles on a MacBook Air and Mac OS X (tested on version 10.9.5). To install gtkmm and other dependencies use the tool homebrew. The current gtkmm version is 3.22 and no problem occurred during the compilation of these libs. However the Gtk::GlArea is not fully implemented on this architecture and by consequence the OpenGL context is not created ! I'm sorry it does not depend on me but on gtk+ developpers (for memory, Legacy OpenGL worked perfectly on gtk+2 with gtkglext on 2003 with OSX (see release-EPITA-2004 branch but again gtk+ developpers seems have made regressions because the whole gtk window is black (even butons) !)

Debian

Is similar to Ubuntu >= 17.04, so please refer to Ubuntu section. The recommended Debian version is >= 9.3 which contains the correct Gtk version.

OpenSUSE

Install the following packages:

gcc-c++ gtksourceviewmm-devel freeglut-devel glew-devel libdw-devel Mesa-devel Mesa-libGLU-devel libglfw-devel

Note: I cannot personally test SimTaDyn on this plateform.

Other architecture

  • I cannot yet personally test on SimTaDyn on distribution like OpenSUSE, Red Hat, Slackware, Gentoo.
  • Window: Not done and no development scheduled yet. Indeed, I only have a XP and Cygwin stopped being ported for Windows XP and so I need higher Window version, which it's not my case currently. Feel free to help me on this point (I have an Appveyor script for my continous inegration but this script fails during the compilation of the external lib: zipper).

Docker

This section is for people having an Ubuntu < 17.04 or preferring to test SimTaDyn inside a docker. If you have a 64-bits machine you can install Docker, pull an image of Ubuntu 17.04 and inside the docker, follow instructions described in below section.

If you have a 32-bits (which is my case, I have to use a computer not owned by me, so I cannot help a lot on docker subject), unfortunately Docker does not support 32-bits architecture and you have to find another way for compling SimTaDyn.

Note: I'm a beginner with Docker so if you find that something I wrote is not good, please tell me.

Step 1: Install docker image:

If you have not a docker installed, you can follow these steps for Ubuntu or follow these steps for Debian.

Then download an official image of Ubuntu 18.10:

docker pull ubuntu:18.10

If you type:

docker images

You shall see something like this:

REPOSITORY TAG      IMAGE ID        CREATED        SIZE
ubuntu     18.10    d4452947e3fa    3 weeks ago    73.7MB

d4452947e3fa is the unique ID referring to your current image. Your value should differ from this document.

Step 2: Clone SimTaDyn:

And go inside SimTaDyn folder, this will be the entry point for your docker:

git clone --recurse-submodules https://github.com/Lecrapouille/SimTaDyn.git
cd SimTaDyn
Step 3: Launch the docker:

From the SimTaDyn directory, launch the following docker command which will launch an interactive bash where the root of the docker will contain the SimTaDyn project next to Ubuntu system directories:

docker run --rm -v "$(pwd):/SimTaDyn" -e LOCAL_USER_ID=`id -u $USER` -it ubuntu:18.10 /bin/bash

You should see something like:

root@8c7c0dd54f88:/#

Note that you are a root user located at the / directory (root) in your docker. 8c7c0dd54f88 is the container id. You have to know that Docker creates a dropable copy of the image (here Ubuntu 18.10), so your current image will be destroyed when leaving the docker (command exit). You can get unique ID of all your images with the following command (to type in a second console) :

docker ps -a

You'll see at least two lines (two different container id):

  • The cloned container currently used.
  • The original container.

If you quit the docker with the exit bash command. You will see that the 8c7c0dd54f88 container has been removed.

Step 4: Installing packages:

Enter back to your docker:

docker run --rm -v "$(pwd):/SimTaDyn" -e LOCAL_USER_ID=`id -u $USER` -it ubuntu:18.10 /bin/bash

If you type the ls command, you'll see the SimTaDyn directory. Go inside it. Now, still inside the docker, follow:

  • these steps for installing libraries for SimTaDyn. Note that do not have to type the sudo command because you are already the root user.
  • Compile SimTaDyn like described in short version section.
Step 5: Save your docker image:

You have to know that Docker creates a dropable copy of the image, so your current image will be destroyed when leaving the docker (command exit). If you did that you will have to install all packages that SimTaDyn depends on.

To avoid that, save your docker image (around 700 MB). In a second console type

docker commit 8c7c0dd54f88 simtadyn/setup:0.1

Where 8c7c0dd54f88 shall be your image unique ID and where simtadyn/setup:0.1 is an example of name (give a better name in your case). Check your images have been saved:

docker images

Will make appear the new image:

REPOSITORY      TAG      IMAGE ID        CREATED        SIZE
simtadyn/setup  0.1      cd9d0d272db6    2 minutes ago  732MB
ubuntu          18.10    d4452947e3fa    3 weeks ago    73.7MB

You can now exit your docker image and run up the container but this time with your new image name instead of the ubuntu name.

docker run --rm -e DISPLAY=$DISPLAY -v "$(pwd):/SimTaDyn" -e LOCAL_USER_ID=`id -u $USER` -it simtadyn/setup:0.1 /bin/bash
Step 6: Running the application:

Note: it seems that GTK+/OpenGL is buggy and displays black window. I tried two solutions but no success. This bug looks like bug with GTK+2/OpenGL on MacOS X.

1st solution

Before entering in docker, get the xauth cooky with the following line:

xauth list

Copy the output (looks like something like username/unix:0 MIT-MAGIC-COOKIE-1 9c8b471).

Now enter the docker with:

docker run --rm --net=host -e DISPLAY -v "$(pwd):/SimTaDyn" -v /tmp/.X11-unix -e LOCAL_USER_ID=`id -u $USER` -it simtadyn/setup:0.1 /bin/bash

Install the xauth package and configure it:

apt-get install xauth
xauth add <YOUR COOKY>

Where <YOUR COOKY> has to be replaced by the cooky you have copied before entering the docker.

You can launch SimTaDyn:

./SimTaDyn/build/SimTaDyn

Save your docker image if this is working for you.

2nd solution
x11docker --sharedir /path/to/SimTaDyn simtadyn/setup:0.1 ./SimTaDyn/build/SimTaDyn

Developers

These sections are optional for users but can be useful for developers. Install the following packages:

sudo apt-get update && apt-get install libcppunit-dev gcovr libglm-dev llvm-4.0-tools osc npm
sudo npm install markdown-to-html -g

RPM and debian packages.

(in gestation) SimTaDyn uses the OpenSUSE Build Service for building the project on different distributions and architectures. Go here for downloading packages. Not all distrubutions are yet made but will be done in the future. I cannot test all of them. So any feeback is welcome.

Create RPM and Debian packages

  • make obs for launching RPM and debian packages compilation with OpenSUSE Build Service. Because you'll need my password (that I'll do not give) you should adapt the script SimTaDyn/.integration/opensuse-build-service.sh for your own repo.

Compiling SimTaDyn unit tests

Address Sanitizer (aka ASAN) displays the stack trace with addresses instead of file names and file lines. For human readable traces ASAN needs llvm-symbolizer. The drawback with llvm-symbolizer in Ubuntu does not create a symbolic link to the current version. Therefore you'll have to do by yourself. For example, in Ubuntu:

sudo ln -s /usr/bin/llvm-symbolizer-4.0 /usr/bin/llvm-symbolizer

Where /usr/bin/ should be adapted to your environment and be set to your PATH. For example

echo $PATH
export PATH=/usr/bin:$PATH
echo $PATH

And optionally, for generating some expected unit test results, install the Scilab fork: ScicosLab

sudo apt-get update && apt-get install scicoslab-gtk

To compile and launch unit tests, type the following commands:

cd SimTaDyn/tests
make -j4
./build/UnitTest

Or directly:

make unit-test

If you have installed gcovr, generate html displaying the code coverage in a single Makefile command:

make coverage

The HTML files are generated in SimTaDyn/doc/coverage. Open the index.html with any kind of browser (like Firefox).

Note 1: Because Travis-CI does not allow OpenGL context, OpenGL unit tests are disable for continous intrgation. Note 2: With Travis-CI, code coverage is also made (without OpenGL unit tests). See here

Makefile options

Summary for developpers !

  • Type make help for displaying makefile options. Here main options:
  • download-external-libs Download external projects that SimTaDyn needs.
  • compile-external-libs Compile external projects that SimTaDyn needs.
  • coverity-scan Clean and compile again the project for static analysis of the code. An archive SimTaDyn.tgz is created and can be uploaded into the service Coverity Scan.
  • unit-testsCompile and launch unit tests. Then the generate code coverage report.
  • coverage Generate the code coverage html rapport.
  • run Launch the SimTaDyn executable with address sanitizer (if enabled) for dynamic analysis of the code (memory access violation).
  • doc Generate the code source documentation with doxygen.
  • targz Compress the code source into a unique tarball for backup (meaning if a backup tarball already exists it will stay intact). .git/, build/, generated documentation and other backup tarballs are ignored. The tarball name is SimTaDyn-----v.
  • obs Create and upload a tarball to the OBS OpenSuse Build Service.
  • install Install SimTaDyn project and its data in your system. You need to be root user.
  • uninstall Uninstall the project. You need to be root. Please be care of potential errors because it will call rm command.
  • clean Clean the build/ directory.
  • veryclean Clean the whole project.
  • which-gcc Display the compilator version and informations.

Note: Modifying a makefile will automaticly force a complete project compilation.