INSANE DEVELOPMENT KIT

INSTALLATION GUIDE

Version: July 31, 2020

 1

Contents
1 Introduction 2
1.1 INSANE Standard Development Kit . . . . . . . . . . . . . . . . . . 2

2 Pre-installation 2

3 Installation 3
3.1 Setting environment variables . . . . . . . . . . . . . . . . . . . . . . 4
3.2 Installing Checkstyle plug-in . . . . . . . . . . . . . . . . . . . . . . 7

4 Configuration 7
4.1 Setting text encoding to UTF-8 . . . . . . . . . . . . . . . . . . . . . 7
4.2 Setting Git user attributes . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3 Setting the JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 Setting up the workspace 10

5.1 Cloning the remote repository . . . . . . . . . . . . . . . . . . . . . . 10
5.2 Configuring Maven plug-in . . . . . . . . . . . . . . . . . . . . . . . 10
5.3 Creating and importing projects to Eclipse . . . . . . . . . . . . . . . 12
5.4 Building the projects . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.5 Activating Checkstyle . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.6 Configuring indentation, tabbing and other formatting settings . . . . 16
5.7 Configuring “Organize Import” . . . . . . . . . . . . . . . . . . . . . 16
5.8 Configuring the native library OpenGL . . . . . . . . . . . . . . . . . 17

6 Running INSANE 18

7 Using Git 18
7.1 How to update a branch from master . . . . . . . . . . . . . . . . . . 19
7.2 How to create a merge request . . . . . . . . . . . . . . . . . . . . . . 27

8 Rules for developers 32

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 2

1 Introduction
In this guide, details regarding the installation, configuration and the use of the
programs used by the INSANE development team will be illustrated, as well as
the necessary procedures for the communication with the version control remote
repository.

1.1 INSANE Standard Development Kit

The set of programs used by the INSANE development team is labelled as INSANE
Standard Development Kit (SDK).
Its main components are:

ˆ Eclipse IDE for Java developers - www.eclipse.org

ˆ Java OpenJDK - Version 11 or above - https://openjdk.java.net/

Advanced users should also install the complete versions of Maven and Git, not
only the versions embedded in Eclipse IDE for Java developers. However, this
guide will not present the instructions for this.

2 Pre-installation
If you are reinstalling the programs and wishes to make a clean install,you must
delete the .insane, .m2, .eclipse, .p2 and .tooling folders located in your HOME directory.
The location of HOME directory varies depending on the operating system, as
follows, in which [username] is your username:

ˆ Windows - C:\Users\[username]

ˆ macOS - /home/[username]

ˆ Linux - /Users/[username]

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 3

3 Installation
The first step consists in downloading the necessary files to the installation of the
INSANE SDK. When downloading the files, verify their compatibility with your
operating system, and make sure that they are the most up-to-date versions.
Make sure you download the Eclipse IDE for Java Developers package
or the Eclipse Installer.

Windows In order to install the Java package, just extract the downloaded file to
a folder of your choice. If you downloaded the Eclipse Installer, execute it and choose
Eclipse IDE for Java Developers during install. Then, follow the instructions on
screen. If you downloaded the Eclipse package, just extract the files to a folder of
your choice.
It is recommended to extract Eclipse to a folder named Eclipse.

Figure 1: Eclipse Installer

macOS In order to install the Java package, just extract the downloaded file to a
folder of your choice. If you downloaded the Eclipse Installer, execute it and choose
Eclipse IDE for Java Developers during install. Then, follow the instructions on

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 4

screen. If you downloaded the Eclipse package, just extract the files to a folder of
your choice.
It is advisable to create folders named Java and Eclipse in the directory
Applications of your system, and extract the files in it. If the directory
Applications is used, the environment variables of the system don’t need
to be configured.

Linux Most Linux distributions are already installed with the Java. To check if
it is installed and which version, just type the following command on a terminal
window: java -version
If it is not installed, you should refer to dedicated guides (for example, Ubuntu).
In Debian based distributions, like Ubuntu, the following command install Java 11):

sudo apt install openjdk-11-jdk

If you downloaded the Eclipse Installer, execute it and choose Eclipse IDE for
Java Developers during install. Then, follow the instructions on screen. If you
downloaded the Eclipse package, just extract the files to a folder of your choice.

3.1 Setting environment variables

In order to make the executable files of the programs globally accessible by the op-
erating system, it is necessary to configure the environment variables. The different
procedures for systems based on Windows, macOs and Linux are described.

Testing the Configuration You can check the configuration of the variables
just by typing the command java -version in the terminal. If the configuration is
correct, a message similar to the one of Figure 2 should appear.

Windows To configure the environment variables in Windows, access Control

Panel → System and security → System → Advanced system configurations and, in
the section Advanced, access Environment Variables (Figure 3a). In Windows 10,

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 5

Figure 2: Testing the environment variables configuration

just type environment variables in the search box and click the Edit system
environment variables link which will be shown.

(a) System Properties (b) Setting user variable

Figure 3: Environment variables definition

In the section User Variables, create a new variable named JAVA_HOME, defining
its value with the path of the installation directory of the Java Development Kit
(for example: C:\ProgramFiles\Java\jdk-11.0.2), (Figure 3b).
In the section System Variables, edit the variable Path, by adding the installation
path of Java, followed by \bin (for example: C:\ProgramFiles\Java\jdk-11.0.
2\bin).
Modify this path according to your system.
In order to make the new configurations effective, restart your system.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 6

macOS If the programs were installed according to the previous procedures, the
environment variables should be already configured.
If needed, it can be done by editing the file .bash profile. Open the terminal
and execute the command vi ∼/.bash profile to open the file in the Vi text
editor. Press the i key in order to insert a new text in the file, and add the following
lines, modified according to the existing paths:

export JAVA_HOME="/System/Library/Java/JavaVirtualMachines/
jdk-11.jdk/Contents/Home"
export PATH=\${PATH}:\$JAVA_HOME/bin

Press the esc key to exit edit mode and type :wq to save the modifications and
close the file.

Linux The configuration of the environment variables in a Linux system requires

the modification of the /etc/profile file, that must be accessed as a superuser.
If the installation of Java was done with the automatic procedure described in the
previous section, there should be no need to configure the JAVA HOME variable.
In case you need to configure this variable, open the terminal and type the
command sudo gedit /etc/profile, in order to open the profile file with the
gedit text editor. Once you have opened the file, add the following lines, modified
according to the existing paths:

JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
ECLIPSE_HOME=/usr/local/eclipse
export JAVA_HOME ECLIPSE_HOME
PATH=\$PATH:\$JAVA_HOME/bin:\$ECLIPSE_HOME
export PATH

There is no need to restart the system.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 7

3.2 Installing Checkstyle plug-in

To install the Checkstyle plug-in, a feature called Eclipse Marketplace will be used.
Start Eclipse and set the working directory (usually a folder named workspace
in your HOME directory). Open the Help menu and select Eclipse Marketplace. In the
dialog which will open, make a search for Checkstyle. Select the Checkstyle plug-in
and click Install (Figure 4). Accept the license agreement and continue until Eclipse
requests to be restarted.

Figure 4: Installing Checkstyle plug-in via Eclipse Marketplace

4 Configuration

4.1 Setting text encoding to UTF-8

All text files in INSANE must be encoded in UTF-8. To set Eclipse to automatically
do this, go to Window → Preferences → General → Workspace and set Text file
encoding to UTF-8 and New text file delimiter to Unix (Figure 5a).
Also, go to Window → Preferences → General → Content types, select Text and
write UTF-8 at the Default encoding field (Figure 5b). Click Update, then OK.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 8

(a) (b)

Figure 5: Setting text encoding to UTF-8

4.2 Setting Git user attributes

To set the Git user name and e-mail, go to Window → Preferences → Team → Git
→ Configuration.
Create these two entries, by clicking Add entry button and filling the dialog with
your name and e-mail (Figure 6a):

ˆ Key = user.name / Value = [your name]

ˆ Key = user.email / Value = [your e-mail]

The e-mail must be the same as set in your user account at InsaneLab.
Check if the entries were successfully saved (Figure 6b).

4.3 Setting the JRE

By default, Eclipse is set to use a JRE (Java Runtime Environment) which is not
part of a JDK (Java Development Environment). However, some of the features
used by the INSANE SDK require the use of a JRE from a JDK.
To configure an adequate JRE, go to Window → Preferences → Java → Installed
JREs, select the JRE which is set and click Edit (Figure 7a). In the following dialog,

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 9

(a) (b)

Figure 6: Setting Git user attributes

change the path of the JRE home to a JRE inside a JDK (for example, in Windows,
C:\ProgramFiles\Java\jdk-11.0.2) (Figure 7b). Click Finish, then OK.
It is recommended that you have only one JRE set. If you have more
than one, you may have to change some configurations for Maven plug-in.

(a) (b)

Figure 7: Setting the JRE

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 10

5 Setting up the workspace

5.1 Cloning the remote repository

Start Eclipse and open the Git perspective by going to Window → Perspective →
Open perspective → Other and selecting Git. Then, select Clone a Git repository.
Fill the URI field with https://git.insane.dees.ufmg.br/insane/insane.
git. Leave all other fields with their default values (Figure 8a). Click Next. In
the next window, select all the branches you want to clone (branch master is the
main branch and must be cloned) (Figure 8b). Click Next again. Do not change any
value in the next window and click Finish (Figure 8c). The remote repository will
be cloned to your local machine. It can take some time. When finished, the local
repository file structure will be displayed (Figure 8d).

5.2 Configuring Maven plug-in

At least three tasks must be created: eclipse:eclipse (creates Eclipse projects,

based on the repository files), install (builds the projects and installs the snap-
shots) and clean (removes the compiled classes and the snapshots).
To create them, open the Java perspective by going to Window → Perspective
→ Open perspective → Other and selecting Java (default). Then, go to Run → Run
configurations. Select Maven build and click the New launch configuration button
(Figure 9a). Complete the following fields as below, where [HOME] is the path to
your home directory (Figure 9b):

Name: eclipse_eclipse
Base directory: [HOME]\git\insane
Goals: eclipse:eclipse
User settings: [HOME]\git\insane\pom.xml

This will set the eclipse:eclipse task. To set the others, select the eclipse:eclipse
task, click the Duplicate button, and change the Name and Goals fields to install

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 11

(a) (b)

(c) (d)

Figure 8: Cloning Git repository

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 12

to create the install task and clean to create the clean task (both fields with the
same value).

(a) (b)

Figure 9: Configuring Maven plug-in

5.3 Creating and importing projects to Eclipse

To create the projects, go back to Run → Run configurations, select the eclipse_eclipse
task and click the Run button. Maven will run and the output will be shown in
Eclipse console. When finished, if no problems occurred, the message Build success
will be displayed (Figure 10). The first time this task is run, it will download many
required packages from the Internet.

Figure 10: Creating projects with Maven plugin

Now, go to File → Import → General → Existing projects into workspace click Next
(Figure 11). In the following dialog, set the Select root directory to the INSANE

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 13

directory root and click Finish. The projects will appear in the Package explorer view
of Eclipse(Figure 12).

Figure 11: Installing projects (1)

5.4 Building the projects

To build the projects, just run the install task created, by going to Run → Run
configurations, selecting the install task and clicking the Run button. Maven will
run and the output will be shown in Eclipse console. When finished, if no problems
occurred, the message Build success will be displayed. The first time this task is
run, it will download many required packages from the Internet.
In case a problem occurs, clean the building by running the clean task
and re-run the install task till the procedure results in the message Build
success.

5.5 Activating Checkstyle

The Checkstyle configuration used in INSANE is the Google Java Style with some
modifications. These rules are saved in a file named InsaneChecks.xml located at the
top directory of the repository.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 14

Figure 12: Installing projects (2)

To define this style, go to Window → Preferences → Checkstyle, and click the

New button. (Figure 13a).
In the dialog, select the following, and then press OK:

Type: External Configuration File

Name: Insane Checks
Location: [HOME]\git\insane\InsaneChecks.xml

Next, select the Insane Checks configuration, click Set as Default and then press
OK.
To finalize the activation of Checkstyle, select all projects (Ctrl + A), right-click
them and select Checkstyle → Activate Checkstyle (Figure 13d). Repeat the process,
but selecting Check code with Checkstyle at the end.
All files will be rebuilt, and the Checkstyle warnings, if any, will be show at
Problems view in Eclipse.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 15

(a) (b)

(c) (d)

Figure 13: Activating Checkstyle

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 16

5.6 Configuring indentation, tabbing and other formatting

settings

In INSANE, indentation must be done using spaces, not tabs. and the indentation
size must be 2.
To configure this and all other formatting settings, go to Window → Preferences
→ Java → Code style → Formatter and click Import (Figure 14).
Select the the file [HOME]\git\insane\InsaneFormatter.xml and press Apply
and Close button.
When editing a file in Eclipse, just press ctrl + shift + F (or the adequate shortcut
for the OS in use) to format the file according to the project rules.

Figure 14: Configuring formatter.

5.7 Configuring “Organize Import”

To configure the “organize import” order, go to Window → Preferences → Java →

Code style → Organize Imports and click Import (Figure 15).
Select the the file [HOME]\git\insane\Insane.importorder and press Apply

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 17

and Close button.

When editing a file in Eclipse, just press ctrl + shift + O (or the adequate shortcut
for the OS in use) to organize the imports section according to the project rules.

Figure 15: Configuring “organize imports”.

5.8 Configuring the native library OpenGL

Since commit 08a94925, from 28/08/2018, this step is no longer necessary.

However, out of date branches may need this.

The OpenGL (Open Graphics Library) is a library of functions and data struc-
tures for accessing the graphic hardware. This interface basically consists of a set
of functions that can be used to specify objects and operations necessary to the
production of 3D interactive applications. Below, the steps for its configuration are
described.
Right-click the project ui.rich.full, select Properties. In the next window,
select Java Build Path → Source. In this section, select Native library location, inside
the package ui.rich.full/src/main/java and click edit (Figure 16a).

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 18

In the next window, click Workspace and follow the path ui.rich.full/src/
main/resources/br/ufmg/dees/insane/ui/rich/full/jogl_2.3.2-patched. Choose
the JOGL version compatible with your operating system and click OK (Figure 16b).

(a) (b)

Figure 16: Configuring OpenGL

6 Running INSANE
To run INSANE, select the Insane.java class from br.ufmg.dees.insane.ui.rich.full pack-
age in ui.rich.full project, right-click it and select Run as → Java application (Fig-
ure 17).
The INSANE graphical user interface will be displayed and the system can al-
ready be used in its most up-to-date version.

7 Using Git
More sections must be added!

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 19

Figure 17: Running INSANE

7.1 How to update a branch from master

It is usual that after creating a branch (newBranch, in this example) from another
one (master, in this example) the original branch continues to be developed (Fig-
ure 18). It is important to integrate these modifications to the new branch, in order
to keep it up to date with the new improvements. The merge command is the best
way to do this.
The following steps show how to merge master into newBranch.
1 – Be sure to be working in the branch that will receive the modifications
(checkout this branch – the sign must be on the desired branch). The newBranch
must be clean (all changes already committed) and the master branch must be up
to date.
2 – Right-click the branch and choose Merge. . .
3 – In the dialog, select the branch to merge into newBranch: in this example,
select master. Keep the other options as shown in Figure 21. Click Merge button.
4 – If there is no conflicts, the following dialog, with the Result: Merged text,
will be displayed.
4a – Checking the branches history, it is possible to see that the braches were

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 20

Figure 18: Branches history – note the new commits (1f5cf6b and 30476fa) in master,
after the creation of newBranch.

Figure 19: newBranch checked out.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 21

Figure 20: Merge command.

successfully merged and a new commit (4fa98f8) was created.

5 – If the same line of a file was modified in both branches, Eclipse will indicate
that there is a conflict (Result: Conflicting). These conflicts must be manually solved.
5a - In Git perspective, the existence of conflicts is also displayed.
5b – In Java perspective, the files with conflicts are marked with the sign.
5c – In the file, the conflicting lines are marked with the <<<<<<<, ======= and
>>>>>>> tags.
The lines between <<<<<<< and ======= are the ones from HEAD revision (from
master). The lines between ======= and >>>>>>> are the ones from newBranch.
The user must choose manually which lines shall remain and delete the others.
IMPORTANT: the lines with the tags (<<<<<<<, ======= and >>>>>>>) must be
also deleted!
5d – After resolving all conflicts from all files, the user must go back to Git
Staging tab. Note that the file with conflict is unstaged (Figure 28). Add this file

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 22

Figure 21: Merge command dialog.

Figure 22: Merge result, no conflicts.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 23

Figure 23: Merged branches.

Figure 24: Merge result, conflicting.

Figure 25: Git perspective, conflicting.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 24

Figure 26: Java perspective, conflicting.

Figure 27: Conflict marks in file.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 25

to the index (move it to the Staged Changes area). A standard commit message will
be created (Figure 29). It is recommended to not change this message. Then, press
Commit.

Figure 28: Conflicting file in unstaged area.

5e - Checking the branches history, it is possible to see that the braches were
successfully merged and a new commit (daef43a) was created.
Note 1: The commits SHA1 hashes shown in this example are for these commits
only. Each different commit will have a unique SHA1 hash.
Note 2: Even if the user chooses to keep the branch version during conflict
solving, master is not modified. If the master branch must be corrected, as it is
protected in the remote repository, the user must create a Merge Request in Insane
GitLab, as explained in section 7.2

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 26

Figure 29: Conflicting file staged, standard commit message created.

Figure 30: Merged branches after conflicts solving.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 27

7.2 How to create a merge request

The master branch is protected in the INSANE remote git repository, that is, only
authorized users can write in it (actually, the supervisors professors). So, if a user
makes some modifications to her local master branch, she will not be able to push
them to the remote.
Then, how can a user make her work available to others (send them to master)?
The user must create a merge request using Gitlab, which will be reviewed by her
supervisor and, if approved, the modifications will be merged into master.
The following steps show how to create a merge request.
1 – Merge master into your branch (see section 7.1). This is important to solve
all conflicts between branches locally.
2 – Log in to Gitlab: access http://git.insane.dees.ufmg.br and use your
InsaneLab credentials Figure 31.

Figure 31

3 – After login, enter the INSANE project by clicking on its name Figure 32.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 28

Figure 32

4 – On top of page, click Merge Requests Figure 33.

5 – Then, click New merge request button Figure 34.
6 – Choose the source and target branches. Click compare branches and continue
button Figure 35.

– Source branch: the branch with modifications

– Target branch: the master branch

7 – Fill the title and description fields with suitable content. In Assignee field,
choose the person responsible for reviewing your merge request. It should be your
supervisor or someone assigned by him. Then, click Submit merge request button
Figure 36.
8 – The assigned person will receive an e-mail about the creation of this merge
request. This person must review the modifications (logic, style, tests, etc.) and
approve it or not.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 29

Figure 33

Figure 34

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 30

Figure 35

In case the request is not approved, the reviewer can write back the reasons
for this and suggest improvements. As long as the request in not set closed, the
communication can be done via Gitlab and a new merge request should not be
created.
Note: It is also possible to merge any two branches using this feature. It is
advisable when the developer wants her modification to be reviewed by someone
before merging.

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 31

Figure 36

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br
 32

8 Rules for developers

ˆ Keep you local repository up-to-date, even if you are working in a separate
branch.

ˆ Properly comment your code. Remember that others will use it and you will
not be always available to explain what you have done.

ˆ Use English language for commenting.

ˆ Before pushing to the remote repository, make sure your code is building.

ˆ Don’t forget to follow the code style.

Have fun!
INSANE development team

INSANE - Interactive Structural Analysis Environment

http://www.insane.dees.ufmg.br