ttool_development_infrastructure.tex

\documentclass[12pt]{article}
\usepackage{amsmath}
\usepackage{latexsym}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}
\usepackage{txfonts}
\usepackage{wasysym}
\usepackage{adjustbox}
\usepackage{ragged2e}
\usepackage{tabularx}
\usepackage{hhline}
\usepackage{float}
\usepackage{multirow}
\usepackage{makecell}
\usepackage{fancyhdr}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[a4paper,bindingoffset=0.2in,headsep=0.5cm,left=1in,right=1in,bottom=3cm,top=2cm,headheight=2cm]{geometry}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{color}

\definecolor{pblue}{rgb}{0.13,0.13,1}
\definecolor{pgreen}{rgb}{0,0.5,0}
\definecolor{pred}{rgb}{0.9,0,0}
\definecolor{pgrey}{rgb}{0.46,0.45,0.48}

\everymath{\displaystyle}
\pagestyle{fancy}
\fancyhf{}
\rfoot{Page \thepage}
\begin{document}
\sloppy 

\begin{center}
\Large Telecom ParisTech \\
\Large COMELEC Department \\
\vspace{20 pt}
\underline{\Huge Development Infrastructure for TTool}
\end{center}

\begin{table}[H]
\large
\centering
\begin{adjustbox}{width=\textwidth}
\begin{tabular}{ |p{1.6cm}|p{6.0cm}|p{4.4cm}|p{4.2cm}| }
\hhline{----}
 & \textbf{Document Manager} & \textbf{Contributors}  & \textbf{Checked by}  \\ 
\hhline{----}
\textbf{Name}   & Dominique BLOUIN & \multirow{2}{*}{Ludovic APVRILLE} &
\multirow{2}{*}{Ludovic APVRILLE} \\
\hhline{--~~}
\textbf{Contact} & dominique.blouin@telecom-paristech.fr &  &  \\ 
\hhline{--~~}
\textbf{Date} & \today & Matteo BERTOLINO &  \\ 
\hline
\end{tabular}
\end{adjustbox}
\end{table}

\newpage
\tableofcontents

% \newpage
% \listoffigures

\newpage
\section{Preface}

\subsection{Table of Versions}

\begin{table}[H]
\large
\centering
\begin{adjustbox}{width=\textwidth}
\begin{tabular}{ |p{1.5cm}|p{2.5cm}|p{9.0cm}|p{3.0cm}| }
\hhline{----}
\textbf{Version} & \textbf{Date} & \textbf{Description  $  \&  $  Rationale of
Modifications} & \textbf{Sections Modified} \\
\hhline{----}
1.0 & 17/10/2016 & First draft &  \\ 
1.1 & 10/02/2017 & Added Eclipse IDE development + tests & All \\ 
1.2 & 11/02/2017 & Added more info on tests & Tests \\ 
\hline
\end{tabular}
\end{adjustbox}
\end{table}

\subsection{Table of References and Applicable Documents}

\begin{table}[H]
\large
\centering
\begin{adjustbox}{width=\textwidth}
\begin{tabular}{ |p{2.66in}|p{2.66in}|p{0.95in}|p{0.43in}| }
\hhline{----}
\textbf{Reference} & \textbf{Title  $  \&  $  Edition} & \textbf{Author or
Editor} & \textbf{Year}
\\
\hhline{----}
 &  &  &  \\ 
\hline
\end{tabular}
\end{adjustbox}
\end{table}

\subsection{Acronyms and glossary}

\begin{table}[H]
\large
\centering
\begin{adjustbox}{width=\textwidth}
\begin{tabular}{ |p{1.24in}|p{5.45in}| }
\hhline{--}
\textbf{Term} & \textbf{Description} \\ 
\hhline{--}
 &  \\ 
\hline
\end{tabular}
\end{adjustbox}
\end{table}

\subsection{Executive Summary}

This document describes the development infrastructure that has been setup for
the development of TTool. It describes sources configuration management, the
development process with basic editor and command lines, with the Eclipse IDE,
as well as the testing, building and installation procedures.

\section{Source Configuration Management}
\label{sec:scm}

\subsection{Gitlab Server}

TTool sources are hosted on the Gitlab server of Telecom ParisTech under the
group \textit{mbe}\textit{-tools} and project \textit{TTool}. The Gitlab project
can be accessed via . Login must be performed using Shibboleth as shown in
figure~\ref{fig:image1}, using the credentials from your institution if it is a
member of the Federation Education Recherche (\url{https://services.renater.fr/federation/participants/idp}). Otherwise, please ask us for an account.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image1.png}
\end{center}
\caption{}
\label{fig:image1}
\end{figure}
 
\subsection{Basic Sources Management}

The address to access the sources is . For the time being and until further notice, we will keep using a centralized development process, like it was the case for Subversion. In this process, each developer first obtains a clone of the master remote repository. For this, go to the directory where the sources are to be downloaded and issue the following command: \\


\begin{verbatim}
git clone git@gitlab.enst.fr:mbe-tools/TTool.git
\end{verbatim}

Once modifications are made, they can be committed using command:

\begin{verbatim}
git commit -m "Commit message"
\end{verbatim}

This will only commit the changes in your local repository. In order to move them to the remote repository, use:

\begin{verbatim}
git push origin master
\end{verbatim}

More information on the use of Git can be found here: \\
\url{http://rogerdudler.github.io/git-guide/}. \\

By default, Git will ask credentials for each operation. In order to avoid this,
it is possible to upload a public SSH key at: \\
\url{https://gitlab.telecom-paristech.fr/profile/keys}.

\subsection{Bug Tracking}

The Gitlab server provides an issues tracking system to record bugs, evolutions
or support demands from users and developers. Issues can be seen at: \\
\url{https://gitlab.telecom-paristech.fr/mbe-tools/TTool/issues} \\

It is suggested to create an issue for every modification that is made to the
code, providing with the issue detailed information on the problem including
screen shots, log traces and test cases if required. This information is
important so that other developers can understand why the changes were made.
Ideally, the issue number should be mentioned within the modified code and
commit messages.  \\

\section{Development with Text Editor (emacs, vi) and Make}

The text editor of your choice can be used to edit the files of TTool. Yet, you must be sure that the correct indentation is respected. Use \textbf{4 spaces for each indentation level}.\\

Also, don't forget to insert your name at the top of the file in the authors list.\\

The main Makefile can be used to compile the source files of TTool, and to generate the jar libraries in bin/.
To compile TTool, do as follows, from the top directory of TTool:
\begin{verbatim}
$ make ttool
\end{verbatim}

Other compilation targets can be obtained with:
\begin{verbatim}
$ make help
\end{verbatim}
or:
\begin{verbatim}
$ make
\end{verbatim}
In particular, compiling the sources of all subprojects can be done with the
\textit{all} target:
  \begin{verbatim}
$ make all
\end{verbatim}



\section{Development with Eclipse}

Eclipse is a well-known Integrated Development Environment (IDE) providing many advanced functionalities to support developers and improve code quality by the application of built-in on the fly code analyses. One advantage of Eclipse is that it is a multi-platform application so it can be used on Linux, Windows and Mac. The procedures described in this section are valid for all platforms although some elements such as C++ projects need to be different due to different platform-specific compilation tool chains to be used. More information on this is provided on the concerned subsections. \\

\subsection{Installing and Configuring Eclipse}

Download Eclipse IDE for Java developers here: \\
\url{http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/neon2}
\\

Unzip the package and launch the eclipse executable. For developing C++
applications such as the DIPLODOCUS simulator, add the C Development Tools
(CDT). For this, select menu ``Help >> Install New Software''.
From the dialog box that opens, select the ``Neon'' update site, unfold the
``Programming Languages'' category and check the elements as shown in
figure~\ref{fig:image2}. Follow the wizard instructions to complete the
installation.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image2.png}
\caption{}
\label{fig:image2}
\end{center}
\end{figure}

\subsection{Online Help}

The first place to look for help is in via menu ``Help>>Help Content'' from
Eclipse. A dialog box will show a tree with branches for each integrated plugin
or application. Help is provided for the 3 plugins that are used to develop
TTool; EGit, Java Development Tools and C/C++ Development Tools.

\subsection{Source Configuration Management with EGit}

The downloaded Eclipse IDE already includes a plugin named EGit for source
configuration management using Git.

\subsubsection{Cloning the TTool Repository}

First, switch to the Git perspective by clicking menu
``Window>>Perspective>>Open Perspective>>Other''. Then select the Git
perspective as illustrated in figure~\ref{fig:image3}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.6\textwidth]{images/image3.png}
\end{center}
\caption{}
\label{fig:image3}
\end{figure}

Then clone the TTool Git repository by clicking the appropriate button as shown
in figure~\ref{fig:image4}. Specify the TTool Git repository URI
(git@gitlab.enst.fr:mbe-tools/TTool.git) and follow the wizard by also setting
the local Git repository path.

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.6\textwidth]{images/image4.png}
\end{center}
\caption{}
\label{fig:image4}
\end{figure}

The content of the cloned repository can be seen from the Git Repository view by
unfolding the ``Working Tree'' folder (figure~\ref{fig:image5}).

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.6\textwidth]{images/image5.png}
\end{center}
\caption{}
\label{fig:image5}
\end{figure}

\subsubsection{Importing the Required Projects into the Workspace}
\label{sec:import}

Two Eclipse Java projects are needed to develop TTool: the \textit{bin} project
that contains the required libraries (jars) and the \textit{src} project that
contains the source code. Install these 2 projects in the workspace by
right-clicking the ``Working Tree'' it in the Git repository view and
selecting ``Import Projects\ldots'' as shown in figure~\ref{fig:image5}.

Then select ``Import existing Eclipse projects'' as shown in
figure~\ref{fig:image6} and follow the steps of the wizard.

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.7\textwidth]{images/image6.png}
\end{center}
\caption{}
\label{fig:image6}
\end{figure}

\subsubsection{Committing, Pulling and Pushing Changes}

Committing the changes of a file or a directory or a project is performed by
selecting this element in the project navigator view then selecting
``Team>>Commit''. This will open the Git Staging view for where the changed
files are listed. Double clicking a file in the unstaged changes view will open
an editor allowing visualizing the changes (figure~\ref{fig:image7}). Right click and select
``Add to Index'', then enter a commit message and click the ``Commit'' button to
commit the changes. Pushing and pulling can be performed by selecting the repository from
the Git repository view or the elements from the project view.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image7.png}
\end{center}
\caption{}
\label{fig:image7}
\end{figure}

\subsection{Java Development}

\subsubsection{Coding and Compiling}

Switch to the Java perspective to develop TTool with JDT (select menu
``Windows>>Perspective\ldots'' or select the appropriate perspective button from
the upper right corner of Eclipse). By default Eclipse will automatically
compile all files in the project. However the provided projects have already
been configured so that only the required classes are compiled and also to use
the required library files from the \textit{bin} project.

JDT provides several advanced functionalities such as automatically navigating
from a variable to its declaration, finding its use throughout all the classes,
including refactoring capabilities, syntactic coloration, code completion, etc.

\subsubsection{Launching TTool}
\label{sec:launch}

A default launch configuration is provided with the TTool \textit{src} project.
It allows for launching TTool from the compiled code. This configuration can be
edited by opening the \textit{Run Configurations} dialog box as show in figure~\ref{fig:image8}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.9\textwidth]{images/image8.png}
\end{center}
\caption{}
\label{fig:image8}
\end{figure}

The TTool launch configuration is displayed in figure~\ref{fig:image9}. It
specifies the main class to execute as well as the program arguments, working directory and
optionally additional environment variables to be added to the default system
environment. Click \textit{Run} to launch TTool. The output from TTool will be
displayed in the console view. Once TTool has been launched once, simply
clicking the button to open the launch dialog box will directly launch TTool so
that it is not necessary to open the launch dialog box every time.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image9.png}
\end{center}
\caption{}
\label{fig:image9}
\end{figure}

\subsubsection{Using the Debugger}

In addition, JDT provides an enhanced debugger allowing executing the program
step by step with sophisticated breakpoints to control the execution and to
examine variable contents etc. However to use the debugger, the proper launch
configurations must be used by clicking the \textit{debug}
button just left of the launch configuration button of figure~\ref{fig:image8}.

\subsection{C++ Development}

One advantage of IDEs is that once a user has learned how to use a first tool,
other integrated tools are faster to learn because the tools share so much
functionality.

\subsubsection{Coding and Compiling}

Like for JDT, CDT also has its own perspective and the first thing to do is to
switch to this perspective as shown in figure~\ref{fig:image10}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=0.45\textwidth]{images/image10.png}
\end{center}
\caption{}
\label{fig:image10}
\end{figure}

For developing the TTool C++ applications with CDT, the predefined CDT projects
must first be imported into the workspace as explained in
section~\ref{sec:import}. Note that for CDT, the projects are platform dependent
due to the different compilation toolchains (Cygwin is used for Windows) so there is one project per
platform. For instance, for developing the DIPLODOCUS simulator on Linux, import
the \textit{c++}\textit{2} project. For windows, import the
\textit{c++}\textit{2 $  \_  $ windows} project (TODO to be provided later). CDT
provides the ability to define several build configurations. For the
\textit{c++}\textit{2} project, two configurations are provided as shown in
figure~\ref{fig:image11}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image11.png}
\end{center}
\caption{}
\label{fig:image11}
\end{figure}

The \textit{TTool} configuration will compile the code using the provided make
file as if the simulator were compiled from TTool. The \textit{Debug}
configuration allows for compiling TTool such that it can be executed in debug
mode. The selected button in figure~\ref{fig:image11} allows changing the configuration being
used. The hammer button on the right hand side of it allows compiling and
linking the code.

The settings for these build configurations can be edited by selecting the
\textit{c++2} project in the project navigator and clicking
``Properties''. For the \textit{Debug} configuration, the CDT internal builder
is used. This means that the compilation and linking options can be changed via
the form editor shown in figure~\ref{fig:image12}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image12.png}
\end{center}
\caption{}
\label{fig:image12}
\end{figure}

Note that the code provided by default in the \textit{c++2} project
from the Git repository does not compile by itself. TTool must first be executed
to generate the classes specific to the system being simulated. Once this is
done, the simulator can be compiled and executed from CDT for the desired build
configuration.

\subsubsection{Launching the Simulator}

Like for JDT, the launch of C++ applications can be specified using the launch
configurations dialog as introduced in section~\ref{sec:launch}. One launch
configuration is provided for each build configuration and named
\textit{c++2 TTool} and \textit{c++2 Debug}.

\subsubsection{Using the Debugger}

The CDT debugger is very similar to the JDT debugger. However to be able to use
it only the \textit{c++2 Debug} launch configuration should be used and
triggered from the \textit{Debug As} button. By default, the program execution
will automatically stop at the first instruction of the program. This behavior
can be changed by editing the debug launch configuration.

\section{Development with IntelliJ}

TODO

\section{Coding Information}
Here are gathered all tricks on how TTool source codes are organized, and what function is coded where, and also how to extend TTool, e.g. adding a new diagram.

\subsection{Coding Instructions}

\subsubsection{Best practices}

TTool is a constantly evolving project with more or less experimental parts. As
such, some leniency is expected from TTool developers and---while comments and
advice are always welcome---a perfect knowledge of best software engineering
practices should not be expected from every developers.

Nonetheless, we advise any developer to make her/his best to follow these best
practices. Indeed, the purpose of these principles is to enable the development
of easily understandable, extendable and reusable code. A good place to start if
you are not familiar with these principles is to have a look at the
\href{https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)}{SOLID}
acronym.

In particular, developers should try to:
\begin{itemize}
    \item \textbf{Avoid public attributes}. Use getters and setters instead.
        This way, if the internal representation of the class changes, only the
        getters/setters would need to be modified.
    \item \textbf{Implement all of the methods of the superclass}.
        If some of the methods of the superclass are not relevant for the
        subclass, then it should probably not inherit from it. Indeed, other
        classes that uses the superclass logically assume that all of the
        subclasses implement the functionalities of the superclass.
    \item \textbf{Use abstractions instead of concrete
        classes when possible}. For instance, if an object A of package
        \textit{avatartranslator} must use an object B of package \textit{ui},
        create an interface in package \textit{avatartranslator} that is
        implemented by B and use it in A. This would make the low-level package
        \textit{ui} depend on the high-level package \textit{avatartranslator}
        instead of the opposite (which enables to use A in a CLI application for
        instance). This principle is also valid when the abstract class and its
        implementation are in the same package: for instance, prefer using
        \textit{List} objects in function arguments instead of the
        \textit{LinkedList} or \textit{ArrayList} concrete classes so that the
        caller can choose which subtype to instantiate.
\end{itemize}

\subsubsection{Style instructions}

\begin{itemize}
\item Indentations should use 4 spaces for each indentation level.
\item Opening brackets should be at the end of the line it relates to with one
    space before the bracket.
\item There should be 1 space between an \texttt{if}, \texttt{for},
    \texttt{switch}, etc. and the following opening parentheses, but none
        between a function name and the following parentheses.
\end{itemize}

Here is an example code with correct formatting:

\begin{lstlisting}[showspaces=true, language=java, commentstyle=\color{pgreen},
keywordstyle=\color{pblue}, stringstyle=\color{pred}, basicstyle=\ttfamily]
public class Foo {
    public int[] X = new int[]{1, 3, 5, 7, 9, 11};

    public void foo(boolean a, int x, int y, int z) {
        for (int i = 0; i < 5; i++) {
            try {
                if (x > 0) {
                    int someVariable = a ? x : y;
                    int anotherVariable = a ? x : y;
                } else {
                    for (int i = 0; i < 5; i++) doSomething(i);
                }
                switch (a) {
                    case 0:
                        doCase0();
                        break;
                    default:
                        doDefault();
                }
            } catch (Exception e) {
                processException(e.getMessage(), x + y, z, a);
            }
        }
    }
}
\end{lstlisting}

Do ensure your file is correctly indented before committing/pushing it.
Preferably, configure your code editor so that these guidelines are
automatically enforced.


\subsubsection{How to output debug information}
Do as follows:
\begin{lstlisting}
TraceManager.addDev("blah blah blah");
\end{lstlisting}
Then, start TTool with the 
\begin{verbatim}
 -debug
\end{verbatim}
option.
Thus, to print information, never use:
\begin{lstlisting}
System.out.println("blah blah blah");
\end{lstlisting}
or similar ways of doing.

\subsubsection{Warnings}
TTool is compiled with the following Xlint warning flags:
\begin{itemize}
    \item unchecked
    \item deprecation
    \item cast
    \item divzero
    \item empty
    \item finally
    \item fallthrough
\end{itemize}
Before committing your changes, make sure that your code does not generate any
warning.

\subsubsection{Documentation}
Whenever it is possible, add a javadoc comment before any function, class or
field declaration. This helps future developers to quickly understand the
purpose of the related code. Note that to be valid, javadoc comments must be
placed right before the declaration and should be correctly formatted. To check
that it really is, generate the javadoc:
\begin{verbatim}
make documentation
\end{verbatim}
and make sure no warning is printed.

\subsection{Code organization}
The TTool repository actually hosts the source code of different standalone
projects. Here is a description of these sub-projects:
\begin{itemize}
    \item \textbf{ttool}. This is the main project: the TTool application with a
        graphical user interface.
    \item \textbf{graphminimize}. TODO
    \item \textbf{graphshow}. TODO
    \item \textbf{launcher}. TODO
    \item \textbf{rundse}. TODO
    \item \textbf{simulationcontrol} or remotesimulator. TODO
    \item \textbf{tiftranslator}. TODO
    \item \textbf{tmltranslator}. TODO
    \item \textbf{webcrawler}. TODO
        \begin{itemize}
            \item \textbf{client}. TODO
            \item \textbf{server}. TODO
        \end{itemize}
    \item \textbf{jttool}. TODO \textit{(Development of this project has been
        dropped)}
\end{itemize}

For each of these sub-projects, there exists a folder in the TTool repository
that contains the sources, tests, resources and runtime dependencies associated
with it. Each of the sub-projects conforms to the
\href{https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html}
{Maven Directory Layout} and the root directory itself contains an \texttt{src}
folder which contains the source code shared by multiple sub-projects and
follow the same directory layout. This means that for instance, source code
specific to the \textit{ttool} sub-project should be located under
\texttt{ttool/src/main/java}, test classes related to the \textit{rundse}
sub-projects would be under \texttt{rundse/src/test/java} and resources (such as
images) needed by shared source code would be under \texttt{src/main/resources}.
Preferably, source code that would only be needed by a particular sub-project
should not be under \texttt{src/main/java} but under
\texttt{<project>/src/main/java}. In particular, \texttt{main} methods should
not appear in the shared source code directory (\texttt{src/main/java}).

If we focus on the shared sources, we see different packages. Basically, all
graphical-related elements are put in "ui". All other subdirectories of
\texttt{src/main/java}
are used to code generic functions (\texttt{myutil}") or non graphical languages and
model transformation. For example, in \texttt{avatartranslator/} you find all classes
related to the internal avatar language, and all transformations from the
internal avatar to other languages (e.g. to UPPAAL) are in subdirectories like
\texttt{avatartranslator/touppaal}. \textbf{Note}: please strive to provide
autonomous packages that depend on as few other packages as possible. This
enables to reuse code without including unrelated classes. In particular,
non-\texttt{ui} packages should not import \texttt{ui} classes so that a CLI
application that uses features provided by the package need not import the
graphical \texttt{ui} package.

\subsubsection{User Interface directories}
Main classes are located directly in "src/ui". Subdirectories of "ui/" are mostly used for diagrams (one diagram per subdirectory, e.g. avatarbd for the Avatar Block Diagram). Other subdirectories are explained in the following table.
\begin{tabular}{l|c}
subdirectory&Explanation\\
\hline
file&Contains the definition of file extensions used by TTool\\
graph&AUT graph definition, and how to display an AUT graph\\
interactivesimulation&Graphical part of Diplodocus model simulation\\
tree&tree located in the upper left part of the main TTool Window.\\
window&Sub-windows: dialogs, frames, etc.
\end{tabular}

\subsection{Structure of the User Interface}
Actions of the main user interface are defined in "TGUIActions.java". The corresponding method which is called when an action occurs is defined in "ActionPerformer.java".

\subsection{Structure of a diagram}


\subsection{Error management}
The tree on the left contains a part dedicated to errors and warnings. The list of errors/warnings that is displayed by the tree is handled in GTURTLEModeling.java with:
\begin{lstlisting}
private List<CheckingError> checkingErrors;
private List<CheckingError> warnings;
\end{lstlisting}

\section{Testing}

It is planned to develop more and more tests for TTool in order to improve the
product quality. Test architectures are defined for each languages used to
develop TTool; Java and C++.

The testing code of TTool is located under the \textit{tests} directory of the TTool
repository and under \texttt{src/test/java} in any sub-project directory. A structure where a subdirectory is created for each
component of TTool to be tested (e.g.: Avatar, Diplodocus, shared utility
functions, etc.) is recommended. Each subdirectory can be further subdivided for
the different subcomponents of the component. For example, the Diplodocus component can be
further divided into its simulator and GUI components, which are not tested
under the same test environment and framework due to the different languages
used to develop these components.

A recommended practice consists of naming the folders containing the classes
with the same name of root package of the provided classes such as
$fr.tpt.ttool.tests.component\_name$, where $component\_name$ is the name of the
component of TTool being tested.

\subsection{Java}

The TTool Java code is tested using JUnit (\url{http://junit.org/}), which is a
unit test framework allowing to write, execute and display the results of
repeatable tests.

\subsubsection{Coding the Tests}

JUnit builds on a set of assertions for evaluating test results
and a set of annotations for qualifying test classes and methods. A test unit in
JUnit consists of a Java class grouping a set of test cases implemented as
methods of the class and identified with the $@Test$ annotation.
Other methods of the class to be executed only once before or after the
execution of all test cases of the class can be identified from the annotations
$@BeforeClass$ and $@AfterClass$. Methods to be executed before or after each
test case is executed can be identified from the annotations $@Before$ and
$@After$.

When using the Eclipse IDE, test classes can be automatically generated for a
given class to be tested and will include annotated methods for the selected
methods of the class to be tested.

See folder $test/fr.tpt.ttool.tests.util$ of the TTool source code repository
for an example test class $TestRshClient$ providing test cases for the TTool
utility class $RshClient$ used for client-server remote communications.

\subsubsection{Executing the Tests}

\textbf{\emph{Using the JUnit Execution API}}

A JUnit test class can be executed automatically by passing
it to a JUnit test runner service that will take care of calling the appropriate
methods in the appropriate order to execute the tests, and return a test result
object that can be inspected to determine the success or failure of the test
cases and provide more details in case of failure. An example code snippet is
shown below:

\begin{verbatim}
import org.junit.runner.JUnitCore;
import org.junit.runner.Result;
import org.junit.runner.notification.Failure;
import fr.tpt.ttool.tests.util.remote.TestRshClient;

public class TToolUtilTestsRunner  {

    public static void main(String[] args) {
        Result result = JUnitCore.runClasses(TestRshClient.class);

        for ( final Failure failure : result.getFailures() ) { 
            System.err.println( "Test failed : " + failure.toString() );
        }
 		
        if ( result.wasSuccessful() ) {
            System.out.println( "All tests passed." );
        }
        else {
            System.err.println( "Some of the tests failed!" );
        }
 
        System.exit( 0 );
    }
}
\end{verbatim}

It is also possible to let gradle run the tests by invoking it:
\begin{verbatim}
gradle test
\end{verbatim}
or
\begin{verbatim}
gradle :ttool:test
\end{verbatim}

for a specific sub-project.

A report is then generated under
\texttt{<project>/build/reports/tests/test/index.html}.

\textbf{\emph{Within the Eclipse IDE}}

Like for C++ and Java applications, JUnit launch configurations can be defined
in Eclipse as shown in figure~\ref{fig:image13}. This configuration will execute all unit tests
for class \textit{RSHClient} and display within the IDE a view of the status of
the tests (passed of failed) as shown in figure~\ref{fig:image14}.

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image13.png}
\end{center}
\caption{}
\label{fig:image13}
\end{figure}

\begin{figure}[H]
\begin{center}
\includegraphics[width=\textwidth]{images/image14.png}
\end{center}
\caption{}
\label{fig:image14}
\end{figure}

\subsection{C++}

TODO

\section{Building}

\subsection{Compiling and Packaging}

First obtain the TTool repository from the Gitlab server as explained in section
\ref{sec:scm}. From a Linux shell, CD to the root TTool directory and execute
\emph{make all} to compile the code. If the compilation fails with the following error:
``unmappable character for encoding ASCII'', you need to do:

\emph{export JAVA\_TOOL\_OPTIONS=-Dfile.encoding=UTF8} \\

For generating a release, execute \emph{make release}.

\subsection{Gradle}
The TTool project has been configured so that it can be built with the
\href{https://gradle.org/}{Gradle Build Tool}. To this end, a
\texttt{build.gradle} file
is present in the root folder and each sub-project directory. Each
\texttt{build.gradle} file describes how to compile and package the related
sub-project and the \texttt{build.gradle} in the root folder describes shared
configuration. They should be modified when the compilation for a project
changes. In particular:
\begin{itemize}
    \item If a .jar library should be added to the classpath
    \item If a source folder should be added to the sourcepath
    \item If a javac flag should be added or removed
\end{itemize}

There is another gradle configuration file in the root folder of TTool:
\texttt{settings.gradle}. The purpose of this file is to list the sub-projects
of TTool. It should thus be modified when a new sub-project is created or if you
want a sub-project not to be compiled when calling \texttt{gradle build}.

In order to build all projects, run:
\begin{verbatim}
gradle build
\end{verbatim}
or 
\begin{verbatim}
gradle :ttool:build
\end{verbatim}
if you only want to build TTool.

\subsection{Executing TTool}
When TTool is executed, it fetches configuration settings from a
\texttt{config.xml} file and modifies it when closed. When you build TTool, a
default \texttt{config.xml} file is copied from
\texttt{ttool/runtime/config.xml} to \texttt{bin/config.xml}. As the
\texttt{bin} folder is not tracked by git, you can modify this configuration
file without committing your personal changes to the distant repository---which
you should not do. However, building TTool once again would replace your
personal \texttt{bin/config.xml} with the generic
\texttt{ttool/runtime/config.xml}, losing the changes you made on your
configuration file.

A better way to use your personal configuration file through different TTool
builds is to keep your own copy of \texttt{config.xml} outside of the
\texttt{bin} folder (which is removed when calling \texttt{make ultraclean}).
You can either create your own configuration file anywhere on the repository and
be careful not to add it to be tracked by git, or put it in a location where it
would not appear when doing a \texttt{git status}: either outside of the TTool
folder, or in a \texttt{.ttool} subdirectory which is explicitly ignored by git:
\begin{verbatim}
$ mkdir .ttool
$ cp ttool/runtime/config.xml .ttool/
\end{verbatim}
You could thus either call ttool directly:
\begin{verbatim}
$ java -jar bin/ttool.jar -config .ttool/config.xml
\end{verbatim}
or copy \texttt{ttool.exe} to \texttt{.ttool} subdirectory and modify it:
\begin{verbatim}
$ cat .ttool/ttool.exe
#!/bin/sh

java -version
cd .ttool;
java -Xmx1024m -Djavax.net.ssl.trustStore=ServerKeyStore \
    -Djavax.net.ssl.trustStorePassword=123456  -jar ../bin/ttool.jar \
    -config config.xml -experimental -debug -avatar -uppaal -launcher

$
\end{verbatim}

\subsection{Automated Tests}
TODO

\section{Installing}
TODO

\section{Adding a graphic component}
This section addresses the adding of a specific graphical component (i.e., the FPGA), that is part of the set of \textit{computational units} such as CPUs, but the steps listed are valid for any kind of graphical component like memories or communication systems. Remember to git add each new file that you create! Remember also to change properly the \texttt{import} at the beginning of a class if necessary. Adding a new component requires a serie of steps listed ad follows: 

\paragraph{Deployment diagram:} The complete list of diagrams is located in \texttt{.src/ui} directory. In order to add a graphical component we are interested in \textit{TML Deployment Diagrams} that are in \texttt{.tmldd} subdirectory. Since FPGAs' models have lots of analogies with CPUs' models, we duplicated the class TMLArchiCPUNode.java naming it TMLArchiFPGANode.java. The main changes to do in this new class are: 
\begin{itemize}
\item Change the \texttt{String stereotype} value
\item Modify the list of attributes adding or removing items: for example, we do not need the parameter \textit{number of cores} to describe the FPGA, so we removed \texttt{private int nbOfCores = HwCPU.DEFAULT\_NB\_OF\_CORES;}
\item On the other hand we need for a parameter that expresses the \textit{capacity} of the FPGA in terms of area, so we added 
\texttt{private int capacity = HwCPU.DEFAULT\_CAPACITY;}
\item Let's change the graphic parameters as you wish: the connecting points, the fact to make the diagrams editable, etc
\item Handle the lines like \texttt{if (dialog.getNbOfCores().length() != 0)} according with your previous modifications on the perameters' list. You can notice the usage of the \texttt{tmp} variable to recover the values in the case that the user closes the window.
\item The method \texttt{public int getType()} return an unique ID, defined in \texttt{TGComponentManager.java}. Change the method, then open the new class and add the new id with an associated number (e.g., \texttt{public static final int TMLARCHI\_FPGANODE = 1116;}). You have to choose an available number!
\item Modify the \texttt{protected String translateExtraParam()} method useful to save in xml the attributes whose default value was changed.
\texttt{sb.append("<attributes capacity=\"" + capacity + "\" byteDataSize=\"" + byteDataSize + "\" ");}
\item Modify the \texttt{getAttribute()} methods according to the new parameters. These methods are useful for the action \textit{Show/Hide element attributes} triggered by an icon in the architectural diagram.
\item In \texttt{TGComponentManager.java} you have also to add the new value that the \texttt{tgc} variable (that represents the graphical component) can take: \begin{verbatim}
 case TMLARCHI_FPGANODE:
                tgc = new TMLArchiFPGANode(x, y, tdp.getMinX(),
                      tdp.getMaxX(), tdp.getMinY(), tdp.getMaxY(),
                      false, null, tdp);
                break;
\end{verbatim}

and 

\begin{verbatim}
else if (tgc instanceof TMLArchiFPGANode) {
            return TMLARCHI_FPGANODE;
\end{verbatim}
\end{itemize}

\paragraph{Icon:} 
\begin{itemize}
\item icons are stored in \texttt{.src/main/resources/ui/util}. You can easily use GIMP to create one of them, modifying an existing one to be sure to fit the proper dimensions.   
\item The class \texttt{.src/main/java/ui/util/IconManager.java} is responsible to charge the icons. Let's assign a number to our icon. The convention is: an odd number for the \textit{big} sized icons, an even number for the \textit{small} sized icon. So, we assigned number 1120 to our new fpga icon: \texttt{private static String icon1120 = "tmlfpganode.gif";}
\item Next to the \texttt{//TDD} comment, create an object icon: \texttt{public static ImageIcon imgic1120;}
\item Associate the icon object to the previously defined string value: \texttt{imgic1120 = getIcon(icon1120);} 
\end{itemize}

\paragraph{Associate an action to the icon: } The actions' list is contained in the file \texttt{.src/main/java/ui/TGUIAction.java}.
\begin{itemize}
\item The first step is to associate a unique number to the action that we aim to create. Let's search in the code for the parameter \texttt{public static final int NB\_ACTION = 474;}. All the actions are in a table named \texttt{private static final TAction [] actions = new TAction[NB\_ACTION];}. So, the number associated to our action should be equal to the number present in \texttt{NB\_ACTION}. Moreover, we need to reserve one more space for the action in the table, so we increment \texttt{NB\_ACTION} by one. In this case, \texttt{public static final int NB\_ACTION = 475;}.
\item Declare the action: taking inspiration from \texttt{public static final int TMLARCHI\_CPUNODE = 218;}, similarly we create \texttt{public static final int TMLARCHI\_FPGANODE = 474;}
\item Then, add the action to the table, with the previously defined icon and a short description: 
\begin{verbatim}
actions[TMLARCHI_FPGANODE] = new TAction("add-tmlarchi-fpganode", 
       "Add a FPGA node", IconManager.imgic1120, 
       IconManager.imgic1120, "FPGA node", "Add a fpga node to the 
       currently opened DIPLODOCUS architecture diagram", 0);
\end{verbatim}

\item Finally, it is necessary to create the graphic component of such ID when this action on a FPGA node is triggered. To do that, open \texttt{.src/main/java/ui/ActionPerformer.java} and search for the string \texttt{CPUNode}. Then, similarly add \begin{verbatim}
else if (command.equals(mgui.actions[TGUIAction.TMLARCHI_FPGANODE]
		.getActionCommand())) {
            mgui.actionOnButton(TGComponentManager.COMPONENT, 
            TGComponentManager.TMLARCHI_FPGANODE);
\end{verbatim}

\end{itemize}

\paragraph{Show/Hide the icon: } the icon is not still present in the GUI. 
\begin{itemize}
\item Open \texttt{.src/main/java/ui/tmldd/TMLArchiDiagramToolBar.java}
\item Set the icon as active: 
\begin{verbatim}
  protected void setActive(boolean b) {
     //[...]
     mgui.actions[TGUIAction.TMLARCHI_CPUNODE].setEnabled(b);
     mgui.actions[TGUIAction.TMLARCHI_FPGANODE].setEnabled(b);
     mgui.actions[TGUIAction.TMLARCHI_HWANODE].setEnabled(b);		
     //[...]
	}		
		\end{verbatim}
Notice that the order is important! For example, we aim to place the FPGA icon before the HWACC icon and after the CPU node. Let's notice also that in order to add the icon we do not manipulate the icon object, but the action!  
\item Since the implementation of the FPGA block is not still ready when we realized the graphical block, we aim to hide the icon and make it available only running TTool/DIPLODOCUS with the flag \texttt{-experimental}. So, within the same class we can add the condition:
\begin{verbatim}
if (mgui.isExperimentalOn()) {
            button = this.add(mgui.actions[TGUIAction.
                     TMLARCHI_FPGANODE]);
            button.addMouseListener(mgui.mouseHandler);
        }
\end{verbatim}
\item Finally, we need to define the behavior of the method \texttt{isExperimentalOn()}. To do that, let's go in the class (\texttt{.src/main/java/ui/MainGUI.java}) and add it: 
\begin{verbatim}
    public boolean isExperimentalOn() {
        return experimentalOn;
    }
\end{verbatim}
\end{itemize}

\paragraph{Towards TML: step 1} All the \textit{hardware FPGA} blocks have the parameter defined in a virtual component that does not take into account it graphical items but it is expressed in an intermediate language, TML. 

\begin{itemize}
\item Let's have a look to \texttt{src/main/java/tmltranslator/HwCPU.java} and copy/paste it renaming the file \texttt{src/main/java/tmltranslator/HwFPGA.java} (don't forget to change the imports, as usual).
\item Modify the class according with your previous operations. In particular, the list of attributes shall be coherent with the attributes already declared, so in our case we removed stuff related to the number of cores and we added those to represent the FPGA like the capacity. Then set their default value. Modify \texttt{toXML()} (useful for the plugin) and \texttt{getType()} methods as well. 
\item Some attributes seems miss, like \texttt{EXECI} and \texttt{EXECC}. Let's check to the father class \texttt{HwExecutionNode.java}, in the same package.
\end{itemize}

\paragraph{Dialog box: } then, we already defined almost all the graphical stuff like connectors, name displayed, etc. When we click on the component, a dialog box appears. We can use it to assign a value to the declared attributes, or to check their default value. The classes that handle the dialog box are usually in \texttt{.src/main/java/ui/window}. Some complex components have these classes in their own subdirectories. 
\begin{itemize}
\item Let's have a look to \texttt{JDialogCPUNode.java}, copy/paste it, git add and modify the import
\item Let's modify properly this new JDialog class. For example, we modified the JText fields and the getters in accordance to the declared parameters, we modified the constructor and we removed the stuff in which we're not interested on. The latter includes the things related to the MEC (useful for the code generation), tracemode, the useless grids, everything after the getters. 
\end{itemize}

\paragraph{Towards TML: step 2} To translate graphical TML modeling to  "tmlmodeling" we rely on the class \texttt{.src/main/java/ui/GTMLModeling.java}. Exactly as \texttt{HwCPU cpu;} and \texttt{TMLArchiCPUNode node} we declared \texttt{HwFPGA fpga;} and \texttt{TMLArchiFPGANode fpgaNode}. Then, getting inspiration by the code that concerns the first two variables, add the equivalent code for FPGA.