\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}
\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{0.79in}|p{2.56in}|p{1.87in}|p{1.45in}| }
\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 &  &  \\ 
\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{0.95in}|p{1.12in}|p{3.06in}|p{1.56in}| }
\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 &  \\ 
\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}

\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 Basic Text Editor and Make}

TODO

\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{Testing}

It is planned to develop more and more tests for TTool in order to improve the product quality.

\subsection{Java}

The TTool Java code is tested using the JUnit framework.

\subsubsection{Test Projects}

Test projects can be found under the \textit{test} directory of the TTool
repository. The projects are typically named
fr.tpt.ttool.tests.\textit{component $  \_  $ name} where \textit{component $ 
\_  $ name} is the name of the component of TTool being tested.

An example project is \textit{fr.tpt.ttool.tests.util}, which provides test
cases for the TTool utility classes such as those for client-server remote
communication.

\subsubsection{Executing the Tests}

\textbf{\emph{Manual Execution}}

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}

\textbf{\emph{Automated Execution}}

JUnit tests can also be launched outside the IDE for automated tests executed
for example at the beginning of a tool release. An example code snippet is
provided in the following:

\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}

\subsection{C++}

TODO

\section{Building}

TODO

\section{Installing}
TODO

\end{document}